function hook_options_list

You are here

7 options.api.php hook_options_list($field, $instance, $entity_type, $entity)

Returns the list of options to be displayed for a field.

Field types willing to enable one or several of the widgets defined in options.module (select, radios/checkboxes, on/off checkbox) need to implement this hook to specify the list of options to display in the widgets.

Parameters

$field: The field definition.

$instance: (optional) The instance definition. The hook might be called without an $instance parameter in contexts where no specific instance can be targeted. It is recommended to only use instance level properties to filter out values from a list defined by field level properties.

$entity_type: The entity type the field is attached to.

$entity: The entity object the field is attached to, or NULL if no entity exists (e.g. in field settings page).

Return value

The array of options for the field. Array keys are the values to be stored, and should be of the data type (string, number...) expected by the first 'column' for the field type. Array values are the labels to display within the widgets. The labels should NOT be sanitized, options.module takes care of sanitation according to the needs of each widget. The HTML tags defined in _field_filter_xss_allowed_tags() are allowed, other tags will be filtered.

2 functions implement hook_options_list()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

list_options_list in modules/field/modules/list/list.module
Implements hook_options_list().
taxonomy_options_list in modules/taxonomy/taxonomy.module
Implements hook_options_list().
1 invocation of hook_options_list()
_options_get_options in modules/field/modules/options/options.module
Collects the options for a field.

File

modules/field/modules/options/options.api.php, line 38
Hooks provided by the Options module.

Code

function hook_options_list($field, $instance, $entity_type, $entity) {
  // Sample structure.
  $options = array(
    0 => t('Zero'),
    1 => t('One'),
    2 => t('Two'),
    3 => t('Three'),
  );

  // Sample structure with groups. Only one level of nesting is allowed. This
  // is only supported by the 'options_select' widget. Other widgets will
  // flatten the array.
  $options = array(
    t('First group') => array(
      0 => t('Zero'),
    ),
    t('Second group') => array(
      1 => t('One'),
      2 => t('Two'),
    ),
    3 => t('Three'),
  );

  // In actual implementations, the array of options will most probably depend
  // on properties of the field. Example from taxonomy.module:
  $options = array();
  foreach ($field['settings']['allowed_values'] as $tree) {
    $terms = taxonomy_get_tree($tree['vid'], $tree['parent']);
    if ($terms) {
      foreach ($terms as $term) {
        $options[$term->tid] = str_repeat('-', $term->depth) . $term->name;
      }
    }
  }

  return $options;
}

Comments

Building a custom field that generates an option list?
You'll need this function.

See: http://api.drupal.org/api/drupal/modules--field--field.api.php/function/...

Please note that for SELECT elements the labels will be passed through check_plain() by drupal (in form_select_options()) so be sure not to encode them yourself.