root / drupal7 / modules / field / modules / options / options.api.php @ b0dc3a2e
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 |
} |