Index: API.txt
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/hierarchical_select/API.txt,v
retrieving revision 1.13
diff -u -F^f -r1.13 API.txt
--- API.txt	25 Feb 2008 22:54:14 -0000	1.13
+++ API.txt	25 Mar 2008 12:41:12 -0000
@@ -24,6 +24,9 @@
       'animation_delay' => 400,
       'dropbox_title' => t('All selections:'),
       'dropbox_limit' => 0,
+      'context' => array(
+        // Optional. See explanation for 'context' below.
+      ),
     ),
     '#default_value' => '83',
   ); 
@@ -89,6 +92,27 @@
    select has been enabled.
 
 
+ - context (optional)
+
+   This optional array is unique in that it isn't used by the Hierarchical
+   Select module itself. This array describes the "context" of this field
+   (that is, the ciscumnstances in which this field is used) so that modules
+   implementing hook_hierarchical_select_settings_alter() can examine it and
+   easily see what they have in their hands. See explanation for the hook,
+   below, for usage example.
+
+   You may put whatever you wish in this 'context' array, but the current
+   practice is to have a 'type' property describing the general context and
+   then some context-sensitive properties. For example, the built-in Taxonomy
+   support provided with this module sets the following 'context' when the
+   select box appers on a node editing form:
+
+       'context' => array(
+         'type' => 'node',
+         'node' => $form['#node'],
+        )
+   
+
 Special values
 --------------
 - Ensure that your options don't have a "none" or "all" value, nor "label_\d+"
@@ -140,3 +164,79 @@
 7) hook_hierarchical_select_item_get_label($item, $params);
 
    Given a valid item, returns the label.
+
+
+The hook_hierarchical_select_settings_alter($settings) hook
+-----------------------------------------------------------
+This hook has its own section in this document because it is likely to be
+used by a different crowd of users than the hooks listed above: It can be
+used by the site administrator, or themer, to alter the settings of each
+hierarchical_select form item on the site.
+
+Every hierarchical_select form element has its settings passed to this hook
+for possible alteration. The intention is to allow you to fine-tune the
+settings of your select boxes in a more granular fashion than is possible
+by using the GUI alone. For example, by implementing this hook you could
+configure a select box to show the '<All>' option when it appears on a certain
+node type form.
+
+The $settings parameter is a PHP reference to the '#hierarchical_select_settings'
+property described above. Of special interest is the 'context' member, which
+tells us --primarily by its 'type' property-- about the circumstances in
+which this select box is used.
+
+Here is an example, to be put in a 'mymodule' module:
+
+//
+// Customize various Hierarchical Select boxes on our site.
+//
+function mymodule_hierarchical_select_settings_alter(&$settings) {
+	
+  if ($settings['module'] == 'taxonomy' || $settings['module'] == 'content_taxonomy') {
+
+    // Don't put exposed filters on separate table rows.
+    if ($settings['context']['type'] == 'exposed_filter') {
+      $settings['exposed_filter_reposition'] = FALSE;
+    }
+
+    // News articles may not have more than three terms of vocabulary #12.
+    if ($settings['context']['type'] == 'node'
+        && $settings['params']['vid'] == 12
+        && $settings['context']['node']->type == 'news') {
+      $settings['dropbox_limit'] = 3;
+    }
+
+    // Add the 'All' option to exposed filters.
+    if ($settings['context']['type'] == 'exposed_filter'
+        && $settings['context']['view']->name == 'a_certain_view') {
+      // but only if it isn't a 'single' filter
+      if (!$settings['context']['filter']['single']) {
+        $settings['all_option'] = TRUE;
+      }
+      // ...and make it possible to select non-leaf terms.
+      $settings['enforce_deepest'] = FALSE;
+    }
+
+    // Disable HS for 'bio' nodes.
+    if ($settings['context']['type'] == 'node'
+        && $settings['context']['node']->type == 'bio') {
+      $settings['enabled'] = FALSE;
+    }
+  }
+}
+
+This example also demonstrates two $settings properties which weren't discussed
+previously (because they make most sense only in the context of this hook):
+  
+  'enabled'
+ 
+    By setting this to FALSE we tell the Hierarchical Select module to not
+    handle this select box.
+
+  'exposed_filter_reposition'
+
+    Usually, the Hierarchical Select module repositions exposed filters in
+    separate table rows --to prevent an unaesthetic 'dance' when dependant
+    drop-downs come and go. But for aesthetic reasons of your own you may wish
+    to turn this feature off. Do this by setting this property to FALSE.
+
Index: hierarchical_select.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/hierarchical_select/hierarchical_select.module,v
retrieving revision 1.40
diff -u -F^f -r1.40 hierarchical_select.module
--- hierarchical_select.module	3 Mar 2008 16:44:26 -0000	1.40
+++ hierarchical_select.module	25 Mar 2008 12:41:14 -0000
@@ -175,6 +175,21 @@ function hierarchical_select_process($el
   // Render a hierarchical select as a normal select, it's the JavaScript that
   // will turn it into a hierarchical select.
   $element['#type'] = 'select';
+  
+  // Allow custom modules to alter the settings.
+  // First, ensure certain settings are present:
+  $element['#hierarchical_select_settings'] += array(
+    'enabled' => TRUE,
+    'context' => array('type' => 'undefined'),
+  );
+  foreach (module_implements('hierarchical_select_settings_alter') as $module) {
+    $function = $module .'_hierarchical_select_settings_alter';
+    $function($element['#hierarchical_select_settings']);
+  }
+  if (!$element['#hierarchical_select_settings']['enabled']) {
+    // A custom module has turned-off HS support for this element.
+    return $element;
+  }
 
   if (!isset($hsid)) {
     $hsid = 0;
@@ -728,12 +743,22 @@ function _hierarchical_select_validate_s
  * Helper function that adds the JS to reposition the exposed filters of a
  * View just once.
  */
-function _hierarchical_select_views_exposed_filters_reposition() {
+function _hierarchical_select_views_exposed_filters_reposition($element) {
   static $js_added;
   
   if (!isset($js_added)) {
-    drupal_add_js(drupal_get_path('module', 'hierarchical_select') .'/modules/views.js', 'module');
+    // Custom modules have a chance to disable this feature, by turning off the
+    // 'exposed_filter_reposition' setting, via hook_hierarchical_select_settings_alter().
+    //
+    // TODO: Right now 'views.js' reposition _all_ filters on the page. It'd
+    //       be nice to make it work on a filter by filter basis.
+    if (!empty($element['#hierarchical_select_settings']['exposed_filter_reposition'])) {
+      drupal_add_js(drupal_get_path('module', 'hierarchical_select') .'/modules/views.js', 'module');
+    }
   }
+
+  // This function is called as an #after_build hook, so it must return the element.
+  return $element;
 }
 
 /**
Index: modules/content_taxonomy.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/hierarchical_select/modules/content_taxonomy.inc,v
retrieving revision 1.7
diff -u -F^f -r1.7 content_taxonomy.inc
--- modules/content_taxonomy.inc	17 Feb 2008 15:00:33 -0000	1.7
+++ modules/content_taxonomy.inc	25 Mar 2008 12:41:14 -0000
@@ -59,6 +59,10 @@ function content_taxonomy_hierarchical_s
             'vid' => $vid,
             'depth' => (is_numeric($depth)) ? $depth : 999,
           ),
+          'context' => array(
+            'type' => 'node',
+            'node' => $form['#node'],
+          ),
         );
         taxonomy_hierarchical_select_update_form_item($form[$field_name]['tids'], $vid);
       }
@@ -74,6 +78,10 @@ function content_taxonomy_hierarchical_s
               'vid' => $vid,
               'depth' => (is_numeric($depth)) ? $depth : 999,
             ),
+            'context' => array(
+              'type' => 'node',
+              'node' => $form['#node'],
+            ),
           );
           taxonomy_hierarchical_select_update_form_item($form[$field_group][$field_name]['tids'], $vid);
         }
Index: modules/taxonomy.inc
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/hierarchical_select/modules/taxonomy.inc,v
retrieving revision 1.20
diff -u -F^f -r1.20 taxonomy.inc
--- modules/taxonomy.inc	9 Feb 2008 18:14:04 -0000	1.20
+++ modules/taxonomy.inc	25 Mar 2008 12:41:15 -0000
@@ -204,6 +204,12 @@ function taxonomy_hierarchical_select_fo
               'params' => array(
                 'vid' => $vid,
               ),
+              'exposed_filter_reposition' => TRUE,
+              'context' => array(
+                'type' => 'exposed_filter',
+                'view' => $form['view']['#value'],
+                'filter' => $filter,
+              ),
             );
             taxonomy_hierarchical_select_update_form_item($form["filter$id"], $vid);
             
@@ -217,7 +223,9 @@ function taxonomy_hierarchical_select_fo
             unset($form["filter$id"]['#hierarchical_select_settings']['dropbox_limit']);
 
             // Put the altered exposed filters in a separate table row.
-            _hierarchical_select_views_exposed_filters_reposition();
+            // We're doing this at a late stage, #after_build, to give custom modules a
+            // chance to turn this feature off.
+            $form["filter$id"]['#after_build'][] = '_hierarchical_select_views_exposed_filters_reposition';
           }
         }
       }
@@ -241,6 +249,10 @@ function taxonomy_hierarchical_select_fo
             'params' => array(
               'vid' => $vid,
             ),
+            'context' => array(
+              'type' => 'node',
+              'node' => $form['#node'],
+            ),
           );
           taxonomy_hierarchical_select_update_form_item($form['taxonomy'][$vid], $vid);
         }