options.api.php 2.4 KB

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