Source: /modules/field/modules/options/options.api.php - 74 lines - 2445 bytes - Summary - Text - Print

   1  <?php
   2  
   3  /**
   4   * @file
   5   * Hooks provided by the Options module.
   6   */
   7  
   8  /**
   9   * Returns the list of options to be displayed for a field.
  10   *
  11   * Field types willing to enable one or several of the widgets defined in
  12   * options.module (select, radios/checkboxes, on/off checkbox) need to
  13   * implement this hook to specify the list of options to display in the
  14   * widgets.
  15   *
  16   * @param $field
  17   *   The field definition.
  18   * @param $instance
  19   *   (optional) The instance definition. The hook might be called without an
  20   *   $instance parameter in contexts where no specific instance can be targeted.
  21   *   It is recommended to only use instance level properties to filter out
  22   *   values from a list defined by field level properties.
  23   * @param $entity_type
  24   *   The entity type the field is attached to.
  25   * @param $entity
  26   *   The entity object the field is attached to, or NULL if no entity
  27   *   exists (e.g. in field settings page).
  28   *
  29   * @return
  30   *   The array of options for the field. Array keys are the values to be
  31   *   stored, and should be of the data type (string, number...) expected by
  32   *   the first 'column' for the field type. Array values are the labels to
  33   *   display within the widgets. The labels should NOT be sanitized,
  34   *   options.module takes care of sanitation according to the needs of each
  35   *   widget. The HTML tags defined in _field_filter_xss_allowed_tags() are
  36   *   allowed, other tags will be filtered.
  37   */
  38  function hook_options_list($field, $instance, $entity_type, $entity) {
  39    // Sample structure.
  40    $options = array(
  41      0 => t('Zero'),
  42      1 => t('One'),
  43      2 => t('Two'),
  44      3 => t('Three'),
  45    );
  46  
  47    // Sample structure with groups. Only one level of nesting is allowed. This
  48    // is only supported by the 'options_select' widget. Other widgets will
  49    // flatten the array.
  50    $options = array(
  51      t('First group') => array(
  52        0 => t('Zero'),
  53      ),
  54      t('Second group') => array(
  55        1 => t('One'),
  56        2 => t('Two'),
  57      ),
  58      3 => t('Three'),
  59    );
  60  
  61    // In actual implementations, the array of options will most probably depend
  62    // on properties of the field. Example from taxonomy.module:
  63    $options = array();
  64    foreach ($field['settings']['allowed_values'] as $tree) {
  65      $terms = taxonomy_get_tree($tree['vid'], $tree['parent']);
  66      if ($terms) {
  67        foreach ($terms as $term) {
  68          $options[$term->tid] = str_repeat('-', $term->depth) . $term->name;
  69        }
  70      }
  71    }
  72  
  73    return $options;
  74  }