dependent.inc 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181
  1. <?php
  2. /**
  3. * @file
  4. * Provide dependent checkboxes that can be easily used in forms.
  5. *
  6. * This system will ensure that form items are invisible if the dependency is
  7. * not met. What this means is that you set the #dependency of an item to a
  8. * list of form ids that must be set, and the list of values that qualify.
  9. *
  10. * For a simple use, setting an item to be dependent upon a select box, if
  11. * any of the listed values are selected, the item will be visible. Otherwise,
  12. * the item will be invisible.
  13. *
  14. * If dependent upon multiple items, use #dependency_count = X to set the
  15. * number of items that must be set in order to make this item visible. This
  16. * defaults to 1. If set to 2, then at least 2 form items in the list must
  17. * have their items set for the item to become visible.
  18. *
  19. * When hiding checkboxes and radios you need to add their id in a div
  20. * manually via #prefix and #suffix since they don't have their own id. You
  21. * actually need to add TWO divs because it's the parent that gets hidden.
  22. *
  23. * Fieldsets can not be hidden by default. Adding '#input' => TRUE to the
  24. * fieldset works around that.
  25. *
  26. * For radios, because they are selected a little bit differently, instead of
  27. * using the CSS id, use: radio:NAME where NAME is the #name of the property.
  28. * This can be quickly found by looking at the HTML of the generated form, but
  29. * it is usually derived from the array which contains the item. For example,
  30. * $form['menu']['type'] would have a name of menu[type]. This name is the same
  31. * field that is used to determine where in $form_state['values'] you will find
  32. * the value of the form.
  33. *
  34. * The item that is dependent on, should be set to #tree = TRUE.
  35. *
  36. * Usage:
  37. *
  38. * First, ensure this tool is loaded:
  39. * @code { ctools_include('dependent'); }
  40. *
  41. * On any form item, add
  42. * - @code '#dependency' => array('id-of-form-without-the-#' => array(list, of, values, that, make, this, gadget, visible)), @endcode
  43. *
  44. * A fuller example, that hides the menu title when no menu is selected:
  45. * @code
  46. *function ctools_dependent_example() {
  47. * $form = array();
  48. * $form['menu'] = array(
  49. * '#type' => 'fieldset',
  50. * '#title' => t('Menu settings'),
  51. * '#tree' => TRUE,
  52. * );
  53. * $form['menu']['type'] = array(
  54. * '#title' => t('Menu type'),
  55. * '#type' => 'radios',
  56. * '#options' => array(
  57. * 'none' => t('No menu entry'),
  58. * 'normal' => t('Normal menu entry'),
  59. * 'tab' => t('Menu tab'),
  60. * 'default tab' => t('Default menu tab'),
  61. * ),
  62. * '#default_value' => 'none',
  63. * );
  64. *
  65. * $form['menu']['title'] = array(
  66. * '#title' => t('Title'),
  67. * '#type' => 'textfield',
  68. * '#default_value' => '',
  69. * '#description' => t('If set to normal or tab, enter the text to use for the menu item.'),
  70. * '#dependency' => array('radio:menu[type]' => array('normal', 'tab', 'default tab')),
  71. * );
  72. *
  73. * return system_settings_form($form);
  74. *}
  75. * @endcode
  76. *
  77. * An example for hiding checkboxes using #prefix and #suffix:
  78. * @code
  79. *function ctools_dependent_example_checkbox() {
  80. * $form = array();
  81. * $form['object'] = array(
  82. * '#type' => 'fieldset',
  83. * '#title' => t('Select object type'),
  84. * '#tree' => TRUE,
  85. * );
  86. * $form['object']['type'] = array(
  87. * '#title' => t('Object type'),
  88. * '#type' => 'radios',
  89. * '#options' => array(
  90. * 'view' => t('View'),
  91. * 'node' => t('Node'),
  92. * 'field' => t('Field'),
  93. * 'term' => t('Term'),
  94. * ),
  95. * '#default_value' => 'view',
  96. * );
  97. *
  98. * $form['object']['elements'] = array(
  99. * '#title' => t('Select the elements to load from the node.'),
  100. * '#type' => 'checkboxes',
  101. * '#prefix' => '<div id="edit-elements-wrapper"><div id="edit-elements">',
  102. * '#suffix' => '</div></div>',
  103. * '#dependency' => array('radio:menu[type]' => array('node')),
  104. * '#options' => array(
  105. * 'body' => t('Body'),
  106. * 'fields' => t('Fields'),
  107. * 'taxonomy' => t('Taxonomy'),
  108. * ),
  109. * '#default_value' => array('body', 'fields'),
  110. * );
  111. *
  112. * return system_settings_form($form);
  113. *}
  114. * @endcode
  115. *
  116. * Deprecated:
  117. *
  118. * You no longer use ctools_dependent_process(), and it should be removed
  119. * completely.
  120. *
  121. * If you have a form element which isn't listed in ctools_dependent_element_info_alter
  122. * you have to add [#pre_render'][] => 'ctools_dependent_pre_render' to your form.
  123. */
  124. /**
  125. * Process callback to add dependency to form items.
  126. *
  127. */
  128. function ctools_dependent_process($element, &$form_state, &$form) {
  129. return $element;
  130. }
  131. function ctools_dependent_pre_render($element) {
  132. // Preprocess only items with #dependency set.
  133. if (isset($element['#dependency'])) {
  134. if (!isset($element['#dependency_count'])) {
  135. $element['#dependency_count'] = 1;
  136. }
  137. if (!isset($element['#dependency_type'])) {
  138. $element['#dependency_type'] = 'hide';
  139. }
  140. $js = array(
  141. 'values' => $element['#dependency'],
  142. 'num' => $element['#dependency_count'],
  143. 'type' => $element['#dependency_type'],
  144. );
  145. // Add a additional wrapper id around fieldsets, textareas to support depedency on it.
  146. if (in_array($element['#type'], array('textarea', 'fieldset', 'text_format'))) {
  147. $element['#theme_wrappers'][] = 'container';
  148. $element['#attributes']['id'] = $element['#id'] . '-wrapper';
  149. }
  150. // Text formats need to unset the dependency on the textarea
  151. // or it gets applied twice.
  152. if ($element['#type'] == 'text_format') {
  153. unset($element['value']['#dependency']);
  154. }
  155. $element['#attached']['js'][] = ctools_attach_js('dependent');
  156. $options['CTools']['dependent'][$element['#id']] = $js;
  157. $element['#attached']['js'][] = array('type' => 'setting', 'data' => $options);
  158. }
  159. return $element;
  160. }
  161. /**
  162. * CTools alters the element_info to be able to add #process functions to
  163. * every major form element to make it much more handy to use #dependency,
  164. * because you don't have to add #process.
  165. */
  166. function ctools_dependent_element_info_alter(&$type) {
  167. $form_elements = array('checkbox', 'checkboxes', 'date', 'fieldset', 'item', 'machine_name', 'markup', 'radio', 'radios', 'select', 'textarea', 'textfield', 'text_format');
  168. foreach ($form_elements as $element) {
  169. $type[$element]['#pre_render'][] = 'ctools_dependent_pre_render';
  170. }
  171. }