function options_element_elements in Options Element 6

Implementation of hook_elements().

Defines the #type = 'options' form element type.

The 'options' form element type is useful when collecting a series of values in a list. The values within the list may optionally have unique keys, such as that in an array structure. In addition, a default choice (or several default choices) may be selected by the user.

$element['options'] = array(
  '#type' => 'options',
  '#limit' => 20,
  '#optgroups' => FALSE,
  '#multiple' => FALSE,
  '#options' => array(
    'foo' => 'foo',
    'bar' => 'bar',
    'baz' => 'baz',
  ),
  '#default_value' => 'foo'
  '#key_type' => 'associative',
);

Properties for the 'options' element include:

• limit: The maximum number of options that can be added to a list. Defaults to 100.
• optgroups: If nesting of options is supported, up to one level. This is used when building a select HTML element that uses optgroups. Defaults to FALSE.
• multiple: Affects the number of default values that may be selected.
• default_value: The key(s) for the options that are currently selected. If #multiple is TRUE then, the default value is an array, otherwise it is a string.
• options: An array of options currently within the list.
• key_type: The method by which keys are determined for each value in the option list. Available options include:
  • mixed: Each value is not given any ID automatically, but any manually specified keys will be retained. This most emulates the existing conventions within Drupal, where keys are optional but allowed.
  • numeric: Each value is automatically given a unique numeric ID. This can be useful when wanting duplicate values in a list and not have to bother the end-user for keys.
  • associative: Keys are automatically mapped from the user-entered values. This is equivalent to making key|value pairs, but both the key and value are the same. Each key must be unique.
  • custom: Keys are manually entered by the end user. A second set of textfields are presented to let the user provide keys as well as values.
  • none: No keys are specified at all. This effectively creates numeric keys but unlike numeric keys, the keys are renumbered if the options in the list are rearranged.
• key_type_toggle: If specified, a checkbox will be added that allows the user to toggle between the current key type and the "custom" key type, letting them customize the keys as desired. This option has no effect with the "none" key type.
• key_type_toggled: Determine if the toggle checkbox is set or not by default.
• default_value_allowed: Indicates whether the end user should be able to modify the default value when editing the options list. Defaults to TRUE.
• default_value_pattern: If allowing dynamic default value keys, such as a token, specify a regular expression pattern that will also be allowed as a default value. Include pattern delimiters. Defaults to an empty string.

$element['options'] = array(
  '#type' => 'options',
  '#key_type' => 'associative',
  '#key_type_toggle' => t('Custom keys'),
  '#key_type_toggled' => TRUE,
);

File

./options_element.module, line 82

Defines an "options" form element type for entering select list options.

Code

function options_element_elements() {
  $type = array();
  $type['options'] = array(
    '#input' => TRUE,
    '#process' => array(
      'form_options_expand',
    ),
    '#limit' => NULL,
    '#optgroups' => TRUE,
    '#multiple' => FALSE,
    '#options' => array(),
    '#options_readonly' => FALSE,
    '#key_type' => 'mixed',
    '#key_type_toggle' => NULL,
    '#key_type_toggled' => FALSE,
    '#default_value_allowed' => TRUE,
    '#default_value_pattern' => '',
    '#element_validate' => array(
      'form_options_validate',
    ),
  );
  return $type;
}