[Summary view] [Print] [Text view]

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