modules/hierarchical_select/README.txt

$Id: README.txt,v 1.38 2009/08/04 22:34:18 wimleers Exp $

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
---------------
* Book (Drupal core) – NOT YET PORTED TO DRUPAL 6
* Forum (Drupal core)
* Menu (Drupal core)
* Taxonomy (Drupal core)
* Content Taxonomy (http://drupal.org/project/content_taxonomy) – NOT YET PORTED TO DRUPAL 6
* Views


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

3) If you want to use it for one or more of your vocabularies, go to
admin/content/taxonomy and click the "edit" link for a vocabulary. Now scroll
down and 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/logs/status (i.e. the Status Report). Ensure that the status
   of the following modules is ok:
   - Hierarchical Select
   - Hierarchical Select Taxonomy Views (if installed)
   - Hierarchical Select Content Taxonomy Views (if installed)

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.

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.


Maximum scalability
-------------------
hs_taxonomy takes advantage of the taxonomy_override_selector variable to
improve scalability: the whole tree is no longer loaded by Drupal core.
While the hs_book, hs_menu and hs_subscriptions modules override existing form
items, those form items are *still* being generated. This can cause scalability
issues.
If you want to fix this, you *will* have to modify the original modules (so
that includes Drupal core modules). Simply move the changes from the
hook_form_alter() implementations into the corresponding form definitions.


Hierarchical Select Taxonomy: using the [save-lineage-termpath] token
---------------------------------------------------------------------
When you're using the Token module, and likely the Pathauto module, and you've
configured your Hierarchical Select to save the lineage, you may want to show
the saved lineage (or the first lineage in case you've also enabled the
dropbox) in your URL. That's possible through the [save-lineage-termpath]
token (and other similar tokens). However, by default it uses the separator
you've configured Pathauto to use (if you aren't using Pathauto then it will
default to a dash). You can override this by setting the hs_taxonomy_separator
variable. Also, when you're using Pathauto and it seems to be stripping the
separator you've configured, then you may want to configure that character in
Pathauto's Punctuation settings to "No action (do not replace)".


Using the dropbox in Views exposed filters
------------------------------------------
This can be very tricky, due to a combination of the respective limitations of
Taxonomy and Views exposed filters.
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.
  ?>
    <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.


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).
1	$Id: README.txt,v 1.38 2009/08/04 22:34:18 wimleers Exp $
2
3	Description
4	-----------
5	This module defines the "hierarchical_select" form element, which is a greatly
6	enhanced way for letting the user select items in a hierarchy.
7
8	Hierarchical Select has the ability to save the entire lineage of a selection
9	or only the "deepest" selection. You can configure it to force the user to
10	make a selection as deep as possible in the tree, or allow the user to select
11	an item anywhere in the tree. Levels can be labeled, you can configure limit
12	the number of items that can be selected, configure a title for the dropbox,
13	choose a site-wide animation delay, and so on. You can even create new items
14	and levels through Hierarchical Select!
15
16
17	Integrates with
18	---------------
19	* Book (Drupal core) – NOT YET PORTED TO DRUPAL 6
20	* Forum (Drupal core)
21	* Menu (Drupal core)
22	* Taxonomy (Drupal core)
23	* Content Taxonomy (http://drupal.org/project/content_taxonomy) – NOT YET PORTED TO DRUPAL 6
24	* Views
25
26
27	Installation
28	------------
29	1) Place this module directory in your "modules" folder (this will usually be
30	"sites/all/modules/"). Don't install your module in Drupal core's "modules"
31	folder, since that will cause problems and is bad practice in general. If
32	"sites/all/modules" doesn't exist yet, just create it.
33
34	2) Enable the module.
35
36	3) If you want to use it for one or more of your vocabularies, go to
37	admin/content/taxonomy and click the "edit" link for a vocabulary. Now scroll
38	down and you'll find a whole range of Hierarchical Select settings. All
39	settings are explained there as well.
40
41
42	Troubleshooting
43	---------------
44	If you ever have problems, make sure to go through these steps:
45
46	1) Go to admin/logs/status (i.e. the Status Report). Ensure that the status
47	of the following modules is ok:
48	- Hierarchical Select
49	- Hierarchical Select Taxonomy Views (if installed)
50	- Hierarchical Select Content Taxonomy Views (if installed)
51
52	2) Ensure that the page isn't being served from your browser's cache. Use
53	CTRL+R in Windows/Linux browsers, CMD+R in Mac OS X browsers to enforce the
54	browser to reload everything, preventing it from using its cache.
55
56	In case of problems, don't forget to try a hard refresh in your browser!
57
58
59	Limitations
60	-----------
61	- Creating new items in the hierarchy in a multiple parents hierarchy (more
62	scientifically: a directed acyclic graph) is not supported.
63	- Not the entire scalability problem can be solved by installing this set of
64	modules; read the maximum scalability section for details.
65	- The child indicators only work in Firefox. This cannot be supported in
66	Safari or IE. See http://drupal.org/node/180691#comment-1044691.
67	- The special [save-lineage-termpath] token only works with content_taxonomy
68	fields as long as you have the "Save option" set to either "Tag" or "Both".
69	- In hierarchies where items can have multiple parent items and where you have
70	enabled Hierarchical Select's "save lineage" setting, it is impossible to
71	remember individual hierarchies, unless the underlying module supports it.
72	So far, no module supports this. Hierarchical Select is just a form element,
73	not a system for storing hierarchies.
74	For example, if you have created a multiple parent vocabulary through the
75	Taxonomy module, and you have terms like this:
76	A -> C
77	A -> D
78	B -> C
79	B -> D
80	If you then save any two lineages in which all four terms exist, all four
81	lineages will be rendered by Hierarchical Select, because only the four
82	terms are stored and thus there is no way to recover the originally
83	selected two lineages.
84
85
86	Maximum scalability
87	-------------------
88	hs_taxonomy takes advantage of the taxonomy_override_selector variable to
89	improve scalability: the whole tree is no longer loaded by Drupal core.
90	While the hs_book, hs_menu and hs_subscriptions modules override existing form
91	items, those form items are still being generated. This can cause scalability
92	issues.
93	If you want to fix this, you will have to modify the original modules (so
94	that includes Drupal core modules). Simply move the changes from the
95	hook_form_alter() implementations into the corresponding form definitions.
96
97
98	Hierarchical Select Taxonomy: using the [save-lineage-termpath] token
99	---------------------------------------------------------------------
100	When you're using the Token module, and likely the Pathauto module, and you've
101	configured your Hierarchical Select to save the lineage, you may want to show
102	the saved lineage (or the first lineage in case you've also enabled the
103	dropbox) in your URL. That's possible through the [save-lineage-termpath]
104	token (and other similar tokens). However, by default it uses the separator
105	you've configured Pathauto to use (if you aren't using Pathauto then it will
106	default to a dash). You can override this by setting the hs_taxonomy_separator
107	variable. Also, when you're using Pathauto and it seems to be stripping the
108	separator you've configured, then you may want to configure that character in
109	Pathauto's Punctuation settings to "No action (do not replace)".
110
111
112	Using the dropbox in Views exposed filters
113	------------------------------------------
114	This can be very tricky, due to a combination of the respective limitations of
115	Taxonomy and Views exposed filters.
116	See http://drupal.org/node/346033.
117
118
119	Rendering hierarchy lineages when viewing content
120	-------------------------------------------------
121	Hierarchical Select is obviously only used for input. Hence it is only used on
122	the create/edit forms of content.
123	Combine that with the fact that Hierarchical Select is the only module capable
124	of restoring the lineage of saved items (e.g. Taxonomy terms). None of the
125	Drupal core modules is capable of storing the lineage, but Hierarchical Select
126	can reconstruct it relatively efficiently. However, this lineage is only
127	visible when creating/editing content, not when viewing it.
128	To allow you to display the lineages of stored items, I have provided a
129	theming function that you can call from within e.g. your node.tpl.php file:
130	the theme_hierarchical_select_selection_as_lineages($selection, $config)
131	function.
132
133	Sample usage (using Taxonomy and Hierarchical Select Taxonomy):
134	<?php if ($taxonomy):
135	require_once(drupal_get_path('module', 'hierarchical_select') . '/includes/common.inc');
136	$vid = 2; // Vocabulary ID. CHANGE THIS!
137	$config_id = "taxonomy-$vid"; // Generate the config ID.
138	$config = hierarchical_select_common_config_get($config_id); // Get the Hierarchical Select configuration through the config ID.
139	$config['module'] = 'hs_taxonomy'; // Set the module.
140	$config['params']['vid'] = $vid; // Set the parameters.
141	?>
142	<div class="terms"><?php print theme('hierarchical_select_selection_as_lineages', $node->taxonomy, $config); ?></div>
143	<?php endif; ?>
144
145	This will automatically render all lineages for vocabulary 2 (meaning that if
146	you want to render the lineages of multiple vocabularies, you'll have to clone
147	this piece of code once for every vocabulary). It will also automatically get
148	the current Hierarchical Select configuration for that vocabulary.
149
150	Alternatively, you could provide the $config array yourself. Only three keys
151	are required: 1) module, 2) params, 3) save_lineage. For example:
152	<?php if ($taxonomy):
153	$vid = 2; // Vocabulary ID. CHANGE THIS!
154	$config['module'] = 'hs_taxonomy'; // Set the module.
155	$config['params']['vid'] = $vid; // Set the parameters.
156	$config['save_lineage'] = 1; // save_lineage setting is enabled. CHANGE THIS!
157	?>
158	<div class="terms"><?php print theme('hierarchical_select_selection_as_lineages', $node->taxonomy, $config); ?></div>
159	<?php endif; ?>
160
161	If you don't like how the lineage is displayed, simply override the
162	theme_hierarchical_select_selection_as_lineages() function from within your
163	theme, create e.g. garland_hierarchical_select_selection_as_lineages().
164
165
166	Setting a fixed size
167	--------------------
168	When you don't want users to be able to resize a hierarchical select
169	themselves, you can set a fixed size in advance yourself
170	Setting #size to >1 does not generate #multiple = TRUE selects! And the
171	opposite is also true. #multiple sets the "multiple" HTML attribute. This
172	enables the user to select multiple options of a select. #size just controls
173	the "size" HTML attribute. This increases the vertical size of selects,
174	thereby showing more options.
175	See http://www.w3.org/TR/html401/interact/forms.html#adef-size-SELECT.
176
177
178	Sponsors
179	--------
180	* Initial development:
181	Paul Ektov of http://autobin.ru.
182	* Abstraction, to let other modules than taxonomy hook in:
183	Etienne Leers of http://creditcalc.biz.
184	* Support for saving the term lineage:
185	Paul Ektov of http://autobin.ru.
186	* Multiple select support:
187	Marmaladesoul, http://marmaladesoul.com.
188	* Taxonomy Subscriptions support:
189	Mr Bidster Inc.
190	* Ability to create new items/levels:
191	The Worx Company, http://www.worxco.com.
192	* Ability to only show items that are associated with at least one entity:
193	Merge, http://merge.nl.
194	* Views 2 support:
195	Merge, http://merge.nl.
196
197
198	Author
199	------
200	Wim Leers
201
202	* website: http://wimleers.com/
203	* contact: http://wimleers.com/contact
204
205	The author can be contacted for paid development on this module. This can vary
206	from new features to Hierarchical Select itself, to new implementations (i.e.
207	support for new kinds of hierarchies).