options.module

<?php

/**
 * @file
 * Defines selection, check box and radio button widgets for text and numeric fields.
 */
use Drupal\field\FieldUpdateForbiddenException;
use Drupal\Core\Entity\Query\QueryFactory;

/**
 * Implements hook_help().
 */
function options_help($path, $arg) {
  switch ($path) {
    case 'admin/help#options':
      $output = '';
      $output .= '<h3>' . t('About') . '</h3>';
      $output .= '<p>' . t('The Options module defines various fields for storing a list of items, for use with the Field module. Usually these items are entered through a select list, checkboxes, or radio buttons. See the <a href="@field-help">Field module help page</a> for more information about fields.', array(
        '@field-help' => url('admin/help/field'),
      )) . '</p>';
      return $output;
  }
}

/**
 * Implements hook_theme().
 */
function options_theme() {
  return array(
    'options_none' => array(
      'variables' => array(
        'instance' => NULL,
        'option' => NULL,
      ),
    ),
  );
}

/**
 * Implements hook_field_info().
 */
function options_field_info() {
  return array(
    'list_integer' => array(
      'label' => t('List (integer)'),
      'description' => t("This field stores integer values from a list of allowed 'value => label' pairs, i.e. 'Lifetime in days': 1 => 1 day, 7 => 1 week, 31 => 1 month."),
      'settings' => array(
        'allowed_values' => array(),
        'allowed_values_function' => '',
      ),
      'default_widget' => 'options_select',
      'default_formatter' => 'list_default',
    ),
    'list_float' => array(
      'label' => t('List (float)'),
      'description' => t("This field stores float values from a list of allowed 'value => label' pairs, i.e. 'Fraction': 0 => 0, .25 => 1/4, .75 => 3/4, 1 => 1."),
      'settings' => array(
        'allowed_values' => array(),
        'allowed_values_function' => '',
      ),
      'default_widget' => 'options_select',
      'default_formatter' => 'list_default',
    ),
    'list_text' => array(
      'label' => t('List (text)'),
      'description' => t("This field stores text values from a list of allowed 'value => label' pairs, i.e. 'US States': IL => Illinois, IA => Iowa, IN => Indiana."),
      'settings' => array(
        'allowed_values' => array(),
        'allowed_values_function' => '',
      ),
      'default_widget' => 'options_select',
      'default_formatter' => 'list_default',
    ),
    'list_boolean' => array(
      'label' => t('Boolean'),
      'description' => t('This field stores simple on/off or yes/no options.'),
      'settings' => array(
        'allowed_values' => array(),
        'allowed_values_function' => '',
      ),
      'default_widget' => 'options_buttons',
      'default_formatter' => 'list_default',
    ),
  );
}

/**
 * Implements hook_field_settings_form().
 */
function options_field_settings_form($field, $instance, $has_data) {
  $settings = $field['settings'];
  switch ($field['type']) {
    case 'list_integer':
    case 'list_float':
    case 'list_text':
      $form['allowed_values'] = array(
        '#type' => 'textarea',
        '#title' => t('Allowed values list'),
        '#default_value' => options_allowed_values_string($settings['allowed_values']),
        '#rows' => 10,
        '#element_validate' => array(
          'options_field_settings_form_validate_allowed_values',
        ),
        '#field_has_data' => $has_data,
        '#field' => $field,
        '#field_type' => $field['type'],
        '#access' => empty($settings['allowed_values_function']),
      );
      $description = '<p>' . t('The possible values this field can contain. Enter one value per line, in the format key|label.');
      if ($field['type'] == 'list_integer' || $field['type'] == 'list_float') {
        $description .= '<br/>' . t('The key is the stored value, and must be numeric. The label will be used in displayed values and edit forms.');
        $description .= '<br/>' . t('The label is optional: if a line contains a single number, it will be used as key and label.');
        $description .= '<br/>' . t('Lists of labels are also accepted (one label per line), only if the field does not hold any values yet. Numeric keys will be automatically generated from the positions in the list.');
      }
      else {
        $description .= '<br/>' . t('The key is the stored value. The label will be used in displayed values and edit forms.');
        $description .= '<br/>' . t('The label is optional: if a line contains a single string, it will be used as key and label.');
      }
      $description .= '</p>';
      $form['allowed_values']['#description'] = $description;
      break;
    case 'list_boolean':
      $values = $settings['allowed_values'];
      $off_value = array_shift($values);
      $on_value = array_shift($values);
      $form['allowed_values'] = array(
        '#type' => 'value',
        '#description' => '',
        '#value_callback' => 'options_field_settings_form_value_boolean_allowed_values',
        '#access' => empty($settings['allowed_values_function']),
      );
      $form['allowed_values']['on'] = array(
        '#type' => 'textfield',
        '#title' => t('On value'),
        '#default_value' => $on_value,
        '#required' => FALSE,
        '#description' => t('If left empty, "1" will be used.'),
        // Change #parents to make sure the element is not saved into field
        // settings.
        '#parents' => array(
          'on',
        ),
      );
      $form['allowed_values']['off'] = array(
        '#type' => 'textfield',
        '#title' => t('Off value'),
        '#default_value' => $off_value,
        '#required' => FALSE,
        '#description' => t('If left empty, "0" will be used.'),
        // Change #parents to make sure the element is not saved into field
        // settings.
        '#parents' => array(
          'off',
        ),
      );

      // Link the allowed value to the on / off elements to prepare for the rare
      // case of an alter changing #parents.
      $form['allowed_values']['#on_parents'] =& $form['allowed_values']['on']['#parents'];
      $form['allowed_values']['#off_parents'] =& $form['allowed_values']['off']['#parents'];
      break;
  }

  // Alter the description for allowed values depending on the widget type.
  if ($instance['widget']['type'] == 'options_onoff') {
    $form['allowed_values']['#description'] .= '<p>' . t("For a 'single on/off checkbox' widget, define the 'off' value first, then the 'on' value in the <strong>Allowed values</strong> section. Note that the checkbox will be labeled with the label of the 'on' value.") . '</p>';
  }
  elseif ($instance['widget']['type'] == 'options_buttons') {
    $form['allowed_values']['#description'] .= '<p>' . t("The 'checkboxes/radio buttons' widget will display checkboxes if the <em>Number of values</em> option is greater than 1 for this field, otherwise radios will be displayed.") . '</p>';
  }
  $form['allowed_values']['#description'] .= '<p>' . t('Allowed HTML tags in labels: @tags', array(
    '@tags' => _field_filter_xss_display_allowed_tags(),
  )) . '</p>';
  $form['allowed_values_function'] = array(
    '#type' => 'value',
    '#value' => $settings['allowed_values_function'],
  );
  $form['allowed_values_function_display'] = array(
    '#type' => 'item',
    '#title' => t('Allowed values list'),
    '#markup' => t('The value of this field is being determined by the %function function and may not be changed.', array(
      '%function' => $settings['allowed_values_function'],
    )),
    '#access' => !empty($settings['allowed_values_function']),
  );
  return $form;
}

/**
 * Element validate callback; check that the entered values are valid.
 */
function options_field_settings_form_validate_allowed_values($element, &$form_state) {
  $field = $element['#field'];
  $has_data = $element['#field_has_data'];
  $field_type = $field['type'];
  $generate_keys = ($field_type == 'list_integer' || $field_type == 'list_float') && !$has_data;
  $values = options_extract_allowed_values($element['#value'], $field['type'], $generate_keys);
  if (!is_array($values)) {
    form_error($element, t('Allowed values list: invalid input.'));
  }
  else {

    // Check that keys are valid for the field type.
    foreach ($values as $key => $value) {
      if ($field_type == 'list_integer' && !preg_match('/^-?\\d+$/', $key)) {
        form_error($element, t('Allowed values list: keys must be integers.'));
        break;
      }
      if ($field_type == 'list_float' && !is_numeric($key)) {
        form_error($element, t('Allowed values list: each key must be a valid integer or decimal.'));
        break;
      }
      elseif ($field_type == 'list_text' && drupal_strlen($key) > 255) {
        form_error($element, t('Allowed values list: each key must be a string at most 255 characters long.'));
        break;
      }
    }

    // Prevent removing values currently in use.
    if ($has_data) {
      $lost_keys = array_diff(array_keys($field['settings']['allowed_values']), array_keys($values));
      if (_options_values_in_use($field, $lost_keys)) {
        form_error($element, t('Allowed values list: some values are being removed while currently in use.'));
      }
    }
    form_set_value($element, $values, $form_state);
  }
}

/**
* Form element #value_callback: assembles the allowed values for 'boolean' fields.
*/
function options_field_settings_form_value_boolean_allowed_values($element, $input, $form_state) {
  $on = drupal_array_get_nested_value($form_state['input'], $element['#on_parents']);
  $off = drupal_array_get_nested_value($form_state['input'], $element['#off_parents']);
  return array(
    $off,
    $on,
  );
}

/**
 * Implements hook_field_update_field().
 */
function options_field_update_field($field, $prior_field, $has_data) {
  drupal_static_reset('options_allowed_values');
}

/**
 * Returns the array of allowed values for a list field.
 *
 * The strings are not safe for output. Keys and values of the array should be
 * sanitized through field_filter_xss() before being displayed.
 *
 * @param $field
 *   The field definition.
 * @param $instance
 *   (optional) A field instance array. Defaults to NULL.
 * @param $entity_type
 *   (optional) The type of entity; e.g. 'node' or 'user'. Defaults to NULL.
 * @param $entity
 *   (optional) The entity object. Defaults to NULL.
 *
 * @return
 *   The array of allowed values. Keys of the array are the raw stored values
 *   (number or text), values of the array are the display labels.
 */
function options_allowed_values($field, $instance = NULL, $entity_type = NULL, $entity = NULL) {
  $allowed_values =& drupal_static(__FUNCTION__, array());
  if (!isset($allowed_values[$field['id']])) {
    $function = $field['settings']['allowed_values_function'];

    // If $cacheable is FALSE, then the allowed values are not statically
    // cached. See options_test_dynamic_values_callback() for an example of
    // generating dynamic and uncached values.
    $cacheable = TRUE;
    if (!empty($function)) {
      $values = $function($field, $instance, $entity_type, $entity, $cacheable);
    }
    else {
      $values = $field['settings']['allowed_values'];
    }
    if ($cacheable) {
      $allowed_values[$field['id']] = $values;
    }
    else {
      return $values;
    }
  }
  return $allowed_values[$field['id']];
}

/**
 * Parses a string of 'allowed values' into an array.
 *
 * @param $string
 *   The list of allowed values in string format described in
 *   options_allowed_values_string().
 * @param $field_type
 *   The field type. Either 'list_number' or 'list_text'.
 * @param $generate_keys
 *   Boolean value indicating whether to generate keys based on the position of
 *   the value if a key is not manually specified, and if the value cannot be
 *   used as a key. This should only be TRUE for fields of type 'list_number'.
 *
 * @return
 *   The array of extracted key/value pairs, or NULL if the string is invalid.
 *
 * @see options_allowed_values_string()
 */
function options_extract_allowed_values($string, $field_type, $generate_keys) {
  $values = array();
  $list = explode("\n", $string);
  $list = array_map('trim', $list);
  $list = array_filter($list, 'strlen');
  $generated_keys = $explicit_keys = FALSE;
  foreach ($list as $position => $text) {
    $value = $key = FALSE;

    // Check for an explicit key.
    $matches = array();
    if (preg_match('/(.*)\\|(.*)/', $text, $matches)) {
      $key = $matches[1];
      $value = $matches[2];
      $explicit_keys = TRUE;
    }
    elseif ($field_type == 'list_text' || $field_type == 'list_float' && is_numeric($text) || $field_type == 'list_integer' && is_numeric($text) && (double) $text == intval($text)) {
      $key = $value = $text;
      $explicit_keys = TRUE;
    }
    elseif ($generate_keys) {
      $key = (string) $position;
      $value = $text;
      $generated_keys = TRUE;
    }
    else {
      return;
    }

    // Float keys are represented as strings and need to be disambiguated
    // ('.5' is '0.5').
    if ($field_type == 'list_float' && is_numeric($key)) {
      $key = (string) (double) $key;
    }
    $values[$key] = $value;
  }

  // We generate keys only if the list contains no explicit key at all.
  if ($explicit_keys && $generated_keys) {
    return;
  }
  return $values;
}

/**
 * Generates a string representation of an array of 'allowed values'.
 *
 * This string format is suitable for edition in a textarea.
 *
 * @param $values
 *   An array of values, where array keys are values and array values are
 *   labels.
 *
 * @return
 *   The string representation of the $values array:
 *    - Values are separated by a carriage return.
 *    - Each value is in the format "value|label" or "value".
 */
function options_allowed_values_string($values) {
  $lines = array();
  foreach ($values as $key => $value) {
    $lines[] = "{$key}|{$value}";
  }
  return implode("\n", $lines);
}

/**
 * Implements hook_field_update_forbid().
 */
function options_field_update_forbid($field, $prior_field, $has_data) {
  if ($field['module'] == 'options' && $has_data) {

    // Forbid any update that removes allowed values with actual data.
    $lost_keys = array_diff(array_keys($prior_field['settings']['allowed_values']), array_keys($field['settings']['allowed_values']));
    if (_options_values_in_use($field, $lost_keys)) {
      throw new FieldUpdateForbiddenException(t('A list field (@field_name) with existing data cannot have its keys changed.', array(
        '@field_name' => $field['field_name'],
      )));
    }
  }
}

/**
 * Checks if a list of values are being used in actual field values.
 */
function _options_values_in_use($field, $values) {
  if ($values) {
    $field = field_info_field_by_id($field['id']);
    $factory = drupal_container()
      ->get('entity.query');
    foreach ($field['bundles'] as $entity_type => $bundle) {
      $result = $factory
        ->get($entity_type)
        ->condition($field['field_name'] . '.value', $values)
        ->count()
        ->accessCheck(FALSE)
        ->range(0, 1)
        ->execute();
      if ($result) {
        return TRUE;
      }
    }
  }
  return FALSE;
}

/**
 * Implements hook_field_validate().
 *
 * Possible error codes:
 * - 'list_illegal_value': The value is not part of the list of allowed values.
 */
function options_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors) {
  $allowed_values = options_allowed_values($field, $instance, $entity_type, $entity);
  foreach ($items as $delta => $item) {
    if (!empty($item['value'])) {
      if (!empty($allowed_values) && !isset($allowed_values[$item['value']])) {
        $errors[$field['field_name']][$langcode][$delta][] = array(
          'error' => 'list_illegal_value',
          'message' => t('%name: illegal value.', array(
            '%name' => $instance['label'],
          )),
        );
      }
    }
  }
}

/**
 * Implements hook_field_is_empty().
 */
function options_field_is_empty($item, $field) {
  if (empty($item['value']) && (string) $item['value'] !== '0') {
    return TRUE;
  }
  return FALSE;
}

/**
 * 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.
 */
function options_field_widget_info() {
  return array(
    'options_select' => array(
      'label' => t('Select list'),
      'field types' => array(
        'list_integer',
        'list_float',
        'list_text',
      ),
      'behaviors' => array(
        'multiple values' => FIELD_BEHAVIOR_CUSTOM,
      ),
    ),
    'options_buttons' => array(
      'label' => t('Check boxes/radio buttons'),
      'field types' => array(
        'list_integer',
        'list_float',
        'list_text',
        'list_boolean',
      ),
      'behaviors' => array(
        'multiple values' => FIELD_BEHAVIOR_CUSTOM,
      ),
    ),
    'options_onoff' => array(
      'label' => t('Single on/off checkbox'),
      'field types' => array(
        'list_boolean',
      ),
      '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 elements.
 */
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.
 *
 * @param $type
 *   The type of widget: select, buttons, or onoff.
 * @param $multiple
 *   TRUE if the field allows multiple values; FALSE otherwise.
 * @param $required
 *   TRUE if a value is required for the field; FALSE otherwise.
 * @param $has_value
 *   TRUE if a value is selected.
 *
 * @return
 *   An array of properties for the widget.
 */
function _options_properties($type, $multiple, $required, $has_value) {
  $base = array(
    'filter_xss' => FALSE,
    'strip_tags' => FALSE,
    'empty_option' => FALSE,
    'optgroups' => FALSE,
  );
  $properties = array();
  switch ($type) {
    case 'select':
      $properties = array(
        // Select boxes do not support any HTML tag.
        'strip_tags' => 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 recursively to support optgroups.
 *
 * @param $options
 *   The option array.
 * @param $properties
 *   An array containing the properties of the widget.
 */
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 {
      if ($properties['strip_tags']) {
        $options[$value] = strip_tags($label);
      }
      if ($properties['filter_xss']) {
        $options[$value] = field_filter_xss($label);
      }
    }
  }
}

/**
 * Transforms stored field values into the format the widgets need.
 *
 * @param $items
 *   An array of stored field values.
 * @param $options
 *   The options array.
 * @param $column
 *   The field storage column of the field.
 * @param $properties
 *   An array containing the properties of the widget.
 *
 * @return
 *   An array of values in the format used by widgets.
 */
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.
 *
 * @param $element
 *   The form element.
 *
 * @return
 *   An array of field values in 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_options_list().
 */
function options_options_list($field, $instance, $entity_type, $entity) {
  return options_allowed_values($field, $instance, $entity_type, $entity);
}

/**
 * Returns HTML for the label for the empty value for non-required options.
 *
 * The default theme will display N/A for a radio list and '- None -' for a
 * select.
 *
 * @param $variables
 *   An associative array containing:
 *   - instance: An array representing the widget requesting the options.
 *
 * @ingroup themeable
 */
function theme_options_none($variables) {
  $instance = $variables['instance'];
  $option = $variables['option'];
  $output = '';
  switch ($instance['widget']['type']) {
    case 'options_buttons':
      $output = t('N/A');
      break;
    case 'options_select':
      $output = $option == 'option_none' ? t('- None -') : t('- Select a value -');
      break;
  }
  return $output;
}

/**
 * Implements hook_field_formatter_info().
 */
function options_field_formatter_info() {
  return array(
    'list_default' => array(
      'label' => t('Default'),
      'field types' => array(
        'list_integer',
        'list_float',
        'list_text',
        'list_boolean',
      ),
    ),
    'list_key' => array(
      'label' => t('Key'),
      'field types' => array(
        'list_integer',
        'list_float',
        'list_text',
        'list_boolean',
      ),
    ),
  );
}

/**
 * Implements hook_field_formatter_view().
 */
function options_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
  $element = array();
  switch ($display['type']) {
    case 'list_default':
      $allowed_values = options_allowed_values($field, $instance, $entity_type, $entity);
      foreach ($items as $delta => $item) {
        if (isset($allowed_values[$item['value']])) {
          $output = field_filter_xss($allowed_values[$item['value']]);
        }
        else {

          // If no match was found in allowed values, fall back to the key.
          $output = field_filter_xss($item['value']);
        }
        $element[$delta] = array(
          '#markup' => $output,
        );
      }
      break;
    case 'list_key':
      foreach ($items as $delta => $item) {
        $element[$delta] = array(
          '#markup' => field_filter_xss($item['value']),
        );
      }
      break;
  }
  return $element;
}