Club Drupal

Terminology

-----------

- item: an item in the hierarchy. A hierarchy can also be seen as a tree. In

        that case, an item can be either a parent or a child. However, if

        "multiple parents" are supported (i.e. a child can have multiple

        parents), then it's actually not a tree but a directed acyclic graph

        (see http://en.wikipedia.org/wiki/Directed_acyclic_graph), in which

        each case technically is a "node".

        An example: in the case of taxonomy, this is the term id (tid).

- label: the label associated with an item in the hierarchy. You may now it

         as "title" or something else similar.

         An example: in the case of taxonomy, this is the actual term.

- item type: a per-level, human-readable name that describes what kind of

             items that level contains.

- entity: an item is often associated with an entity. E.g. a term is usually

          associated with a node.

- form element: a form element allows the developer to assign a new value to

                a #type property in a form item. Examples of form elements

                supported by Drupal core are: select, checkboxes, textfield.

- form item: an instance of a form element, with various other properties

             defined, such as #title, #default_value and #description. These

             are used to define a form in Drupal.

- Hierarchical Select: this is the name of the module.

- hierarchical_select: this is the internal name of the Hierarchical Select

                       form element.

- hierarchical select: (note the difference in case) this is the part of the

                       widget with the multiple selects.

- dropbox: this is the part of the widget where the selections are stored when

           multiple selections are allowed.

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.'),

    '#size' => 1,

    '#config' => array(

      'module' => 'hs_taxonomy',

      'params' => array(

        'vid' => $vid,

      ),

      'save_lineage'    => 0,

      'enforce_deepest' => 0,

      'entity_count'    => 0,

      'require_entity'  => 0,

      'resizable'       => 1,

      'level_labels' => array(

        'status' => 0,

        'labels' => array(

          0 => t('Main category'),

          1 => t('Subcategory'),

          2 => t('Third level category'),

        ),

      ),

      'dropbox' => array(

        'status'   => 0,

        'title'    => t('All selections'),

        'limit'    => 0,

        'reset_hs' => 1,

      ),

      'editability' => array(

        'status'           => 0,

        'item_types'       => array(),

        'allowed_levels'   => array(

          0 => 0,

          1 => 0,

          2 => 1,

        ),

        'allow_new_levels' => 0,

        'max_levels'       => 3,

      ),

      // These settings cannot be configured through the UI: they can only be

      // overridden through code.

      'animation_delay'    => 400,

      'special_items'      => array(),

      'render_flat_select' => 0,

    ),

    '#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) The #size property is inherited by the selects of the hierarchical select.

   You can use it to change a vertical size of the select (i.e. change how many

   items are displayed in the select, similar to a form select multiple).

3) There's a new property: #config. This must be an

array. These are the items it can contain:

 - module (required)

   This will be passed through in the AJAX requests, to let Hierarchical

   Select know which module's hooks should be used.

 - params (optional, may be necessary for some implementations)

   An array of parameters that will also be passed through in every AJAX

   request.

   e.g. In the case of taxonomy, this is the vocabulary id (vid). In case of

   content_taxonomy, there's three parameters: vid, tid and depth (tid allows

   one to define a new root, depth allows one to limit the depth of the

   displayed hierarchy).

 - save_lineage (optional, defaults to 0)

   Triggers the lineage saving functionality. If enabled, the selection can

   consist of multiple values.

 - enforce_deepest (optional, defaults to 0)

   Triggers the enforcing of a selection in the deepest level. If enabled, the

   selection will always be a single value.

 - entity_count (optional, defaults to 0)

   Enables the display of entity counts, between parentheses, for each item in

   the hierarchy.

 - require_entity (optional, defaults to 0)

   Whether an item should only be displayed if it has at least one associated

   entity.

 - resizable (optional, defaults to 1)

   Makes the hierarchical select resizable.

 - level_labels['status'] (optional, defaults to 0)

   Whether level labels should be enabled or not. When save_lineage is

   enabled, this will result in *empty* level labels.

 - level_labels['labels'] (optional)

   An array of labels, one per level. The label for the first level should be

   the value of key 0.

   When enforce_deepest is set to:

   - 0, then you can provide n level labels, with n the number of levels

   - 1, then you can provide only one level label.   

 - dropbox['status'] (optional, defaults to 0)

   Whether the dropbox is enabled or not (the dropbox allows the user to make

   multiple selections).

 - dropbox['title'] (optional, defaults to "All selections:")

   The title of the dropbox. The dropbox is the area where all selections are

   displayed when the dropbox is enabled.

 - dropbox['limit'] (optional, defaults to 0, which means "no limit")

   Limit the number of selection that can be added to the dropbox. So this

   allows you the restrict the number of items that can be selected when

   the dropbox has been enabled.

 - dropbox['reset_hs'] (optional, defaults to 1, which means "do reset")

   Determines what will happen to the hierarchical select when the user has

   added a selection to the dropbox.

 - editability['status] (optional, defaults to 0)

   Allow the user to create new items in the hierarchy.

 - editability['item_types'] (optional, defaults to the empty array)

   Only meaningful when editable is set to TRUE.

   Set the item type for each level. E.g.: "country" for the first level,

   "region" for the second and "city" for the third. When the user then wants

   to create a new item, the default label for the new item will be of the

   form "new <item type>", e.g. "new region".

 - editability['allowed_levels'] (optional, defaults to 1 for each level)

   Only meaningful when editable is set to TRUE.

   Specify in which levels the user is allowed to create new items. In the

   example, the user is only allowed to create new items in the third level.

   When a setting for a level is ommitted, it defaults to 1 (i.e. allowed for

   that level). This means you only have to specify in which levels the user

   is not allowed to create new items.

   This only applies to *existing* levels: it does not affect the

   allow_new_levels setting (the next setting).

 - editability['allow_new_levels'] (optional, defaults to 0)

   Only meaningful when editable is set to TRUE.

   Allow the user to create new levels, i.e. when a certain item does not yet

   have children, the user can create a first child for it (thus thereby

   creating a new level).

 - editability['max_levels'] (optional, defaults to 3)

   Only meaningful when editable_settings['allow_new_levels'] is set to TRUE.

   Limits the maximum number of levels. Don't set this too high or you'll end

   up with very deep hierarchies. This only affects how deep new levels can be

   created, it will not affect the existing hierarchy.

 - animation_delay (optional, defaults to 400)

   The delay of each animation (the drop in left and right animations), in ms.

 - special_items (optional, defaults to the empty array)

   Through this setting, you can mark each item with special properties it

   possesses. There currently are two special properties: 'exclusive' and

   'none'.

   Note: you should include these items in the hierarchy as if it were a

   normal item and then you can mark them as special through this property.

   * 'exclusive': Sometimes it's desirable to have exclusive lineages. When

                  such an option is selected, the user should not be able to

                  select anything else. This also means that  nothing else in

                  the dropbox can be selected: if the dropbox contains

                  anything, it will be reset.

                  Can be applied to multiple items.

                  e.g. an 'entire_tree' item:

                    'special_items' => array(

                      'entire_tree' => array('exclusive'),

                    )

   * 'none': Sometimes you want to replace the default '<none>' option by

             something else. This replacement should of course also exist in

             the root level.

             Can be applied to only one item.

             e.g. an 'any' item (used in hs_taxonomy_views):

               'special_items' => array(

                 'any' => array('none', 'exclusive'),

               )

   And a final example for a better overview:

    'special_items' => array(

      'entire_tree' => array('exclusive'),

      'any'         => array('none', 'exclusive'),

    )

 - render_flat_select (optional, defaults to 0)

   Because the hierarchical_select form element consists of multiple form

   items, it doesn't work well in GET forms. By enabling this setting, a flat

   select will also be rendered, that contains only the selected lineages.

   Combine that with Drupal.HierarchicalSelect.prepareGETSubmit in the JS code

   (or, alternatively, the 'prepare-GET-submit' event  that can be triggered,

   see the JavaScript events section for details) and you have a work-around

   (which, admittedly, only works when JS is enabled).

3) We *don't* specify a list of options: Hierarchical Select automatically

generates the options for us, thanks to the 'module' and 'params' settings.

Concepts

--------

- Item Unicity: each item in the hierarchy must be *unique*. It doesn't have

                to be numerical, it can also be a string.

                If your hierarchy does not have unique items by nature or by

                design (your items may be unique per level instead), that's

                not a problem. You can simply prepend the item's ancestors to

                get a unique item.

                e.g. you have an item "foobar" at the first, second and third

                levels. By prepending the ancestors using the dash as the

                separator, you'd get an item "foobar-foobar-foobar" at the

                third level.

                Also see the "Reserved item values" section.

- #options: it's gone, because it was the inherent cause for scalability

            problems: if a hierarchy consists of 10,000 or even 100,000 items,

            this results in huge HTML being generated. Huge HTML means more

            processing power necessary, and more bandwidth necessary. So where

            does Hierarchical Select get its "options"? It uses the hooks that

            every implementation has to implement to only get what it needs.

- The General Concept: you should think of Hierarchical Select as an abstract

                       widget that can represent *any* hierarchy. To be able

                       to display any hierarchy, you obviously  need some

                       universal way to "browse" a hierarchy.

                       If you are familiar with C++ or Java iterators, this

                       should come natural: the hooks you have to implement

                       is what allows Hierarchical Select to iterate over your

                       hierarchy. Then the heart of the iterator would be the

                       root_level() and children() hooks. params() allows you

                       to define which information is necessary before you can

                       determine *which* hierarchy or which *part* of the

                       hierarchy is being browsed. lineage() must return the

                       lineage, i.e. the item itself and all its ancestors,

                       this allows a hierarchy to be generated from just one

                       (selected) item.

Reserved item values

--------------------

- Ensure that your items don't have a "none", "all", "create_new_item" nor

  "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.

Developer mode

--------------

When you are writing your implementation of the Hierarchical Select API, you

will often wonder what Hierarchical Select is doing internally with the data

you're feeding it. That's why there's a developer mode: it will show you this

data, even the data generated in AJAX callbacks. It'll also show you the time

it took to generate the lineage, to fill up the levels and to calculate the

child info, to track down badly performing code.

Also, when you're just creating a new HS config and it doesn't quite work

right, it can be helpful to enable the developer mode. It will perform some

basic diagnostics that might help you track down the cause.

To use this, you must have a browser with console.log() support. Install 

Firebug Lite (http://getfirebug.com/lite.html) if your browser does not

suport this. Next, go to Hierarchical Select's .module file and set the define

for the HS_DEVELOPER_MODE constant to TRUE.

When you now open Firebug (Firefox) or the Web Inspector (Safari), you'll see

the debug output. New output is added after each callback to the server.

Hierarchical Select implementations: gotcha's

---------------------------------------------

- "warning: Missing argument 1 for drupal_retrieve_form() …"

  This implies that your implementation's module weight is heavier than

  hierarchical_select.module. In that case, Hierarchical Select will not be

  able to detect hierarchical_select form items, preventing it from applying

  some magic, and AJAX updates won't work.

Hierarchical Select compatibility: gotcha's

-------------------------------------------

- "Invalid response from server"

  This typically means that some functions could not be found when

  Hierarchical Select does an AJAX callback to the server, which in turn means

  that some code (some PHP file) has not been included, while it should have

  been. Instead of using module_load_include() or even require_once, you

  should use form_load_include(). This function is new in Drupal 7 and will

  ensure that all required PHP files are included automatically.

Hierarchical Select API Tutorial

--------------------------------

Written by Stephen Barker of Digital Frontiers Media

(http://drupal.org/user/106070) and reviewed by Wim Leers:

  http://drupal.org/node/532724

Hierarchical Select Small Hierarchy

-----------------------------------

Hierarchical Select includes a Hierarchical Select API implementation that

allows one to use a hardcoded hierarchy. When it becomes to slow, you should

move the hierarchy into the database and write a proper implementation.

Below you can find an example of how to use the hs_smallhierarchy module. Just

change the $hierarchy array to suit your needs and off you go! Look at the

code of hs_smallhierarchy.module for full details, but this code example

should get you started.

  $hierarchy = array(

     'win' => array(

       'label' => 'Windows',

       'children' => array(

         'xp'    => array('label' => 'XP'),

         'vista' => array(

           'label' => 'Vista',

           'children' => array(

             'x86' => array('label' => '32-bits'),

             'x64' => array('label' => '64-bits'),

           ),

         ),

       ),

     ),

  );

  $form['select_some_term'] = array(

    '#type' => 'hierarchical_select',

    '#title' => t('Select the tag you wish to use.'),

    '#size' => 1,

    '#config' => array(

      'module' => 'hs_smallhierarchy',

      'params' => array(

        'hierarchy' => $hierarchy,

        'id' => 'my-hierarchy-about-windows',

        'separator' => '|',

      ),

      'save_lineage'    => 0,

      'enforce_deepest' => 0,

      'entity_count'    => 0,

      'resizable'       => 1,

      'level_labels' => array(

        'status' => 0,

        'labels' => array(

          0 => t('Main category'),

          1 => t('Subcategory'),

          2 => t('Third level category'),

        ),

      ),

      'dropbox' => array(

        'status'   => 0,

        'title'    => t('All selections'),

        'limit'    => 0,

        'reset_hs' => 1,

      ),

      'editability' => array(

        'status'           => 0,

        'item_types'       => array(),

        'allowed_levels'   => array(

          0 => 0,

          1 => 0,

          2 => 1,

        ),

        'allow_new_levels' => 0,

        'max_levels'       => 3,

      ),

      // These settings cannot be configured through the UI: they can only be

      // overridden through code.

      'animation_delay'    => 400,

      'exclusive_lineages' => array(),

      'render_flat_select' => 0,

    ),

    '#description' => 'Put your description here',

    '#default_value' => 'win|xp|x86',

  );

Hooks

-----

1) hook_hierarchical_select_params();

   Returns an array with the names of all parameters that are necessary for

   this implementation to work.

2) hook_hierarchical_select_root_level($params, $dropbox = FALSE);

   Returns the root level of the hierarchy: an array of (item, label) pairs.

   The $dropbox parameter can is optional and can even ommitted, as it's only

   necessary if you need the dropbox to influence your hierarchy.

3) hook_hierarchical_select_children($parent, $params, $dropbox = FALSE);

   Gets the children of $parent ($parent is an item in the hierarchy) and

   returns them: an array of (item, label) pairs, or the empty array if the

   given $parent has no children.

   The $dropbox parameter can is optional and can even ommitted, as it's only

   necessary if you need the dropbox to influence your hierarchy.

4) hook_hierarchical_select_lineage($item, $params);

   Calculates the lineage of $item (array of items, with $item the last) and

   returns it. Necessary when the "enforce_deepest" option is enabled.

5) hook_hierarchical_select_valid_item($item, $params);

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

6) hook_hierarchical_select_item_get_label($item, $params);

   Given a valid item, returns the label. Is only used for rendering the

   selections in the dropbox.

7) hook_hierarchical_select_create_item($label, $parent, $params);

   Given a parent item and the label of a new item, create a new item as a

   child of the parent item. When $parent == 0, this means a new item is being

   created at the root level.

   Optional hook. When this hook is not implemented, this functionality will

   never be used, even when you configure it that way in code.

8) hook_hierarchical_select_entity_count($item, $params);

   Given a item, get the number of entities (most of the time the entity type

   is 'node') that are related to the given item. Used for the entity_count

   and require_entity settings.

   Optional hook. When this hook is not implemented, this functionality will

   never be used, even when you configure it that way (i.e. when you enable

   the entity_count and require_entity settings).

9) hook_hierarchical_select_implementation_info();

   Return metadata about this implementation.

   This information is used to generate the implementations overview at

   admin/settings/hierarchical_select/implementations. The expected format is:

      array(

        'hierarchy type' => t('Taxonomy'),

        'entity type'    => t('Node'),

        'entity'         => t('Story'),

        'context type'   => t('Node form'),

        'context'        => '',

      );

    another example:

      array(

        'hierarchy type' => t('Taxonomy'),

        'entity type'    => t('Node'),

        'entity'         => '',

        'context type'   => t('Views exposed filter'),

        'context'        => t('some view'),

      );

10) hook_hierarchical_select_config_info();

    Return metadata about each available user-editable configuration for this

    implementation.

    Optional hook. This information is used to generate the configurations

    overview at admin/settings/hierarchical_select/configs. The expected

    format is:

      $config_info[$config_id] = array(

        'config_id'      => $config_id,

        'hierarchy type' => t('Taxonomy'),

        'hierarchy'      => t($vocabulary->name),

        'entity type'    => t('Node'),

        'entity'         => implode(', ', array_map('t', $entities)),

        'edit link'      => "admin/content/taxonomy/edit/vocabulary/$vid",

      );

Standardized configuration form

-------------------------------

Hierarchical Select 3 comes with a standardized configuration form: 

hierarchical_select_common_config_form(). This function accepts a lot of

parameters, which allows you to use names typical to your module's hierarchy

(e.g. 'leaf' instead of 'term' and 'tree' instead of 'vocabulary'). A submit

handler is also provided, of course.

An example:

  // I'm not configuring all parameters here. For an example of that, see one

  // of the included modules.

  $form['foobar_hierarchical_select_config'] = hierarchical_select_common_config_form($module, $params, $config_id, $defaults, $strings, $max_hierarchy_depth, $preview_is_required);

  // Add the the submit handler for the Hierarchical Select config form.

  $parents = array('foobar_hierarchical_select_config');

  $form['#submit'][] = 'hierarchical_select_common_config_form_submit';

  $form['#hs_common_config_form_parents'] = $parents;

Configuration management

------------------------

It's now possible to export Hierarchical Select configurations, and there is a

function to set the configuration of a certain Hierarchical Select. Combine

the two and you can manage your Hierarchical Select configurations in code!

An example:

  // The exported configuration.

  $config = array( … );

  $config_id = $config['config_id];

  // Apply the configuration.

  require_once(drupal_get_path('module', 'hierarchical_select') .'/includes/common.inc');

  hierarchical_select_common_config_set($config_id, $config);

JavaScript events

-----------------

The Hierarchical Select module's JavaScript code triggers several events, to

allow for advanced interactions.

You can find all hierarchical_select form items using this selector:

  $('.hierarchical-select-wrapper');

You can find a *specific* hierarchical_select form item using this selector:

  $('#hierarchical-select-x-wrapper');

where x is a number, or more accurately: a hsid (hierarchical select id).

Retrieving all hsids in the current document can be done like this:

  for (var hsid in Drupal.settings.HierarchicalSelect.settings) {

    // …

  }

Alternatively, you can use one of the transliterated class names. A wrapper

for Hierarchical Select looks like this:

  <div class="hierarchical-select-wrapper

              hierarchical-select-level-labels-style-none

              hierarchical-select-wrapper-for-name-edit-taxonomy-1

              hierarchical-select-wrapper-for-config-taxonomy-1

              hierarchical-select-wrapper-processed"

       id="hierarchical-select-35-wrapper">

  …

  </div>

Hence, you could also use selectors such as these, to achieve the same effect,

but with more robust code:

  $('.hierarchical-select-wrapper-for-config-taxonomy-1:first')

  .trigger('enforce-update');

  $('.hierarchical-select-wrapper-for-name-edit-taxonomy-1:first')

  .trigger('enforce-update');

The following events are triggered:

  - change-hierarchical-select

  - update-hierarchical-select

  - create-new-item

  - cancel-new-item

  - add-to-dropbox

  - remove-from-dropbox

  - enforced-update

  - prepared-GET-submit

All events are triggered *after* the animations have completed.

However, it's often useful to do something *before* an event (especially

because all of the above events perform an AJAX request to the server). So,

the equivalent "before" events exist as well:

  - before-update-hierarchical-select

  - before-create-new-item

  - before-cancel-new-item

  - before-add-to-dropbox

  - before-remove-from-dropbox

  - before-enforced-update

There is one exception: when the cache is enabled, the "before update

hierarchical select" event will not be triggered. This makes sense, because

updates from the cache are instantaneous.

An example of binding a function to the 'create-new-item' event of the second

(hsid == 1) hierarchical_select form item on the page:

  $('#hierarchical-select-1-wrapper')

  .bind('create-new-item', function() {

    // …

  });

And finally, you can trigger a special event to enforce an update (this can be

useful when you have changed a hierarchy through another form item, or for

live previews, or …). You can then also pass additional information that will

be POSTed. You can even disable normal updates, to manage that completely

yourself via enforced updates. This allows you to write a Hierarchical Select

implementation that gets some of its information ($params) from another form

item!

Suppose you'd like to enforce an update of the first (hsid == 0)

hierarchical_select form item on the page:

  $('#hierarchical-select-0-wrapper')

  .trigger('enforce-update');

Now let's move on to a more advanced example, in which we will disable normal

updates and let another form item (here a select) provide a part of the

information that will be used to render the Hierarchical Select. Effectively,

this other form item will *influence* the hierarchy that will be presented by

Hierarchical Select!

  $(document).ready(function() {

    Drupal.settings.specialfilter = {};

    // .specialfilter-first: a select form item

    // .specialfilter-second: a hierarchical_select form item

    update = function() {

      var selection = Drupal.settings.specialfilter.currentSelection;

      // Send an extra parameter via POST: dynamicParameter. This is the stored

      // selection.

      $('.specialfilter-second')

      .trigger('enforce-update',

        [

          { name : 'dynamicParameter', value : selection }

        ]

      );

    };

    attachHSBindings = function() {

      // When a user navigates the hierarchical_select form item, we still want to

      // POST the the extra dynamicParameter, or otherwise we will no longer have

      // a hierarchy in the hierarchical_select form item that really depends on

      // the select.

      $('.specialfilter-second .hierarchical-select > select')

      .change(function() { update(); });

      $('.specialfilter-second')

      .unbind('enforced-update').bind('enforced-update', function() { return attachHSBindings(); });

    };

    // Initialize after 25 ms, because otherwise the event binding of HS will

    // not yet be ready, and hence this won't have any effect

    setTimeout(function() {

      // Get the initial selection (before the user has changed anything).

      Drupal.settings.specialfilter.currentSelection = $('.specialfilter-first').attr('value');

      // When the select form item changes, we want to *store* that selection, and

      // update the hierarchical_select form item.

      $('.specialfilter-first')

      .change(function() {

        // Store the current selection.

        Drupal.settings.specialfilter.currentSelection = $(this).attr('value');

        update();

      });

      $('.specialfilter-second')

      .trigger('disable-updates');

      attachHSBindings();

    }, 25);

  });

The 'enforced-update' (notice the past tense!) event is triggered upon

completion.

An even more rarely used special event can be triggered to prepare the

hierarchical_select form element for a get submit: the 'prepare GET submit'

event. To use this event, the 'render_flat_select' setting should be enabled

in the config.

                    GNU GENERAL PUBLIC LICENSE

                       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.,

 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

 Everyone is permitted to copy and distribute verbatim copies

 of this license document, but changing it is not allowed.

                            Preamble

  The licenses for most software are designed to take away your

freedom to share and change it.  By contrast, the GNU General Public

License is intended to guarantee your freedom to share and change free

software--to make sure the software is free for all its users.  This

General Public License applies to most of the Free Software

Foundation's software and to any other program whose authors commit to

using it.  (Some other Free Software Foundation software is covered by

the GNU Lesser General Public License instead.)  You can apply it to

your programs, too.

  When we speak of free software, we are referring to freedom, not

price.  Our General Public Licenses are designed to make sure that you

have the freedom to distribute copies of free software (and charge for

this service if you wish), that you receive source code or can get it

if you want it, that you can change the software or use pieces of it

in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid

anyone to deny you these rights or to ask you to surrender the rights.

These restrictions translate to certain responsibilities for you if you

distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether

gratis or for a fee, you must give the recipients all the rights that

you have.  You must make sure that they, too, receive or can get the

source code.  And you must show them these terms so they know their

rights.

  We protect your rights with two steps: (1) copyright the software, and

(2) offer you this license which gives you legal permission to copy,

distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain

that everyone understands that there is no warranty for this free

software.  If the software is modified by someone else and passed on, we

want its recipients to know that what they have is not the original, so

that any problems introduced by others will not reflect on the original

authors' reputations.

  Finally, any free program is threatened constantly by software

patents.  We wish to avoid the danger that redistributors of a free

program will individually obtain patent licenses, in effect making the

program proprietary.  To prevent this, we have made it clear that any

patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and

modification follow.

                    GNU GENERAL PUBLIC LICENSE

   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains

a notice placed by the copyright holder saying it may be distributed

under the terms of this General Public License.  The "Program", below,

refers to any such program or work, and a "work based on the Program"

means either the Program or any derivative work under copyright law:

that is to say, a work containing the Program or a portion of it,

either verbatim or with modifications and/or translated into another

language.  (Hereinafter, translation is included without limitation in

the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not

covered by this License; they are outside its scope.  The act of

running the Program is not restricted, and the output from the Program

is covered only if its contents constitute a work based on the

Program (independent of having been made by running the Program).

Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's

source code as you receive it, in any medium, provided that you

conspicuously and appropriately publish on each copy an appropriate

copyright notice and disclaimer of warranty; keep intact all the

notices that refer to this License and to the absence of any warranty;

and give any other recipients of the Program a copy of this License

along with the Program.

You may charge a fee for the physical act of transferring a copy, and

you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion

of it, thus forming a work based on the Program, and copy and

distribute such modifications or work under the terms of Section 1

above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices

    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in

    whole or in part contains or is derived from the Program or any

    part thereof, to be licensed as a whole at no charge to all third

    parties under the terms of this License.

    c) If the modified program normally reads commands interactively

    when run, you must cause it, when started running for such

    interactive use in the most ordinary way, to print or display an

    announcement including an appropriate copyright notice and a

    notice that there is no warranty (or else, saying that you provide

    a warranty) and that users may redistribute the program under

    these conditions, and telling the user how to view a copy of this

    License.  (Exception: if the Program itself is interactive but

    does not normally print such an announcement, your work based on

    the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole.  If

identifiable sections of that work are not derived from the Program,

and can be reasonably considered independent and separate works in

themselves, then this License, and its terms, do not apply to those

sections when you distribute them as separate works.  But when you

distribute the same sections as part of a whole which is a work based

on the Program, the distribution of the whole must be on the terms of

this License, whose permissions for other licensees extend to the

entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest

your rights to work written entirely by you; rather, the intent is to

exercise the right to control the distribution of derivative or

collective works based on the Program.

In addition, mere aggregation of another work not based on the Program

with the Program (or with a work based on the Program) on a volume of

a storage or distribution medium does not bring the other work under

the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,

under Section 2) in object code or executable form under the terms of

Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable

    source code, which must be distributed under the terms of Sections

    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three

    years, to give any third party, for a charge no more than your

    cost of physically performing source distribution, a complete

    machine-readable copy of the corresponding source code, to be

    distributed under the terms of Sections 1 and 2 above on a medium

    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer

    to distribute corresponding source code.  (This alternative is

    allowed only for noncommercial distribution and only if you

    received the program in object code or executable form with such

    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for

making modifications to it.  For an executable work, complete source

code means all the source code for all modules it contains, plus any

associated interface definition files, plus the scripts used to

control compilation and installation of the executable.  However, as a

special exception, the source code distributed need not include

anything that is normally distributed (in either source or binary

form) with the major components (compiler, kernel, and so on) of the

operating system on which the executable runs, unless that component

itself accompanies the executable.

If distribution of executable or object code is made by offering

access to copy from a designated place, then offering equivalent

access to copy the source code from the same place counts as

distribution of the source code, even though third parties are not

compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program

except as expressly provided under this License.  Any attempt

otherwise to copy, modify, sublicense or distribute the Program is

void, and will automatically terminate your rights under this License.

However, parties who have received copies, or rights, from you under

this License will not have their licenses terminated so long as such

parties remain in full compliance.

  5. You are not required to accept this License, since you have not

signed it.  However, nothing else grants you permission to modify or

distribute the Program or its derivative works.  These actions are

prohibited by law if you do not accept this License.  Therefore, by

modifying or distributing the Program (or any work based on the

Program), you indicate your acceptance of this License to do so, and

all its terms and conditions for copying, distributing or modifying

the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the

Program), the recipient automatically receives a license from the

original licensor to copy, distribute or modify the Program subject to

these terms and conditions.  You may not impose any further

restrictions on the recipients' exercise of the rights granted herein.

You are not responsible for enforcing compliance by third parties to

this License.

  7. If, as a consequence of a court judgment or allegation of patent

infringement or for any other reason (not limited to patent issues),

conditions are imposed on you (whether by court order, agreement or

otherwise) that contradict the conditions of this License, they do not

excuse you from the conditions of this License.  If you cannot

distribute so as to satisfy simultaneously your obligations under this

License and any other pertinent obligations, then as a consequence you

may not distribute the Program at all.  For example, if a patent

license would not permit royalty-free redistribution of the Program by

all those who receive copies directly or indirectly through you, then

the only way you could satisfy both it and this License would be to

refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under

any particular circumstance, the balance of the section is intended to

apply and the section as a whole is intended to apply in other

circumstances.

It is not the purpose of this section to induce you to infringe any

patents or other property right claims or to contest validity of any

such claims; this section has the sole purpose of protecting the

integrity of the free software distribution system, which is

implemented by public license practices.  Many people have made

generous contributions to the wide range of software distributed

through that system in reliance on consistent application of that

system; it is up to the author/donor to decide if he or she is willing

to distribute software through any other system and a licensee cannot

impose that choice.

This section is intended to make thoroughly clear what is believed to

be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in

certain countries either by patents or by copyrighted interfaces, the

original copyright holder who places the Program under this License

may add an explicit geographical distribution limitation excluding

those countries, so that distribution is permitted only in or among

countries not thus excluded.  In such case, this License incorporates

the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions

of the General Public License from time to time.  Such new versions will

be similar in spirit to the present version, but may differ in detail to

address new problems or concerns.

Each version is given a distinguishing version number.  If the Program

specifies a version number of this License which applies to it and "any

later version", you have the option of following the terms and conditions

either of that version or of any later version published by the Free

Software Foundation.  If the Program does not specify a version number of

this License, you may choose any version ever published by the Free Software

Foundation.

  10. If you wish to incorporate parts of the Program into other free

programs whose distribution conditions are different, write to the author

to ask for permission.  For software which is copyrighted by the Free

Software Foundation, write to the Free Software Foundation; we sometimes

make exceptions for this.  Our decision will be guided by the two goals

of preserving the free status of all derivatives of our free software and

of promoting the sharing and reuse of software generally.

                            NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY

FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN

OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES

PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED

OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS

TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE

PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,

REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING

WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR

REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,

INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING

OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED

TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY

YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER

PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE

POSSIBILITY OF SUCH DAMAGES.

                     END OF TERMS AND CONDITIONS

            How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest

possible use to the public, the best way to achieve this is to make it

free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest

to attach them to the start of each source file to most effectively

convey the exclusion of warranty; and each file should have at least

the "copyright" line and a pointer to where the full notice is found.

    <one line to give the program's name and a brief idea of what it does.>

    Copyright (C) <year>  <name of author>

    This program is free software; you can redistribute it and/or modify

    it under the terms of the GNU General Public License as published by

    the Free Software Foundation; either version 2 of the License, or

    (at your option) any later version.

    This program is distributed in the hope that it will be useful,

    but WITHOUT ANY WARRANTY; without even the implied warranty of

    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License along

    with this program; if not, write to the Free Software Foundation, Inc.,

    51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this

when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) year name of author

    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.

    This is free software, and you are welcome to redistribute it

    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate

parts of the General Public License.  Of course, the commands you use may

be called something other than `show w' and `show c'; they could even be

mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your

school, if any, to sign a "copyright disclaimer" for the program, if

necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program

  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  <signature of Ty Coon>, 1 April 1989

  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into

proprietary programs.  If your program is a subroutine library, you may

consider it more useful to permit linking proprietary applications with the

library.  If this is what you want to do, use the GNU Lesser General

Public License instead of this License.

Description

-----------

This module defines the "hierarchical_select" form element, which is a greatly

enhanced way for letting the user select items in a hierarchy.

Hierarchical Select has the ability to save the entire lineage of a selection

or only the "deepest" selection. You can configure it to force the user to

make a selection as deep as possible in the tree, or allow the user to select

an item anywhere in the tree. Levels can be labeled, you can configure limit

the number of items that can be selected, configure a title for the dropbox,

choose a site-wide animation delay, and so on. You can even create new items

and levels through Hierarchical Select!

Integrates with

---------------

* Taxonomy (Drupal core)

Installation

------------

1) Place this module directory in your "modules" folder (this will usually be

"sites/all/modules/"). Don't install your module in Drupal core's "modules"

folder, since that will cause problems and is bad practice in general. If

"sites/all/modules" doesn't exist yet, just create it.

2) Enable the Hierarchical Select and Hierarchical Select Taxonomy modules.

3) If you want to use it for one or more of your vocabularies, go to

admin/structure/types and click the "manage fields" link for a content type on

which you're using a Term reference field. Click the "edit" link for this Term

reference field and then go to the "widget type" tab in the upper right corner.

There, you can choose the "Hierarchical Select" widget type, and when you do,

the entire Hierarchical Select configuration UI will appear: here you'll find

a whole range of Hierarchical Select settings. All settings are explained

there as well!

Troubleshooting

---------------

If you ever have problems, make sure to go through these steps:

1) Go to admin/reports/status (i.e. the Status Report). Ensure that the status

   of the Hierarchical Select module is ok.

2) Ensure that the page isn't being served from your browser's cache. Use

   CTRL+R in Windows/Linux browsers, CMD+R in Mac OS X browsers to enforce the

   browser to reload everything, preventing it from using its cache.

3) When you're getting a JS alert with the following message: "Received an

   invalid response from the server.", ensure that the page (of which this

   form is a part) is *not* being cached.

4) When Hierarchical Select seems to be misbehaving in a certain use case in

   which terms with multiple parents are being used, make sure to enable the

   "Save term lineage" setting.

   Note: you may have to repeat this for every configuration in which the

   vocabulary with terms that have multiple parents are being used. E.g. if

   such a vocabulary is called "A", then go to 

      admin/config/content/hierarchical_select/configs

   and edit all configuration that have "A" in the "Hierarchy" column.

In case of problems, don't forget to try a hard refresh in your browser!

Limitations

-----------

- Creating new items in the hierarchy in a multiple parents hierarchy (more

  scientifically: a directed acyclic graph) is *not* supported.

- Not the entire scalability problem can be solved by installing this set of

  modules; read the maximum scalability section for details.

- The child indicators only work in Firefox. This *cannot* be supported in

  Safari or IE. See http://drupal.org/node/180691#comment-1044691.

- The special [save-lineage-termpath] token only works with content_taxonomy

  fields as long as you have the "Save option" set to either "Tag" or "Both".

- In hierarchies where items can have multiple parent items and where you have

  enabled Hierarchical Select's "save lineage" setting, it is impossible to

  remember individual hierarchies, unless the underlying module supports it.

  So far, no module supports this. Hierarchical Select is just a form element,

  not a system for storing hierarchies.

  For example, if you have created a multiple parent vocabulary through the

  Taxonomy module, and you have terms like this:

   A -> C

   A -> D

   B -> C

   B -> D

  If you then save any two lineages in which all four terms exist, all four

  lineages will be rendered by Hierarchical Select, because only the four

  terms are stored and thus there is no way to recover the originally selected

  two lineages.

- You can NOT expect the Hierarchical Select Taxonomy module to automagically

  fix all existing nodes when you enable or disable the "save lineage" setting

  and neither can you expect it to keep working properly when you reorganize

  the term hierarchy. There's nothing I can do about this. Hierarchical Select

  is merely a form element, it can't be held responsible for features that

  Drupal core lacks or supports poorly.

  See the following issues:

  * http://drupal.org/node/1023762#comment-4054386

  * http://drupal.org/node/976394#comment-4054456

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.

  ?>

    <div class="terms"><?php print theme('hierarchical_select_selection_as_lineages', $node->taxonomy, $config); ?></div>

  <?php endif; ?>

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!

  ?>

    <div class="terms"><?php print theme('hierarchical_select_selection_as_lineages', $node->taxonomy, $config); ?></div>

  <?php endif; ?>

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().

Setting a fixed size

--------------------

When you don't want users to be able to resize a hierarchical select

themselves, you can set a fixed size in advance yourself

Setting #size to >1 does *not* generate #multiple = TRUE selects! And the

opposite is also true. #multiple sets the "multiple" HTML attribute. This

enables the user to select multiple options of a select. #size just controls

the "size" HTML attribute. This increases the vertical size of selects,

thereby showing more options.

See http://www.w3.org/TR/html401/interact/forms.html#adef-size-SELECT.

Sponsors

--------

* Initial development:

   Paul Ektov of http://autobin.ru.

* Abstraction, to let other modules than taxonomy hook in:

   Etienne Leers of http://creditcalc.biz.

* Support for saving the term lineage:

   Paul Ektov of http://autobin.ru.

* Multiple select support:

   Marmaladesoul, http://marmaladesoul.com.

* Taxonomy Subscriptions support:

   Mr Bidster Inc.

* Ability to create new items/levels:

   The Worx Company, http://www.worxco.com.

* Ability to only show items that are associated with at least one entity:

   Merge, http://merge.nl.

* Views 2 support:

   Merge, http://merge.nl.

* Initial Drupal 7 port + folow-up fixes:

   PingV, http://pingv.com.

* Port of "save lineage" functionality to Drupal 7:

   Bancard Data Service

Author

------

Wim Leers

* website: http://wimleers.com/

* contact: http://wimleers.com/contact

The author can be contacted for paid development on this module. This can vary

from new features to Hierarchical Select itself, to new implementations (i.e.

support for new kinds of hierarchies).

HS core:

✓ port: initial port

✓ fix: JS code cleanup (remove hardcoded hacks)

✓ fix: title + description (i.e. something's off with the theme wrapper)

✓ fix: #value_callback may be necessary? (see file.module) OR: ensure #return_value works

✓ fix: #element_validate callback: _hierarchical_select_validate() — verify this still works

✓ port: support multiple HS on the same page

✓ port: admin UI

✓ port: "dropbox" support

✓ upgrade path: delete cache_hierarchical_select

✓ upgrade path: documentation

✓ port: "create new item" support — see http://drupal.org/node/1087620

✓ port: status report

- port: render_flat_select support

- port: client-side caching (use _hierarchical_select_json_convert_hierarchy_to_cache())

- feature: live preview of HS on the common config form

- refactor: use the proper #value_callback -> #process callback -> #after_build callback pipeline as described in the documentation for form_builder() in form.inc

Taxonomy:

✓ port: admin UI

✓ port: "dropbox" support

✓ port: "save lineage" support (i.e. support multiple parents, automatic warning shown through hs_taxonomy_hierarchical_select_root_level())

✓ port: field formatters (from content_taxonomy)

✓ port: taxonomy term (create/edit) form should be altered to include HS

✓ upgrade path: migrate settings (no migration necessary)

✓ upgrade path: documentation (no migration, no docs)

✓ port: "create new item" support — see http://drupal.org/node/1087620

- port: "entity_count" support — see http://drupal.org/node/1068462

- refactor: use the vocabulary machine name internally instead of the vid

- port: token support — see http://drupal.org/node/1248908

- port: forum support

- refactor: optimize HS API implementation: take advantage of improvements in Taxonomy

HS Taxonomy Views: 

- everything — see http://drupal.org/node/1170192

Menu: 

✓ everything

Flat List:

✓ everything

Small Hierarchy:

✓ everything

# Upgrading (from Drupal 6 to 7)

1. **BE WARE THAT NOT ALL FUNCTIONALITY HAS BEEN PORTED!**

	Make sure that you know if the part of Hierarchical Select's functionality

	that you want to use has been ported. Otherwise, you may be in for a

	frustrating upgrade experience.

	See the included TODO.txt file for details. In a nutshell:

	- Taxonomy support is almost complete, only "create new item", "entity count" and token support are missing

	- Forum support has **not** yet been ported (but relies on Taxonomy, so this is trivial)

	- Taxonomy Views support has **not** yet been ported

	- Menu support has **not** yet been ported

2. Upgrade this module just like any other: delete the old module, copy the

	files of the new module and run update.php.  

	For details, see <http://drupal.org/node/570162>.

3. That's it! :)

/* The hierarchical select. */

.hierarchical-select-wrapper .hierarchical-select .selects {

  float: right; /* If a block is floated, it won't consume as much width as

                   available, only just enough. This allows the grippie to

                   perfectly scale with the with consumed by the selects. */ 

}

.hierarchical-select-wrapper .hierarchical-select .selects .grippie {

  clear: right; /* clear: left; */

  height: 9px;

  overflow: hidden;

  background: #eee url(images/grippie.png) no-repeat center 2px;

  border: 1px solid #ddd;

  border-top-width: 0;

  cursor: s-resize;

  margin-left: 0.5em; /* margin-right: 0.5em; */ /* Give the grippie the same margin as each select. */

  min-width: 70px; /* Hack for IE, makes the grip usable, but not yet the same as in other browsers. */

}

.hierarchical-select-wrapper .hierarchical-select select,

.hierarchical-select-wrapper .hierarchical-select .add-to-dropbox,

.hierarchical-select-wrapper .hierarchical-select .create-new-item {

  margin-left: .5em;

  float: right;

}

/* The pseudo-modal window for creating a new item or new level. */

.hierarchical-select-wrapper .hierarchical-select .create-new-item-create,

.hierarchical-select-wrapper .hierarchical-select .create-new-item-cancel {

  float: left;

  margin-right: .4em;

}

.hierarchical-select-wrapper .hierarchical-select .create-new-item-input {

  float: right;

  clear: left;

}

/* Child level indicator. */

.hierarchical-select-wrapper .hierarchical-select option.has-children {

  background: url(images/arrow-rtl.png) no-repeat left center;

}

/* Dropbox limit warning.*/

p.hierarchical-select-dropbox-limit-warning {

  padding-right: .5em;

}

<?php

/**

 * @file

 * Module settings and configuration administration UI.

 */

/**

 * Form definition; admin settings.

 */

function hierarchical_select_admin_settings($form, &$form_state) {

  $form['description'] = array(

    '#markup' => t('All settings below will be used as site-wide defaults.'),

    '#prefix' => '<div>',

    '#suffix' => '</div>',

  );

  $form['hierarchical_select_animation_delay'] = array(

    '#type' => 'textfield',

    '#title' => t('Animation delay'),

    '#description' => t(

      'The delay that will be used for the "drop in/out" effect when a

      hierarchical select is being updated (in milliseconds).'

    ),

    '#size' => 5,

    '#maxlength' => 5,

    '#default_value' => variable_get('hierarchical_select_animation_delay', 400),

  );

  $form['hierarchical_select_level_labels_style'] = array(

    '#type' => 'select',

    '#title' => t('Level labels style'),

    '#description' => t(

      'The style that will be used for level labels. This is not supported by

      all browsers! If you want a consistent interface, choose to use no

      style.'

    ),

    '#options' => array(

      'none' => t('No style'),

      'bold' => t('Bold'),

      'inversed' => t('Inversed'),

      'underlined' => t('Underlined'),

    ),

    '#default_value' => variable_get('hierarchical_select_level_labels_style', 'none'),

  );

  // TODO: port the HS client-side cache system to Drupal 7.

  /*

  $form['hierarchical_select_js_cache_system'] = array(

    '#type' => 'radios',

    '#title' => t('Cache in a HTML 5 client-side database'),

    '#description' => t(

      'This feature only works in browsers that support the

      <a href="!spec-url">HTML 5 client-side database storage specification

      </a>.</br>

      After enabling this, you will notice (in supporting browsers) that

      refreshing the hierarchical select will not require a request to the

      server when a part is being requested that has been requested before.',

      array('!spec-url' => url('http://www.whatwg.org/specs/web-apps/current-work/multipage/section-sql.html'))

    ),

    '#options' => array(

      0 => t('Disabled'),

      1 => t('Enabled'),

    ),

    '#default_value' => variable_get('hierarchical_select_js_cache_system', 0),

  );

  */

  return system_settings_form($form);

}

/**

 * Menu callback; a table that lists all Hierarchical Select configs.

 */

function hierarchical_select_admin_configs() {

  $header = array(t('Hierarchy type'), t('Hierarchy'), t('Entity type'), t('Bundle'), t('Context type'), t('Context'), t('Actions'));

  // Retrieve all information items

  $info_items = array();

  foreach (module_implements('hierarchical_select_config_info') as $module) {

    $info_items = array_merge_recursive($info_items, module_invoke($module, 'hierarchical_select_config_info'));

  }

  // Process the retrieved information into rows.

  $rows = array();

  foreach ($info_items as $id => $item) {

    $config_id = $item['config_id'];

    $rows[$id] = array(

      $item['hierarchy type'],

      $item['hierarchy'],

      $item['entity type'],

      $item['bundle'],

      $item['context type'],

      $item['context'],

      theme('links', array('links' => array(

          array(

            'title' => t('Edit'),

            'href' => $item['edit link'],

            'fragment' => "hierarchical-select-config-form-$config_id",

          ),

          array(

            'title' => t('Export'),

            'href' => "admin/config/content/hierarchical_select/export/$config_id",

          ),

          array(

            'title' => t('Import'),

            'href' => "admin/config/content/hierarchical_select/import/$config_id",

          ),

        ))),

    );

  }

  return theme('table', array('header' => $header, 'rows' => $rows, 'attributes' => array(), 'caption' => t('Overview of all Hierarchical Select configurations.')));

}

/**

 * Menu callback; a table that lists all Hierarchical Select implementations

 * and the features they support.

 */

function hierarchical_select_admin_implementations() {

  $output = '';

  $header = array(t('Implementation (module)'), t('Hierarchy type'), t('Entity type'), t('Create new items'), t('Entity count'));

  // Retrieve all information items

  $rows = array();

  foreach (module_implements('hierarchical_select_root_level') as $module) {

    $filename = db_query("SELECT filename FROM {system} WHERE type = :type AND name = :name", array(':type' => 'module', ':name' => $module))->fetchField();

    $module_info = drupal_parse_info_file(dirname($filename) . "/$module.info");

    // Try to extract the hierarchy type from the optional hook_hierarchical_select_config_info().

    $hierarchy_type = $entity_type = t('unknown');

    if (module_hook($module, 'hierarchical_select_implementation_info')) {

      $implementation = module_invoke($module, 'hierarchical_select_implementation_info');

      $hierarchy_type = $implementation['hierarchy type'];

      $entity_type    = $implementation['entity type'];

    }