dita-fa-edboard - Greg's progress on dita.xml.org

Greg's progress on dita.xml.org

[ Lists Home | Date Index | Thread Index ]

To: <dita-fa-edboard@lists.xml.org>
Subject: Greg's progress on dita.xml.org
From: "Carol Geyer" <carol.geyer@oasis-open.org>
Date: Mon, 6 Mar 2006 07:57:04 -0500
Thread-index: AcZA2TizoO/nKU3hQPabb+8Spc84ZQAQ76Ng

From: Greg Rundlett [mailto:greg.rundlett@oasis-open.org]
Sent: Sunday, March 05, 2006 11:50 PM
To: Carol Geyer
Cc: Patrick Gannon; Robin Cover; Greg Rundlett; Stephen Glines
Subject: dita.xml.org

Hi Carol,

I'm sure you'll be happy to see the amount of work and progress on DITA.xml.org. You'll likely want to distribute all or most of this information to the Editorial Board. Now that the site has the infrastructure (added modules), definitions, and configuration settings to support what we have in mind, the main work between here and launch is to do 'clean-up' and adjustments to the content and configurations now that we can actually see an implementation of the code. As always there are many choices to be made in the selection, installation, configuration of functional components. I believe I have captured the essence of what you've described in terms of the goals for the site, and have provided the required features in a compressed cycle of requirements gathering, feasibility analysis, technical implementation and communication back to you for content implementation plus policy setting.

Taxonomy (Content Categories)

For the purpose of organizing site content by category, I created a new 'vocabulary' using the Drupal taxonomy system. The new 'vocabulary' is called 'Submission Category' and all the terms are listed below.

Name	Type	Operations
Submission Category	personal blog entry, calendar event, news, testimonial, resource, product, service, case study, page, story, collaborative story	edit vocabulary	add term	preview form
Case Studies (edit term) News (edit term) Products and Services (edit term) -- Products (edit term) ---- Content Management (edit term) ---- Content Versioning (edit term) ---- DITA map editor (edit term) ---- DITA Reference Manager (edit term) ---- Member Provided (edit term) ---- Open Source (edit term) ---- Publishing (edit term) ---- Workflow Management (edit term) ---- WYSIWYG editor (edit term) ---- XML Editor (edit term) -- Service (edit term) ---- Member Provided (edit term) ---- Open Source (edit term) Testimonials (edit term) Resource Directory (edit term) -- Presentations (edit term) -- Websites (edit term) -- Publication (edit term) -- Mail Lists and Forums (edit term) -- Other Materials (edit term)

I noticed what appears to be an earlier attempt to create some of these same terms in a vocabulary called 'Product features'... that vocabulary can be deleted, or we can review to be sure that all the terms are present (with descriptions, synonyms, etc) as needed in one vocabulary.

For editing the taxonomy (admins? only) see
http://dita.xml.org/admin/taxonomy

Admin tip:
Hover over any edit term and see the ID for that term in the status bar.

Node Association

For each node referenced in the 'DITA Today' block, I categorized it according to the new vocabulary.

How taxonomy navigation works

The taxonomy terms are accessible individually at their ID For example, any content which has been tagged with the term 'Testimonials' (term 33) can be viewed at http://dita.xml.org/taxonomy/term/33 (see complete term link list below). Also, a taxonomy query of sorts can be created with simple syntax to combine terms. To see content that is a combination of 'Case Studies' (term xx) and 'Testimonials' (term yy), you simply combine the Term ID's in one URL using a comma as a delimter. For example that would look like: http://dita.xml.org/taxonomy/term/32,33 The resulting listing represents the boolean AND operation. It includes all nodes tagged with both terms. To get a listing of nodes using either taxonomy term xx OR term yy, use a plus sign as the operator: http://dita.xml.org/taxonomy/term/33+33

Because regular content stories were created first before we created the taxonomies, the way that those stories appear now are a bit confusing. The one and only story under the category 'Testimonials' is a story titled 'Testimonials'. The system is actually designed to work by accomodating any arbitrary story, e.g. "Confessions of a DITA Junkie" to be tagged upon submission (or any time) as a testimonial, and it would automatically show up under the list of testimonials at http://dita.xml.org/taxonomy/term/33 (We'll see a bit later how to get both the story titles, snippets AND some content describing the category all at that same time -- using a module called taxonomy_assoc)

Review

Improvements

Building individual Taxonomy URL's is not the most user friendly way to provide site users access to browseable listings. Nor do site owners necessarily want to clutter their layout with a number of custom blocks for category content. To extend the the taxonomy system, including offering means of accessing nodes by category, there are many optional (taxonomy-related) modules to download and install. The most interesting appear to be:

taxonomy_assoc The taxonomy_assoc module lets you display a node - along with the usual node listing for that term - when you view a taxonomy term. The node can be used instead of (or as well as) the description that taxonomy_context outputs. Unlike raw descriptions, however, nodes can be commented on, can have filters applied to them, and can be used in a number of other ways (like print-friendly output).

This one I installed -- see Site Work section of this message. (Interestingly, the author of this module has created a whole new implementation of the book module and taxonomy module to simplify (and improve) the way that you can organize site content, navigation and organization. It will be interesting to explore more how, when and if these changes, currently outside drupal, are merged into the project.

taxonomy_defaults This module provides the ability to set default taxonomy terms per node type.

This I basically did (without downloading and installing an extra module) by administering the node types -- see Site Work section of this message.

taxonomy_context The taxonomy_context module enables you to display several useful types of information drawn from taxonomy terms. By default in Drupal, when you bring up a taxonomy term you get a list of "node" (stories, static pages, books, etc.) associated with that term--but nothing to describe the term itself. But for organizational websites one often wants to display information like a title and description of the current section. So this module includes several methods for displaying information about taxonomy terms:
* breadcrumbs
* the current term
* listings of sub-terms of the current term

This is very much like taxonomy_assoc, but presents a few options like navigation and breadcrumbs in addition to the description capability. It is installed and initially configured. See the Site Work section of this message.

taxonomy_menu The taxonomy menu module adds links to the navigation menu for taxonomy terms. This is useful when the community is focused on creating content that is organized in a taxonomy. The taxonomy menu administration interface allows taxonomy terms to be enabled to show in the navigation menu. You can also select whether a term's descendents subterms are displayed.

We have already done this by creating a custom block called DITA Today. We should edit the links in that block to go to the appropriate taxonomy/term (which when associated with a node through taxonomy_assoc will present some intro content plus the list of recent nodes.

taxonomy_dhtml A page listing recent nodes on your site, organized by taxonomy term. Also provides a block for each vocabulary, listing terms and their node counts. Finally, a box is
exported to the syndication.module main page.

Is supposed to be interesting, but may or may not be buggy, so I have not investigated it yet.

Documentation

The Drupal Handbook contents on taxonomy starts at http://drupal.org/handbook/modules/taxonomy

Related Site Work

RSS Feeds

In addition to displaying Drupal nodes by category, Drupal has category specific RSS feeds for other sites to access your site content. See how the URL format for the RSS feed is very similar to the Taxonomy URL:
http://dita.xml.org/taxonomy/term/32+33/0/feed

The RSS feeds would be a valuable thing to advertise to any offsite webpages / authors to pull traffic into our site. Also, many people these days enjoy using an RSS reader to keep track of subjects/websites that interest them, and click through on stories of particular interest. Since the RSS feeds are generated automatically, there is no work on our part. It just offers a way for us to syndicate our content and pull readers into the site.

Content Types

Just to be sure that the content creation process was smooth for contributors, I also configured all the content types, setting the appropriate defaults for things like view, edit, change perms
http://dita.xml.org/admin/node/configure/types

Style

I turned the background white behind the sponsor logos like you wanted, but I didn't really like the way the design clashes a bit (the grayish background and shadow border treatment makes the white background section appear blocky). It would be nice in my opinion to work on this, but also takes time to create a truly uniform and impressive design so I didn't want to dive into that rat hole -- especially without doing so in concert with your feedback. Anyway, the bottom line is that it does look a bit better with a white background for that block.

Site Enhancements

evaluate, download, install, configure, document the taxonomy_assoc module

grundlett@moria:/var/www/drupal/modules$ wget http://drupal.org/files/projects/taxonomy_assoc-4.6.0.tar.gz
grundlett@moria:/var/www/drupal/modules$ tar xzvf taxonomy_assoc-4.6.0.tar.gz
grundlett@moria:/var/www/drupal/modules$ mysql -u root drupal -p < taxonomy_assoc/taxonomy_assoc.mysql
# don't forget that each site uses their own database in addition to the master.
grundlett@moria:/var/www/drupal/modules$ mysql -u root dita -p < taxonomy_assoc/taxonomy_assoc.mysql

Next admin the site to activate the new module
http://dita.xml.org/admin/modules

Permissions are not automaticly set on activation, so admin the permissions so that somebody (even admin) has ability to use the module
http://dita.xml.org/admin/access

And admin the module to create new associations between taxonomy terms and content nodes
http://dita.xml.org/admin/taxonomy_assoc

evaluate, download, install, configure, document the taxonomy_context module

grundlett@moria:/var/www/drupal/modules$ wget http://drupal.org/files/projects/taxonomy_context-4.6.0.tar.gz
grundlett@moria:/var/www/drupal/modules$ tar zxvf taxonomy_context-4.6.0.tar.gz

Activate the module
http://dita.xml.org/admin/modules/

(no permission settings needed)

Administer the settings for the module
http://dita.xml.org/admin/settings/taxonomy_context

Look at the documentation
grundlett@moria:/var/www/drupal/modules$ cat taxonomy_context/INSTALL

grundlett@moria:/var/www/drupal/modules$ cat taxonomy_context/README.txt

Description
------------

With version 4.5, taxonomy_context uses the _help() hook for output
instead of drupal_set_message() and so no longer requires editing
to theme's display of messages.

The taxonomy_context module enables you to display several useful
types of information drawn from taxonomy terms. By default in Drupal,
when you bring up a taxonomy term you get a list of "node" (stories,
static pages, books, etc.) associated with that term--but nothing to
describe the term itself. But for organizational websites one often
wants to display information like a title and description of the
current section. So this module includes several methods for
displaying information about taxonomy terms:
* breadcrumbs
* the current term
* listings of sub-terms of the current term

The module also includes a context-sensitive menu block for each
vocabulary.

While it should be possible to use the module in other contexts, it's
primarily suited to use with vocabularies where there is (a) a single
term hierarchy and (b) only one term per node.

Configuration
-------------

To configure the module, click administration > configuration
> taxonomy_context.

Use the settings to select whether term and subterm info is displayed.
You can also disable the automatic styling of term info (see INSTALL).

Developer Usage
---------------

Navigation Buttons

Taxonomy context will generate context-sensitive top navigation buttons/
tabs. Sample request:

$buttons = taxonomy_context_buttons();

The $buttons variable will contain output with graphical navigation
buttons based on the first-level taxonomy terms in a given vocabulary.
You could reference this, e.g., in a theme.

Getting Context

The function taxonomy_context_get_context() can be invoked from any
theme or module to get the context of the current taxonomy and node.
It takes no parameters and returns an object with the following
properties:
tid: the current term's ID. If a node is being displayed, this is
the ID of the (first) term associated with the node.
root_tid: the ID of the top-level term in the hierarchy in which
nid: the current node's ID; null if none
vid: the ID of the current term or node's vocabulary.

-- 
Gregory S. Rundlett
Manager
Technology Services
OASIS
"Advancing E-Business Standards Since 1993"
http://www.oasis-open.org
(978) 667-5115 x 205

Prev by Date: New sponsor for DITA FA
Next by Date: Thursday's meeting
Previous by thread: New sponsor for DITA FA
Next by thread: Thursday's meeting
Index(es):
- Date
- Thread