Same name and namespace in other branches
  1. 8.9.x core/modules/options/options.api.php \callback_allowed_values_function()
  2. 9 core/modules/options/options.api.php \callback_allowed_values_function()

Provide the allowed values for a 'list_*' field.

Callback for options_allowed_values().

'list_*' fields can specify a callback to define the set of their allowed values using the 'allowed_values_function' storage setting.

That function will be called:

  • either in the context of a specific entity, which is then provided as the $entity parameter,
  • or for the field generally without the context of any specific entity or entity bundle (typically, Views needing a list of values for an exposed filter), in which case the $entity parameter is NULL.

This lets the callback restrict the set of allowed values or adjust the labels depending on some conditions on the containing entity.

For consistency, the set of values returned when an $entity is provided should be a subset of the values returned when no $entity is provided.

Parameters

\Drupal\Core\Field\FieldStorageDefinitionInterface $definition: The field storage definition.

\Drupal\Core\Entity\FieldableEntityInterface|null $entity: (optional) The entity context if known, or NULL if the allowed values are being collected without the context of a specific entity.

bool &$cacheable: (optional) If an $entity is provided, the $cacheable parameter should be modified by reference and set to FALSE if the set of allowed values returned was specifically adjusted for that entity and cannot not be reused for other entities. Defaults to TRUE.

Return value

array 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. If $entity is NULL, you should return the list of all the possible allowed values in any context so that other code (e.g. Views filters) can support the allowed values for all possible entities and bundles.

See also

options_allowed_values()

options_test_allowed_values_callback()

options_test_dynamic_values_callback()

Related topics

File

core/modules/options/options.api.php, line 83
Hooks provided by the Options module.

Code

function callback_allowed_values_function(FieldStorageDefinitionInterface $definition, FieldableEntityInterface $entity = NULL, &$cacheable = TRUE) {
  if (isset($entity) && $entity
    ->bundle() == 'not_a_programmer') {
    $values = [
      1 => 'One',
      2 => 'Two',
    ];
  }
  else {
    $values = [
      'Group 1' => [
        0 => 'Zero',
        1 => 'One',
      ],
      'Group 2' => [
        2 => 'Two',
      ],
    ];
  }
  return $values;
}