crm.fsf.org/20131203/files/sites/all/modules-new/ctools/includes/dependent.inc

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