$Id: API.txt,v 1.8 2007-12-31 16:40:38 wimleers Exp $

Hooks
-----

1) hook_hierarchial_select_form_alter($form_id, &$form);

  This hook is absolutely optional. The sole reason for its existence, is to
  allow easy altering of Drupal core forms to use the hierarchical_select form
  item.

2) hook_hierarchical_select_params();

  Returns the names of all parameters that should be present.

3) hook_hierarchical_select_root_level($params);

  Returns the root level of the hierarchy.

4) hook_hierarchical_select_children($parent, $params);

  Gets the children of $parent and returns them.

5) hook_hierarchical_select_lineage($item, $params);

  Calculates the lineage of $item and returns it. Necessary when the
  "enforce_deepest" option is enabled.

6) hook_hierarchical_select_valid_item($item, $params);

  Validates an item, returns TRUE if valid, FALSE if invalid.

7) hook_hierarchical_select_item_get_label($item, $params);

  Given a valid item, returns the label.


Form API usage
--------------
You have to make sure your form item is using the "hierarchical_select" form
element type:

  $form['select_some_term'] = array(
    '#type' => 'hierarchical_select',
    '#title' => t('Select the tag you wish to use.'),
    '#options' => $options, // Contains an array of tid - term name pairs.
    '#hierarchical_select_settings' => array(
      'module' => 'taxonomy',
      'save_lineage' => FALSE,
      'enforce_deepest' => FALSE,
      'level_labels' => array(
        0 => t('Main category'),
        1 => t('Subcategory'),
      ),
      'params' => array(
        'vid' => $vid,
      ),
      'animation_delay' => 400,
      'dropbox_title' => t('These are the terms you selected'). ':',
    ),
    '#default_value' => '83',
  ); 

Now, let's explain what we see here:
1) We've set the #type property to "hierarchical_select" instead of "select".
2) There's a new property: #hierarchical_select_settings. This must be an
array. These are the items it can contain:
 - module (obligated)
   This will be passed through in the AHAH requests, to let the HS module know
   which module's hooks should be used.
 - save_lineage (optional, defaults to FALSE)
   This option triggers the lineage saving functionality.
 - enforce_deepest (optional, defaults to FALSE)
   This option triggers the enforcing of a selection in the deepest level.
 - level_labels (optional, only used if enforce_deepest is set to FALSE)
   An array of labels, one per level. The label for the first level should be
   the value of key 0.
 - params (optional, may be necessary for some implementations)
   An array of parameters that will also be passed through in every AHAH
   request.
   e.g. In the case of taxonomy, this is the vocabulary id (vid). In case of
   content_taxonomy, there's two parameters: vid and the depth.
 - animation_delay (optional, defaults to 400)
   The delay of each animation (the drop in left and right animations), in ms.
 - dropbox_title (optional, defaults to "All selections:")
   The title of the dropbox. The dropbox is the area where all selected items
   are displayed when multiple select is enabled.


Special values
--------------
- Ensure that your options don't have a "none" value or "label_\d+" values
  (the latter means "label_" followed by one or more digits). Your values
  should also not contain a pipe ("|"), since pipes are used to separate
  the selection of values that are sent back to the server in the callbacks.
- Valid 'empty' selections (i.e. if you want to set the #default_value
  property of your form item), are -1 and the empty array. The empty string is
  also considered valid, because Drupal core's Taxonomy module uses this as
  the empty selection.