[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * @file
   5   * Defines an "options" form element type for entering select list options.
   6   */
   7  
   8  /**
   9   * Implementation of hook_elements().
  10   *
  11   * Defines the #type = 'options' form element type.
  12   *
  13   * The 'options' form element type is useful when collecting a series of
  14   * values in a list. The values within the list may optionally have unique
  15   * keys, such as that in a array structure. In addition, a default choice
  16   * (or several default choices) may be selected by the user.
  17   *
  18   * @code
  19   * $element['options'] = array(
  20   *   '#type' => 'options',
  21   *   '#limit' => 20,
  22   *   '#optgroups' => FALSE,
  23   *   '#multiple' => FALSE,
  24   *   '#options' => array(
  25   *     'foo' => 'foo',
  26   *     'bar' => 'bar',
  27   *     'baz' => 'baz',
  28   *   ),
  29   *   '#default_value' => 'foo'
  30   *   '#key_type' => 'associative',
  31   * );
  32   * @endcode
  33   *
  34   * Properties for the 'options' element include:
  35   * - limit: The maximum number of options that can be added to a list. Defaults
  36   *   to 100.
  37   * - optgroups: If nesting of options is supported, up to one level. This is
  38   *   used when building a select HTML element that uses optgroups. Defaults to
  39   *   FALSE.
  40   * - multiple: Affects the number of default values that may be selected.
  41   * - default_value: The key(s) for the options that are currently selected. If
  42   *   #multiple is TRUE then, the default value is an array, otherwise it is a
  43   *   string.
  44   * - options: An array of options currently within the list.
  45   * - key_type: The method by which keys are determined for each value in the
  46   *   option list. Available options include:
  47   *   - mixed: Each value is not given any ID automatically, but any manually
  48   *     specified keys will be retained. This most emulates the existing
  49   *     conventions within Drupal, where keys are optional but allowed.
  50   *   - numeric: Each value is automatically given a unique numeric ID. This can
  51   *     be useful when wanting duplicate values in a list and not have to bother
  52   *     the end-user for keys.
  53   *   - associative: Keys are automatically mapped from the user-entered values.
  54   *     This is equivalent to making key|value pairs, but both the key and value
  55   *     are the same. Each key must be unique.
  56   *   - custom: Keys are manually entered by the end user. A second set of
  57   *     textfields are presented to let the user provide keys as well as values.
  58   *   - none: No keys are specified at all. This effectively creates numeric keys
  59   *     but unlike numeric keys, the keys are renumbered if the options in the
  60   *     list are rearranged.
  61   * - key_type_toggle: If specified, a checkbox will be added that allows the
  62   *   user to toggle between the current key type and the "custom" key type,
  63   *   letting them customize the keys as desired. This option has no effect with
  64   *   the "none" key type.
  65   * - key_type_toggled: Determine if the toggle checkbox is set or not by
  66   *   default.
  67   * - default_value_allowed: Indicates whether the end user should be able to
  68   *   modify the default value when editing the options list. Defaults to TRUE.
  69   * - default_value_pattern: If allowing dynamic default value keys, such as a
  70   *   token, specify a regular expression pattern that will also be allowed as
  71   *   a default value. Include pattern delimiters. Defaults to an empty string.
  72   *
  73   *   @code
  74   *   $element['options'] = array(
  75   *     '#type' => 'options',
  76   *     '#key_type' => 'associative',
  77   *     '#key_type_toggle' => t('Custom keys'),
  78   *     '#key_type_toggled' => TRUE,
  79   *   );
  80   *   @endcode
  81   */
  82  function options_element_elements() {
  83    $type = array();
  84  
  85    $type['options'] = array(
  86      '#input' => TRUE,
  87      '#process' => array('form_options_expand'),
  88      '#limit' => 100,
  89      '#optgroups' => TRUE,
  90      '#multiple' => FALSE,
  91      '#options' => array(),
  92      '#key_type' => 'mixed',
  93      '#key_type_toggle' => NULL,
  94      '#key_type_toggled' => FALSE,
  95      '#default_value_allowed' => TRUE,
  96      '#default_value_pattern' => '',
  97      '#element_validate' => array('form_options_validate'),
  98      '#disabled' => FALSE,
  99    );
 100  
 101    return $type;
 102  }
 103  
 104  /**
 105   * Implementation of hook_theme().
 106   */
 107  function options_element_theme() {
 108    return array(
 109      'options' => array(
 110        'arguments' => array('element' => NULL),
 111        'file' => 'options_element.inc',
 112      ),
 113    );
 114  }
 115  
 116  /**
 117   * Expand the "options" form element type.
 118   *
 119   * The "options" type is simply an enhanced textarea that makes it easier to
 120   * create key|value pairs and put items into optgroups.
 121   */
 122  function form_options_expand($element) {
 123    module_load_include('inc', 'options_element');
 124    return _form_options_expand($element);
 125  }
 126  
 127  /**
 128   * Validate the "options" form element type.
 129   */
 130  function form_options_validate($element, &$form_state) {
 131    module_load_include('inc', 'options_element');
 132    _form_options_validate($element, $form_state);
 133  }
 134  
 135  /**
 136   * This function adjusts the value of the element from a text value to an array.
 137   */
 138  function form_type_options_value(&$element, $edit = FALSE) {
 139    module_load_include('inc', 'options_element');
 140    return _form_type_options_value($element, $edit);
 141  }
 142  
 143  /**
 144   * Create a textual representation of options from an array.
 145   *
 146   * @param $options
 147   *   An array of options used in a select list.
 148   * @param $key_type
 149   *   How key/value pairs should be interpreted. Available options:
 150   *   - mixed
 151   *   - numeric
 152   *   - associative
 153   *   - custom
 154   *   - none
 155   */
 156  function form_options_to_text($options, $key_type) {
 157    module_load_include('inc', 'options_element');
 158    return _form_options_to_text($options, $key_type);
 159  }
 160  
 161  /**
 162   * Create an array representation of text option values.
 163   *
 164   * If the Key of the option is within < >, treat as an optgroup
 165   * 
 166   * <Group 1>
 167   *   creates an optgroup with the label "Group 1"
 168   * 
 169   * <>
 170   *   Exits the current group, allowing items to be inserted at the root element.
 171   */
 172  function form_options_from_text($text, $key_type, $flat = FALSE, &$duplicates = array()) {
 173    module_load_include('inc', 'options_element');
 174    return _form_options_from_text($text, $key_type, $flat, $duplicates);
 175  }