API.txt 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693
  1. Terminology
  2. -----------
  3. - item: an item in the hierarchy. A hierarchy can also be seen as a tree. In
  4. that case, an item can be either a parent or a child. However, if
  5. "multiple parents" are supported (i.e. a child can have multiple
  6. parents), then it's actually not a tree but a directed acyclic graph
  7. (see http://en.wikipedia.org/wiki/Directed_acyclic_graph), in which
  8. each case technically is a "node".
  9. An example: in the case of taxonomy, this is the term id (tid).
  10. - label: the label associated with an item in the hierarchy. You may now it
  11. as "title" or something else similar.
  12. An example: in the case of taxonomy, this is the actual term.
  13. - item type: a per-level, human-readable name that describes what kind of
  14. items that level contains.
  15. - entity: an item is often associated with an entity. E.g. a term is usually
  16. associated with a node.
  17. - form element: a form element allows the developer to assign a new value to
  18. a #type property in a form item. Examples of form elements
  19. supported by Drupal core are: select, checkboxes, textfield.
  20. - form item: an instance of a form element, with various other properties
  21. defined, such as #title, #default_value and #description. These
  22. are used to define a form in Drupal.
  23. - Hierarchical Select: this is the name of the module.
  24. - hierarchical_select: this is the internal name of the Hierarchical Select
  25. form element.
  26. - hierarchical select: (note the difference in case) this is the part of the
  27. widget with the multiple selects.
  28. - dropbox: this is the part of the widget where the selections are stored when
  29. multiple selections are allowed.
  30. Form API usage
  31. --------------
  32. You have to make sure your form item is using the "hierarchical_select" form
  33. element type:
  34. $form['select_some_term'] = array(
  35. '#type' => 'hierarchical_select',
  36. '#title' => t('Select the tag you wish to use.'),
  37. '#size' => 1,
  38. '#config' => array(
  39. 'module' => 'hs_taxonomy',
  40. 'params' => array(
  41. 'vid' => $vid,
  42. ),
  43. 'save_lineage' => 0,
  44. 'enforce_deepest' => 0,
  45. 'resizable' => 1,
  46. 'level_labels' => array(
  47. 'status' => 0,
  48. 'labels' => array(
  49. 0 => t('Main category'),
  50. 1 => t('Subcategory'),
  51. 2 => t('Third level category'),
  52. ),
  53. ),
  54. 'dropbox' => array(
  55. 'status' => 0,
  56. 'title' => t('All selections'),
  57. 'limit' => 0,
  58. 'reset_hs' => 1,
  59. 'sort' => 1,
  60. ),
  61. 'editability' => array(
  62. 'status' => 0,
  63. 'item_types' => array(),
  64. 'allowed_levels' => array(
  65. 0 => 0,
  66. 1 => 0,
  67. 2 => 1,
  68. ),
  69. 'allow_new_levels' => 0,
  70. 'max_levels' => 3,
  71. ),
  72. 'entity_count' => array(
  73. 'enabled' => 0,
  74. 'require_entity' => 0,
  75. 'settings' => array(
  76. 'count_children' => 0,
  77. 'entity_types' => array(),
  78. ),
  79. ),
  80. // These settings cannot be configured through the UI: they can only be
  81. // overridden through code.
  82. 'animation_delay' => 400,
  83. 'special_items' => array(),
  84. 'render_flat_select' => 0,
  85. ),
  86. '#default_value' => '83',
  87. );
  88. Now, let's explain what we see here:
  89. 1) We've set the #type property to "hierarchical_select" instead of "select".
  90. 2) The #size property is inherited by the selects of the hierarchical select.
  91. You can use it to change a vertical size of the select (i.e. change how many
  92. items are displayed in the select, similar to a form select multiple).
  93. 3) There's a new property: #config. This must be an
  94. array. These are the items it can contain:
  95. - module (required)
  96. This will be passed through in the AJAX requests, to let Hierarchical
  97. Select know which module's hooks should be used.
  98. - params (optional, may be necessary for some implementations)
  99. An array of parameters that will also be passed through in every AJAX
  100. request.
  101. e.g. In the case of taxonomy, this is the vocabulary id (vid). In case of
  102. content_taxonomy, there's three parameters: vid, tid and depth (tid allows
  103. one to define a new root, depth allows one to limit the depth of the
  104. displayed hierarchy).
  105. - save_lineage (optional, defaults to 0)
  106. Triggers the lineage saving functionality. If enabled, the selection can
  107. consist of multiple values.
  108. - enforce_deepest (optional, defaults to 0)
  109. Triggers the enforcing of a selection in the deepest level. If enabled, the
  110. selection will always be a single value.
  111. - resizable (optional, defaults to 1)
  112. Makes the hierarchical select resizable.
  113. - level_labels['status'] (optional, defaults to 0)
  114. Whether level labels should be enabled or not. When save_lineage is
  115. enabled, this will result in *empty* level labels.
  116. - level_labels['labels'] (optional)
  117. An array of labels, one per level. The label for the first level should be
  118. the value of key 0.
  119. When enforce_deepest is set to:
  120. - 0, then you can provide n level labels, with n the number of levels
  121. - 1, then you can provide only one level label.
  122. - dropbox['status'] (optional, defaults to 0)
  123. Whether the dropbox is enabled or not (the dropbox allows the user to make
  124. multiple selections).
  125. - dropbox['title'] (optional, defaults to "All selections:")
  126. The title of the dropbox. The dropbox is the area where all selections are
  127. displayed when the dropbox is enabled.
  128. - dropbox['limit'] (optional, defaults to 0, which means "no limit")
  129. Limit the number of selection that can be added to the dropbox. So this
  130. allows you the restrict the number of items that can be selected when
  131. the dropbox has been enabled.
  132. - dropbox['reset_hs'] (optional, defaults to 1, which means "do reset")
  133. Determines what will happen to the hierarchical select when the user has
  134. added a selection to the dropbox.
  135. - dropbox['sort'] (optional, defaults to 1, which means "do sort")
  136. Determines whether the items in the dropbox will be automatically sorted.
  137. - editability['status] (optional, defaults to 0)
  138. Allow the user to create new items in the hierarchy.
  139. - editability['item_types'] (optional, defaults to the empty array)
  140. Only meaningful when editable is set to TRUE.
  141. Set the item type for each level. E.g.: "country" for the first level,
  142. "region" for the second and "city" for the third. When the user then wants
  143. to create a new item, the default label for the new item will be of the
  144. form "new <item type>", e.g. "new region".
  145. - editability['allowed_levels'] (optional, defaults to 1 for each level)
  146. Only meaningful when editable is set to TRUE.
  147. Specify in which levels the user is allowed to create new items. In the
  148. example, the user is only allowed to create new items in the third level.
  149. When a setting for a level is ommitted, it defaults to 1 (i.e. allowed for
  150. that level). This means you only have to specify in which levels the user
  151. is not allowed to create new items.
  152. This only applies to *existing* levels: it does not affect the
  153. allow_new_levels setting (the next setting).
  154. - editability['allow_new_levels'] (optional, defaults to 0)
  155. Only meaningful when editable is set to TRUE.
  156. Allow the user to create new levels, i.e. when a certain item does not yet
  157. have children, the user can create a first child for it (thus thereby
  158. creating a new level).
  159. - editability['max_levels'] (optional, defaults to 3)
  160. Only meaningful when editable_settings['allow_new_levels'] is set to TRUE.
  161. Limits the maximum number of levels. Don't set this too high or you'll end
  162. up with very deep hierarchies. This only affects how deep new levels can be
  163. created, it will not affect the existing hierarchy.
  164. - entity_count['enabled'] (optional, defaults to 0)
  165. Enables the display of entity counts, between parentheses, for each item in
  166. the hierarchy.
  167. - entity_count['require_entity'] (optional, defaults to 0)
  168. Whether an item should only be displayed if it has at least one associated
  169. entity.
  170. - entity_count['settings']['count_children'] (optional, defaults to 0)
  171. Whether the entity count should also count associated children of the entity.
  172. - entity_count['settings']['entity_types'] (optional, defaults to array())
  173. Which types of entities should be counted. This is a list of checkboxes that
  174. allow the user to select entity types by bundles.
  175. - animation_delay (optional, defaults to 400)
  176. The delay of each animation (the drop in left and right animations), in ms.
  177. - special_items (optional, defaults to the empty array)
  178. Through this setting, you can mark each item with special properties it
  179. possesses. There currently are two special properties: 'exclusive' and
  180. 'none'.
  181. Note: you should include these items in the hierarchy as if it were a
  182. normal item and then you can mark them as special through this property.
  183. * 'exclusive': Sometimes it's desirable to have exclusive lineages. When
  184. such an option is selected, the user should not be able to
  185. select anything else. This also means that nothing else in
  186. the dropbox can be selected: if the dropbox contains
  187. anything, it will be reset.
  188. Can be applied to multiple items.
  189. e.g. an 'entire_tree' item:
  190. 'special_items' => array(
  191. 'entire_tree' => array('exclusive'),
  192. )
  193. * 'none': Sometimes you want to replace the default '<none>' option by
  194. something else. This replacement should of course also exist in
  195. the root level.
  196. Can be applied to only one item.
  197. e.g. an 'any' item (used in hs_taxonomy_views):
  198. 'special_items' => array(
  199. 'any' => array('none', 'exclusive'),
  200. )
  201. And a final example for a better overview:
  202. 'special_items' => array(
  203. 'entire_tree' => array('exclusive'),
  204. 'any' => array('none', 'exclusive'),
  205. )
  206. - render_flat_select (optional, defaults to 0)
  207. Because the hierarchical_select form element consists of multiple form
  208. items, it doesn't work well in GET forms. By enabling this setting, a flat
  209. select will also be rendered, that contains only the selected lineages.
  210. Combine that with Drupal.HierarchicalSelect.prepareGETSubmit in the JS code
  211. (or, alternatively, the 'prepare-GET-submit' event that can be triggered,
  212. see the JavaScript events section for details) and you have a work-around
  213. (which, admittedly, only works when JS is enabled).
  214. 3) We *don't* specify a list of options: Hierarchical Select automatically
  215. generates the options for us, thanks to the 'module' and 'params' settings.
  216. Concepts
  217. --------
  218. - Item Unicity: each item in the hierarchy must be *unique*. It doesn't have
  219. to be numerical, it can also be a string.
  220. If your hierarchy does not have unique items by nature or by
  221. design (your items may be unique per level instead), that's
  222. not a problem. You can simply prepend the item's ancestors to
  223. get a unique item.
  224. e.g. you have an item "foobar" at the first, second and third
  225. levels. By prepending the ancestors using the dash as the
  226. separator, you'd get an item "foobar-foobar-foobar" at the
  227. third level.
  228. Also see the "Reserved item values" section.
  229. - #options: it's gone, because it was the inherent cause for scalability
  230. problems: if a hierarchy consists of 10,000 or even 100,000 items,
  231. this results in huge HTML being generated. Huge HTML means more
  232. processing power necessary, and more bandwidth necessary. So where
  233. does Hierarchical Select get its "options"? It uses the hooks that
  234. every implementation has to implement to only get what it needs.
  235. - The General Concept: you should think of Hierarchical Select as an abstract
  236. widget that can represent *any* hierarchy. To be able
  237. to display any hierarchy, you obviously need some
  238. universal way to "browse" a hierarchy.
  239. If you are familiar with C++ or Java iterators, this
  240. should come natural: the hooks you have to implement
  241. is what allows Hierarchical Select to iterate over your
  242. hierarchy. Then the heart of the iterator would be the
  243. root_level() and children() hooks. params() allows you
  244. to define which information is necessary before you can
  245. determine *which* hierarchy or which *part* of the
  246. hierarchy is being browsed. lineage() must return the
  247. lineage, i.e. the item itself and all its ancestors,
  248. this allows a hierarchy to be generated from just one
  249. (selected) item.
  250. Reserved item values
  251. --------------------
  252. - Ensure that your items don't have a "none", "all", "create_new_item" nor
  253. "label_\d+" values (the latter means "label_" followed by one or more
  254. digits). Your values should also not contain a pipe ("|"), since pipes are
  255. used to separate the selection of values that are sent back to the server
  256. in the callbacks.
  257. - Valid 'empty' selections (i.e. if you want to set the #default_value
  258. property of your form item), are -1 and the empty array. The empty string is
  259. also considered valid, because Drupal core's Taxonomy module uses this as
  260. the empty selection.
  261. Developer mode
  262. --------------
  263. When you are writing your implementation of the Hierarchical Select API, you
  264. will often wonder what Hierarchical Select is doing internally with the data
  265. you're feeding it. That's why there's a developer mode: it will show you this
  266. data, even the data generated in AJAX callbacks. It'll also show you the time
  267. it took to generate the lineage, to fill up the levels and to calculate the
  268. child info, to track down badly performing code.
  269. Also, when you're just creating a new HS config and it doesn't quite work
  270. right, it can be helpful to enable the developer mode. It will perform some
  271. basic diagnostics that might help you track down the cause.
  272. To use this, you must have a browser with console.log() support. Install
  273. Firebug Lite (http://getfirebug.com/lite.html) if your browser does not
  274. suport this. Next, go to Hierarchical Select's .module file and set the define
  275. for the HS_DEVELOPER_MODE constant to TRUE.
  276. When you now open Firebug (Firefox) or the Web Inspector (Safari), you'll see
  277. the debug output. New output is added after each callback to the server.
  278. Hierarchical Select implementations: gotcha's
  279. ---------------------------------------------
  280. - "warning: Missing argument 1 for drupal_retrieve_form() …"
  281. This implies that your implementation's module weight is heavier than
  282. hierarchical_select.module. In that case, Hierarchical Select will not be
  283. able to detect hierarchical_select form items, preventing it from applying
  284. some magic, and AJAX updates won't work.
  285. Hierarchical Select compatibility: gotcha's
  286. -------------------------------------------
  287. - "Invalid response from server"
  288. This typically means that some functions could not be found when
  289. Hierarchical Select does an AJAX callback to the server, which in turn means
  290. that some code (some PHP file) has not been included, while it should have
  291. been. Instead of using module_load_include() or even require_once, you
  292. should use form_load_include(). This function is new in Drupal 7 and will
  293. ensure that all required PHP files are included automatically.
  294. Hierarchical Select API Tutorial
  295. --------------------------------
  296. Written by Stephen Barker of Digital Frontiers Media
  297. (http://drupal.org/user/106070) and reviewed by Wim Leers:
  298. http://drupal.org/node/532724
  299. Hierarchical Select Small Hierarchy
  300. -----------------------------------
  301. Hierarchical Select includes a Hierarchical Select API implementation that
  302. allows one to use a hardcoded hierarchy. When it becomes to slow, you should
  303. move the hierarchy into the database and write a proper implementation.
  304. Below you can find an example of how to use the hs_smallhierarchy module. Just
  305. change the $hierarchy array to suit your needs and off you go! Look at the
  306. code of hs_smallhierarchy.module for full details, but this code example
  307. should get you started.
  308. $hierarchy = array(
  309. 'win' => array(
  310. 'label' => 'Windows',
  311. 'children' => array(
  312. 'xp' => array('label' => 'XP'),
  313. 'vista' => array(
  314. 'label' => 'Vista',
  315. 'children' => array(
  316. 'x86' => array('label' => '32-bits'),
  317. 'x64' => array('label' => '64-bits'),
  318. ),
  319. ),
  320. ),
  321. ),
  322. );
  323. $form['select_some_term'] = array(
  324. '#type' => 'hierarchical_select',
  325. '#title' => t('Select the tag you wish to use.'),
  326. '#size' => 1,
  327. '#config' => array(
  328. 'module' => 'hs_smallhierarchy',
  329. 'params' => array(
  330. 'hierarchy' => $hierarchy,
  331. 'id' => 'my-hierarchy-about-windows',
  332. 'separator' => '|',
  333. ),
  334. 'save_lineage' => 0,
  335. 'enforce_deepest' => 0,
  336. 'resizable' => 1,
  337. 'level_labels' => array(
  338. 'status' => 0,
  339. 'labels' => array(
  340. 0 => t('Main category'),
  341. 1 => t('Subcategory'),
  342. 2 => t('Third level category'),
  343. ),
  344. ),
  345. 'dropbox' => array(
  346. 'status' => 0,
  347. 'title' => t('All selections'),
  348. 'limit' => 0,
  349. 'reset_hs' => 1,
  350. 'sort' => 1,
  351. ),
  352. 'editability' => array(
  353. 'status' => 0,
  354. 'item_types' => array(),
  355. 'allowed_levels' => array(
  356. 0 => 0,
  357. 1 => 0,
  358. 2 => 1,
  359. ),
  360. 'allow_new_levels' => 0,
  361. 'max_levels' => 3,
  362. ),
  363. 'entity_count' => array(
  364. 'enabled' => 0,
  365. 'require_entity' => 0,
  366. 'settings' => array(
  367. 'count_children' => 0,
  368. 'entity_types' => array(),
  369. ),
  370. ),
  371. // These settings cannot be configured through the UI: they can only be
  372. // overridden through code.
  373. 'animation_delay' => 400,
  374. 'exclusive_lineages' => array(),
  375. 'render_flat_select' => 0,
  376. ),
  377. '#description' => 'Put your description here',
  378. '#default_value' => 'win|xp|x86',
  379. );
  380. Hooks
  381. -----
  382. 1) hook_hierarchical_select_params();
  383. Returns an array with the names of all parameters that are necessary for
  384. this implementation to work.
  385. 2) hook_hierarchical_select_root_level($params, $dropbox = FALSE);
  386. Returns the root level of the hierarchy: an array of (item, label) pairs.
  387. The $dropbox parameter can is optional and can even ommitted, as it's only
  388. necessary if you need the dropbox to influence your hierarchy.
  389. 3) hook_hierarchical_select_children($parent, $params, $dropbox = FALSE);
  390. Gets the children of $parent ($parent is an item in the hierarchy) and
  391. returns them: an array of (item, label) pairs, or the empty array if the
  392. given $parent has no children.
  393. The $dropbox parameter can is optional and can even ommitted, as it's only
  394. necessary if you need the dropbox to influence your hierarchy.
  395. 4) hook_hierarchical_select_lineage($item, $params);
  396. Calculates the lineage of $item (array of items, with $item the last) and
  397. returns it. Necessary when the "enforce_deepest" option is enabled.
  398. 5) hook_hierarchical_select_valid_item($item, $params);
  399. Validates an item, returns TRUE if valid, FALSE if invalid.
  400. 6) hook_hierarchical_select_item_get_label($item, $params);
  401. Given a valid item, returns the label. Is only used for rendering the
  402. selections in the dropbox.
  403. 7) hook_hierarchical_select_create_item($label, $parent, $params);
  404. Given a parent item and the label of a new item, create a new item as a
  405. child of the parent item. When $parent == 0, this means a new item is being
  406. created at the root level.
  407. Optional hook. When this hook is not implemented, this functionality will
  408. never be used, even when you configure it that way in code.
  409. 8) hook_hierarchical_select_entity_count($item, $params);
  410. Given a item, get the number of entities (most of the time the entity type
  411. is 'node') that are related to the given item. Used for the entity_count
  412. and require_entity settings.
  413. Optional hook. When this hook is not implemented, this functionality will
  414. never be used, even when you configure it that way (i.e. when you enable
  415. the entity_count and require_entity settings).
  416. 9) hook_hierarchical_select_implementation_info();
  417. Return metadata about this implementation.
  418. This information is used to generate the implementations overview at
  419. admin/settings/hierarchical_select/implementations. The expected format is:
  420. array(
  421. 'hierarchy type' => t('Taxonomy'),
  422. 'entity type' => t('Node'),
  423. 'entity' => t('Story'),
  424. 'context type' => t('Node form'),
  425. 'context' => '',
  426. );
  427. another example:
  428. array(
  429. 'hierarchy type' => t('Taxonomy'),
  430. 'entity type' => t('Node'),
  431. 'entity' => '',
  432. 'context type' => t('Views exposed filter'),
  433. 'context' => t('some view'),
  434. );
  435. 10) hook_hierarchical_select_config_info();
  436. Return metadata about each available user-editable configuration for this
  437. implementation.
  438. Optional hook. This information is used to generate the configurations
  439. overview at admin/settings/hierarchical_select/configs. The expected
  440. format is:
  441. $config_info[$config_id] = array(
  442. 'config_id' => $config_id,
  443. 'hierarchy type' => t('Taxonomy'),
  444. 'hierarchy' => t($vocabulary->name),
  445. 'entity type' => t('Node'),
  446. 'entity' => implode(', ', array_map('t', $entities)),
  447. 'edit link' => "admin/content/taxonomy/edit/vocabulary/$vid",
  448. );
  449. Standardized configuration form
  450. -------------------------------
  451. Hierarchical Select 3 comes with a standardized configuration form:
  452. hierarchical_select_common_config_form(). This function accepts a lot of
  453. parameters, which allows you to use names typical to your module's hierarchy
  454. (e.g. 'leaf' instead of 'term' and 'tree' instead of 'vocabulary'). A submit
  455. handler is also provided, of course.
  456. An example:
  457. // I'm not configuring all parameters here. For an example of that, see one
  458. // of the included modules.
  459. $form['foobar_hierarchical_select_config'] = hierarchical_select_common_config_form($module, $params, $config_id, $defaults, $strings, $max_hierarchy_depth, $preview_is_required);
  460. // Add the the submit handler for the Hierarchical Select config form.
  461. $parents = array('foobar_hierarchical_select_config');
  462. $form['#submit'][] = 'hierarchical_select_common_config_form_submit';
  463. $form['#hs_common_config_form_parents'] = $parents;
  464. Configuration management
  465. ------------------------
  466. It's now possible to export Hierarchical Select configurations, and there is a
  467. function to set the configuration of a certain Hierarchical Select. Combine
  468. the two and you can manage your Hierarchical Select configurations in code!
  469. An example:
  470. // The exported configuration.
  471. $config = array( … );
  472. $config_id = $config['config_id];
  473. // Apply the configuration.
  474. require_once(drupal_get_path('module', 'hierarchical_select') .'/includes/common.inc');
  475. hierarchical_select_common_config_set($config_id, $config);
  476. JavaScript events
  477. -----------------
  478. The Hierarchical Select module's JavaScript code triggers several events, to
  479. allow for advanced interactions.
  480. You can find all hierarchical_select form items using this selector:
  481. $('.hierarchical-select-wrapper');
  482. You can find a *specific* hierarchical_select form item using this selector:
  483. $('#hierarchical-select-x-wrapper');
  484. where x is a number, or more accurately: a hsid (hierarchical select id).
  485. Retrieving all hsids in the current document can be done like this:
  486. for (var hsid in Drupal.settings.HierarchicalSelect.settings) {
  487. // …
  488. }
  489. Alternatively, you can use one of the transliterated class names. A wrapper
  490. for Hierarchical Select looks like this:
  491. <div class="hierarchical-select-wrapper
  492. hierarchical-select-level-labels-style-none
  493. hierarchical-select-wrapper-for-name-edit-taxonomy-1
  494. hierarchical-select-wrapper-for-config-taxonomy-1
  495. hierarchical-select-wrapper-processed"
  496. id="hierarchical-select-35-wrapper">
  497. </div>
  498. Hence, you could also use selectors such as these, to achieve the same effect,
  499. but with more robust code:
  500. $('.hierarchical-select-wrapper-for-config-taxonomy-1:first')
  501. .trigger('enforce-update');
  502. $('.hierarchical-select-wrapper-for-name-edit-taxonomy-1:first')
  503. .trigger('enforce-update');
  504. The following events are triggered:
  505. - change-hierarchical-select
  506. - update-hierarchical-select
  507. - create-new-item
  508. - cancel-new-item
  509. - add-to-dropbox (check https://www.drupal.org/node/1277068)
  510. - remove-from-dropbox
  511. - enforced-update
  512. - prepared-GET-submit
  513. All events are triggered *after* the animations have completed.
  514. However, it's often useful to do something *before* an event (especially
  515. because all of the above events perform an AJAX request to the server). So,
  516. the equivalent "before" events exist as well:
  517. - before-update-hierarchical-select
  518. - before-create-new-item
  519. - before-cancel-new-item
  520. - before-add-to-dropbox
  521. - before-remove-from-dropbox
  522. - before-enforced-update
  523. There is one exception: when the cache is enabled, the "before update
  524. hierarchical select" event will not be triggered. This makes sense, because
  525. updates from the cache are instantaneous.
  526. An example of binding a function to the 'create-new-item' event of the second
  527. (hsid == 1) hierarchical_select form item on the page:
  528. $('#hierarchical-select-1-wrapper')
  529. .bind('create-new-item', function() {
  530. // …
  531. });
  532. And finally, you can trigger a special event to enforce an update (this can be
  533. useful when you have changed a hierarchy through another form item, or for
  534. live previews, or …). You can then also pass additional information that will
  535. be POSTed. You can even disable normal updates, to manage that completely
  536. yourself via enforced updates. This allows you to write a Hierarchical Select
  537. implementation that gets some of its information ($params) from another form
  538. item!
  539. Suppose you'd like to enforce an update of the first (hsid == 0)
  540. hierarchical_select form item on the page:
  541. $('#hierarchical-select-0-wrapper')
  542. .trigger('enforce-update');
  543. Now let's move on to a more advanced example, in which we will disable normal
  544. updates and let another form item (here a select) provide a part of the
  545. information that will be used to render the Hierarchical Select. Effectively,
  546. this other form item will *influence* the hierarchy that will be presented by
  547. Hierarchical Select!
  548. $(document).ready(function() {
  549. Drupal.settings.specialfilter = {};
  550. // .specialfilter-first: a select form item
  551. // .specialfilter-second: a hierarchical_select form item
  552. update = function() {
  553. var selection = Drupal.settings.specialfilter.currentSelection;
  554. // Send an extra parameter via POST: dynamicParameter. This is the stored
  555. // selection.
  556. $('.specialfilter-second')
  557. .trigger('enforce-update',
  558. [
  559. { name : 'dynamicParameter', value : selection }
  560. ]
  561. );
  562. };
  563. attachHSBindings = function() {
  564. // When a user navigates the hierarchical_select form item, we still want to
  565. // POST the the extra dynamicParameter, or otherwise we will no longer have
  566. // a hierarchy in the hierarchical_select form item that really depends on
  567. // the select.
  568. $('.specialfilter-second .hierarchical-select > select')
  569. .change(function() { update(); });
  570. $('.specialfilter-second')
  571. .unbind('enforced-update').bind('enforced-update', function() { return attachHSBindings(); });
  572. };
  573. // Initialize after 25 ms, because otherwise the event binding of HS will
  574. // not yet be ready, and hence this won't have any effect
  575. setTimeout(function() {
  576. // Get the initial selection (before the user has changed anything).
  577. Drupal.settings.specialfilter.currentSelection = $('.specialfilter-first').attr('value');
  578. // When the select form item changes, we want to *store* that selection, and
  579. // update the hierarchical_select form item.
  580. $('.specialfilter-first')
  581. .change(function() {
  582. // Store the current selection.
  583. Drupal.settings.specialfilter.currentSelection = $(this).attr('value');
  584. update();
  585. });
  586. $('.specialfilter-second')
  587. .trigger('disable-updates');
  588. attachHSBindings();
  589. }, 25);
  590. });
  591. The 'enforced-update' (notice the past tense!) event is triggered upon
  592. completion.
  593. An even more rarely used special event can be triggered to prepare the
  594. hierarchical_select form element for a get submit: the 'prepare GET submit'
  595. event. To use this event, the 'render_flat_select' setting should be enabled
  596. in the config.