options.module

<?php
/**
 * @file
 * Defines selection, check box and radio button widgets for text and numeric fields.
 */

/**
 * Implements hook_theme().
 */
function options_theme() {
  return array(
    'options_none' => array(
      'variables' => array('instance' => NULL, 'option' => NULL),
      'file' => 'options.theme.inc',
    ),
    'options' => array(
      'render element' => 'element',
      'file' => 'options.theme.inc',
    ),
  );
}

/**
 * Implements hook_library_info().
 */
function options_library_info() {
  $path = backdrop_get_path('module', 'options');
  $libraries['options'] = array(
    'title' => 'Options',
    'version' => BACKDROP_VERSION,
    'js' => array(
      $path . '/js/options.js' => array(),
      'core/misc/tabledrag.js' => array('group' => JS_LIBRARY, 'weight' => 5),
      'core/misc/jquery.cookie.js' => array('group' => JS_LIBRARY),
    ),
    'css' => array(
     $path . '/css/options.css' => array(),
    ),
  );
  return $libraries;
}

/**
 * Implements hook_field_widget_info().
 *
 * Field type modules willing to use those widgets should:
 * - Use hook_field_widget_info_alter() to append their field own types to the
 *   list of types supported by the widgets,
 * - Implement hook_options_list() to provide the list of options.
 * See list.module.
 */
function options_field_widget_info() {
  return array(
    'options_select' => array(
      'label' => t('Select list'),
      'field types' => array(),
      'behaviors' => array(
        'multiple values' => FIELD_BEHAVIOR_CUSTOM,
      ),
    ),
    'options_buttons' => array(
      'label' => t('Check boxes/radio buttons'),
      'field types' => array(),
      'behaviors' => array(
        'multiple values' => FIELD_BEHAVIOR_CUSTOM,
      ),
    ),
    'options_onoff' => array(
      'label' => t('Single on/off checkbox'),
      'field types' => array(),
      'behaviors' => array(
        'multiple values' => FIELD_BEHAVIOR_CUSTOM,
      ),
      'settings' => array('display_label' => 0),
    ),
  );
}

/**
 * Implements hook_field_widget_form().
 */
function options_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) {
  // Abstract over the actual field columns, to allow different field types to
  // reuse those widgets.
  $value_key = key($field['columns']);

  $type = str_replace('options_', '', $instance['widget']['type']);
  $multiple = $field['cardinality'] > 1 || $field['cardinality'] == FIELD_CARDINALITY_UNLIMITED;
  $required = $element['#required'];
  $has_value = isset($items[0][$value_key]);
  $properties = _options_properties($type, $multiple, $required, $has_value);

  $entity_type = $element['#entity_type'];
  $entity = $element['#entity'];

  // Prepare the list of options.
  $options = _options_get_options($field, $instance, $properties, $entity_type, $entity);

  // Put current field values in shape.
  $default_value = _options_storage_to_form($items, $options, $value_key, $properties);

  switch ($type) {
    case 'select':
      $element += array(
        '#type' => 'select',
        '#default_value' => $default_value,
        // Do not display a 'multiple' select box if there is only one option.
        '#multiple' => $multiple && count($options) > 1,
        '#options' => $options,
      );
      break;

    case 'buttons':
      // If required and there is one single option, preselect it.
      if ($required && count($options) == 1) {
        reset($options);
        $default_value = array(key($options));
      }

      // If this is a single-value field, take the first default value, or
      // default to NULL so that the form element is properly recognized as
      // not having a default value.
      if (!$multiple) {
        $default_value = $default_value ? reset($default_value) : NULL;
      }

      $element += array(
        '#type' => $multiple ? 'checkboxes' : 'radios',
        // Radio buttons need a scalar value.
        '#default_value' => $default_value,
        '#options' => $options,
      );
      break;

    case 'onoff':
      $keys = array_keys($options);
      $off_value = array_shift($keys);
      $on_value = array_shift($keys);
      $element += array(
        '#type' => 'checkbox',
        '#default_value' => (isset($default_value[0]) && $default_value[0] == $on_value) ? 1 : 0,
        '#on_value' => $on_value,
        '#off_value' => $off_value,
      );
      // Override the title from the incoming $element.
      $element['#title'] = isset($options[$on_value]) ? $options[$on_value] : '';

      if ($instance['widget']['settings']['display_label']) {
        $element['#title'] = $instance['label'];
      }
      break;
  }

  $element += array(
    '#value_key' => $value_key,
    '#element_validate' => array('options_field_widget_validate'),
    '#properties' => $properties,
  );

  return $element;
}

/**
 * Implements hook_field_widget_settings_form().
 */
function options_field_widget_settings_form($field, $instance) {
  $form = array();
  if ($instance['widget']['type'] == 'options_onoff') {
    $form['display_label'] = array(
      '#type' => 'checkbox',
      '#title' => t('Use field label instead of the "On value" as label'),
      '#default_value' => $instance['widget']['settings']['display_label'],
      '#weight' => -1,
    );
  }
  return $form;
}

/**
 * Form element validation handler for options element.
 */
function options_field_widget_validate($element, &$form_state) {
  if ($element['#required'] && $element['#value'] == '_none') {
    form_error($element, t('!name field is required.', array('!name' => $element['#title'])));
  }
  // Transpose selections from field => delta to delta => field, turning
  // multiple selected options into multiple parent elements.
  $items = _options_form_to_storage($element);
  form_set_value($element, $items, $form_state);
}

/**
 * Describes the preparation steps required by each widget.
 */
function _options_properties($type, $multiple, $required, $has_value) {
  $base = array(
    'filter_xss' => FALSE,
    'strip_tags' => FALSE,
    'strip_tags_and_unescape' => FALSE,
    'empty_option' => FALSE,
    'optgroups' => FALSE,
  );

  $properties = array();

  switch ($type) {
    case 'select':
      $properties = array(
        // Select boxes do not support any HTML tag.
        'strip_tags_and_unescape' => TRUE,
        'optgroups' => TRUE,
      );
      if ($multiple) {
        // Multiple select: add a 'none' option for non-required fields.
        if (!$required) {
          $properties['empty_option'] = 'option_none';
        }
      }
      else {
        // Single select: add a 'none' option for non-required fields,
        // and a 'select a value' option for required fields that do not come
        // with a value selected.
        if (!$required) {
          $properties['empty_option'] = 'option_none';
        }
        elseif (!$has_value) {
          $properties['empty_option'] = 'option_select';
        }
      }
      break;

    case 'buttons':
      $properties = array(
        'filter_xss' => TRUE,
      );
      // Add a 'none' option for non-required radio buttons.
      if (!$required && !$multiple) {
        $properties['empty_option'] = 'option_none';
      }
      break;

    case 'onoff':
      $properties = array(
        'filter_xss' => TRUE,
      );
      break;
  }

  return $properties + $base;
}

/**
 * Collects the options for a field.
 */
function _options_get_options($field, $instance, $properties, $entity_type, $entity) {
  // Get the list of options.
  $options = (array) module_invoke($field['module'], 'options_list', $field, $instance, $entity_type, $entity);

  // Sanitize the options.
  _options_prepare_options($options, $properties);

  if (!$properties['optgroups']) {
    $options = options_array_flatten($options);
  }

  if ($properties['empty_option']) {
    $label = theme('options_none', array('instance' => $instance, 'option' => $properties['empty_option']));
    $options = array('_none' => $label) + $options;
  }

  return $options;
}

/**
 * Sanitizes the options.
 *
 * The function is recursive to support optgroups.
 */
function _options_prepare_options(&$options, $properties) {
  foreach ($options as $value => $label) {
    // Recurse for optgroups.
    if (is_array($label)) {
      _options_prepare_options($options[$value], $properties);
    }
    else {
      // The 'strip_tags' option is deprecated. Use 'strip_tags_and_unescape'
      // when plain text is required (and where the output will be run through
      // check_plain() before being inserted back into HTML) or 'filter_xss'
      // when HTML is required.
      if ($properties['strip_tags']) {
        $options[$value] = strip_tags($label);
      }
      if (!empty($properties['strip_tags_and_unescape'])) {
        $options[$value] = decode_entities(strip_tags($label));
      }
      if ($properties['filter_xss']) {
        $options[$value] = field_filter_xss($label);
      }
    }
  }
}

/**
 * Transforms stored field values into the format the widgets need.
 */
function _options_storage_to_form($items, $options, $column, $properties) {
  $items_transposed = options_array_transpose($items);
  $values = (isset($items_transposed[$column]) && is_array($items_transposed[$column])) ? $items_transposed[$column] : array();

  // Discard values that are not in the current list of options. Flatten the
  // array if needed.
  if ($properties['optgroups']) {
    $options = options_array_flatten($options);
  }
  $values = array_values(array_intersect($values, array_keys($options)));
  return $values;
}

/**
 * Transforms submitted form values into field storage format.
 */
function _options_form_to_storage($element) {
  $values = array_values((array) $element['#value']);
  $properties = $element['#properties'];

  // On/off checkbox: transform '0 / 1' into the 'on / off' values.
  if ($element['#type'] == 'checkbox') {
    $values = array($values[0] ? $element['#on_value'] : $element['#off_value']);
  }

  // Filter out the 'none' option. Use a strict comparison, because
  // 0 == 'any string'.
  if ($properties['empty_option']) {
    $index = array_search('_none', $values, TRUE);
    if ($index !== FALSE) {
      unset($values[$index]);
    }
  }

  // Make sure we populate at least an empty value.
  if (empty($values)) {
    $values = array(NULL);
  }

  $result = options_array_transpose(array($element['#value_key'] => $values));
  return $result;
}

/**
 * Manipulates a 2D array to reverse rows and columns.
 *
 * The default data storage for fields is delta first, column names second.
 * This is sometimes inconvenient for field modules, so this function can be
 * used to present the data in an alternate format.
 *
 * @param $array
 *   The array to be transposed. It must be at least two-dimensional, and
 *   the subarrays must all have the same keys or behavior is undefined.
 * @return
 *   The transposed array.
 */
function options_array_transpose($array) {
  $result = array();
  if (is_array($array)) {
    foreach ($array as $key1 => $value1) {
      if (is_array($value1)) {
        foreach ($value1 as $key2 => $value2) {
          if (!isset($result[$key2])) {
            $result[$key2] = array();
          }
          $result[$key2][$key1] = $value2;
        }
      }
    }
  }
  return $result;
}

/**
 * Flattens an array of allowed values.
 *
 * @param $array
 *   A single or multidimensional array.
 * @return
 *   A flattened array.
 */
function options_array_flatten($array) {
  $result = array();
  if (is_array($array)) {
    foreach ($array as $key => $value) {
      if (is_array($value)) {
        $result += options_array_flatten($value);
      }
      else {
        $result[$key] = $value;
      }
    }
  }
  return $result;
}

/**
 * Implements hook_field_widget_error().
 */
function options_field_widget_error($element, $error, $form, &$form_state) {
  form_error($element, $error['message']);
}

/**
 * Implements hook_element_info().
 *
 * 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.
 *
 * @code
 * $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',
 * );
 * @endcode
 *
 * 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.
 *
 *   @code
 *   $element['options'] = array(
 *     '#type' => 'options',
 *     '#key_type' => 'associative',
 *     '#key_type_toggle' => t('Custom keys'),
 *     '#key_type_toggled' => TRUE,
 *   );
 *   @endcode
 */
function options_element_info() {
  $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'),
    '#theme_wrappers' => array('form_element'),
    '#attached' => array(
      'library' => array(
        array('options', 'options'),
      ),
    ),
  );

  return $type;
}

/**
 * Expand the "options" form element type.
 *
 * The "options" type is simply an enhanced textarea that makes it easier to
 * create key|value pairs and put items into optgroups.
 */
function form_options_expand($element) {
  module_load_include('inc', 'options', 'options.element');
  return _form_options_expand($element);
}

/**
 * Validate the "options" form element type.
 */
function form_options_validate($element, &$form_state) {
  module_load_include('inc', 'options', 'options.element');
  _form_options_validate($element, $form_state);
}

/**
 * This function adjusts the value of the element from a text value to an array.
 */
function form_type_options_value(&$element, $edit = FALSE) {
  module_load_include('inc', 'options', 'options.element');
  return _form_type_options_value($element, $edit);
}

/**
 * Create a textual representation of options from an array.
 *
 * @param $options
 *   An array of options used in a select list.
 * @param $key_type
 *   How key/value pairs should be interpreted. Available options:
 *   - mixed
 *   - numeric
 *   - associative
 *   - custom
 *   - none
 */
function form_options_to_text($options, $key_type) {
  module_load_include('inc', 'options', 'options.element');
  return _form_options_to_text($options, $key_type);
}

/**
 * Create an array representation of text option values.
 *
 * If the Key of the option is within < >, treat as an optgroup
 *
 * <Group 1>
 *   creates an optgroup with the label "Group 1"
 *
 * <>
 *   Exits the current group, allowing items to be inserted at the root element.
 */
function form_options_from_text($text, $key_type, $flat = FALSE, &$duplicates = array()) {
  module_load_include('inc', 'options', 'options.element');
  return _form_options_from_text($text, $key_type, $flat, $duplicates);
}

/**
 * Element #after_build callback for the options list in Field UI.
 */
function options_field_settings_after_build($element, &$form_state) {
  // Add original data for validating.
  $element['options_field'] = array_merge($element['options_field'], $element['#original']);
  // Standard validate.
  $element['options_field']['#element_validate'][] = 'list_allowed_values_setting_validate';
  return $element;
}

/**
 * Form #validate callback for Field UI forms that use an options element.
 */
function options_field_settings_validate($form, &$form_state) {
  if (!form_get_errors()) {
    // Set allowed values.
    form_set_value(
      $form['field']['settings']['allowed_values'],
      $form['field']['settings']['allowed_values']['#value']['options'],
      $form_state
    );
  }
}

/**
 * Form #validate callback for field_ui_field_edit_form().
 */
function options_field_instance_settings_validate($form, &$form_state) {
  $field = $form['#field'];

  if (!form_get_errors()) {
    // Set default values.
    $default_field_value_key = $form['instance']['default_value_widget'][$field['field_name']][LANGUAGE_NONE]['#value_key'];
    // Create transposed array for field storage.
    $default_values = options_array_transpose(array($default_field_value_key => (array)$form['field']['settings']['allowed_values']['#value']['default_value']));

    form_set_value(
      $form['instance']['default_value_widget'][$field['field_name']][LANGUAGE_NONE],
      $default_values,
      $form_state
    );
  }
}