Index: README.txt
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/hierarchical_select/README.txt,v
retrieving revision 1.37
diff -u -F^f -r1.37 README.txt
--- README.txt	29 Jul 2009 20:48:41 -0000	1.37
+++ README.txt	29 Jul 2009 23:08:25 -0000
@@ -116,6 +116,51 @@ folder, since that will cause problems a
 See http://drupal.org/node/346033.
 
 
+Rendering hierarchy lineages when viewing content
+-------------------------------------------------
+Hierarchical Select is obviously only used for input. Hence it is only used on
+the create/edit forms of content.
+Combine that with the fact that Hierarchical Select is the only module capable
+of restoring the lineage of saved items (e.g. Taxonomy terms). None of the
+Drupal core modules is capable of storing the lineage, but Hierarchical Select
+can reconstruct it relatively efficiently. However, this lineage is only
+visible when creating/editing content, not when viewing it.
+To allow you to display the lineages of stored items, I have provided a
+theming function that you can call from within e.g. your node.tpl.php file:
+the theme_hierarchical_select_selection_as_lineages($selection, $config)
+function.
+
+Sample usage (using Taxonomy and Hierarchical Select Taxonomy):
+  <?php if ($taxonomy):
+    require_once(drupal_get_path('module', 'hierarchical_select') .'/includes/common.inc');
+    $vid = 2;                                                    // Vocabulary ID. CHANGE THIS!
+    $config_id = "taxonomy-$vid";                                // Generate the config ID.
+    $config = hierarchical_select_common_config_get($config_id); // Get the Hierarchical Select configuration through the config ID.
+    $config['module'] = 'hs_taxonomy';                           // Set the module.
+    $config['params']['vid'] = $vid;                             // Set the parameters.
+    print theme('hierarchical_select_selection_as_lineages', $node->taxonomy, $config);
+  ?>
+
+This will automatically render all lineages for vocabulary 2 (meaning that if
+you want to render the lineages of multiple vocabularies, you'll have to clone
+this piece of code once for every vocabulary). It will also automatically get
+the current Hierarchical Select configuration for that vocabulary.
+
+Alternatively, you could provide the $config array yourself. Only three keys
+are required: 1) module, 2) params, 3) save_lineage. For example:
+  <?php if ($taxonomy):
+    $vid = 2;                          // Vocabulary ID. CHANGE THIS!
+    $config['module'] = 'hs_taxonomy'; // Set the module.
+    $config['params']['vid'] = $vid;   // Set the parameters.
+    $config['save_lineage'] = 1;       // save_lineage setting is enabled. CHANGE THIS!
+    print theme('hierarchical_select_selection_as_lineages', $node->taxonomy, $config);
+  ?>
+
+If you don't like how the lineage is displayed, simply override the
+theme_hierarchical_select_selection_as_lineages() function from within your
+theme, create e.g. garland_hierarchical_select_selection_as_lineages().
+
+
 Addressing Views exposed filters display issues
 -----------------------------------------------
 When using Hierarchical Select to alter an exposed Views filter (i.e. an 
Index: hierarchical_select.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/hierarchical_select/hierarchical_select.module,v
retrieving revision 1.166
diff -u -F^f -r1.166 hierarchical_select.module
--- hierarchical_select.module	29 Jul 2009 20:32:31 -0000	1.166
+++ hierarchical_select.module	29 Jul 2009 23:08:28 -0000
@@ -248,6 +248,13 @@ function hierarchical_select_theme() {
       'file'      => 'includes/theme.inc',
       'arguments' => array('form' => NULL),
     ),
+    'hierarchical_select_selection_as_lineages' => array(
+      'file'      => 'includes/theme.inc',
+      'arguments' => array(
+        'selection' => NULL,
+        'config'    => NULL,
+      ),
+    ),
   );
 }
 
Index: includes/theme.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/hierarchical_select/includes/theme.inc,v
retrieving revision 1.4
diff -u -F^f -r1.4 theme.inc
--- includes/theme.inc	21 Mar 2009 20:07:46 -0000	1.4
+++ includes/theme.inc	29 Jul 2009 23:08:28 -0000
@@ -290,6 +290,47 @@ function theme_hierarchical_select_commo
 }
 
 /**
+ * Themeing function to render a selection (of items) according to a given
+ * Hierarchical Select configuration as one or more lineages.
+ *
+ * @param $selection
+ *   A selection of items of a hierarchy.
+ * @param $config
+ *   A config array with at least the following settings:
+ *   - module
+ *   - save_lineage
+ *   - params
+ */
+function theme_hierarchical_select_selection_as_lineages($selection, $config) {
+  $output = '';
+
+  $selection = (!is_array($selection)) ? array($selection) : $selection;
+
+  // Generate a dropbox out of the selection. This will automatically
+  // calculate all lineages for us.
+  $selection = array_keys($selection);
+  $dropbox = _hierarchical_select_dropbox_generate($config, $selection);
+
+  // Actual formatting.
+  foreach ($dropbox->lineages as $id => $lineage) {
+    if ($id > 0) {
+      $output .= '<br />';
+    }
+
+    $items = array();
+    foreach ($lineage as $level => $item) {
+      $items[] = $item['label'];
+    }
+    $output .= implode('<span class="hierarchical-select-item-separator">›</span>', $items);
+  }
+
+  // Add the CSS.
+  drupal_add_css(drupal_get_path('module', 'hierarchical_select') .'/hierarchical_select.css');
+
+  return $output;
+}
+
+/**
  * @} End of "ingroup themeable".
  */