Chris@0: <?php
Chris@0: 
Chris@0: /**
Chris@0:  * @file
Chris@0:  * Field API documentation.
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * @addtogroup hooks
Chris@0:  * @{
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * @defgroup field_types Field Types API
Chris@0:  * @{
Chris@0:  * Defines field, widget, display formatter, and storage types.
Chris@0:  *
Chris@0:  * In the Field API, each field has a type, which determines what kind of data
Chris@0:  * (integer, string, date, etc.) the field can hold, which settings it provides,
Chris@0:  * and so on. The data type(s) accepted by a field are defined in
Chris@0:  * hook_field_schema().
Chris@0:  *
Chris@0:  * Field types are plugins annotated with class
Chris@0:  * \Drupal\Core\Field\Annotation\FieldType, and implement plugin interface
Chris@0:  * \Drupal\Core\Field\FieldItemInterface. Field Type plugins are managed by the
Chris@0:  * \Drupal\Core\Field\FieldTypePluginManager class. Field type classes usually
Chris@0:  * extend base class \Drupal\Core\Field\FieldItemBase. Field-type plugins need
Chris@0:  * to be in the namespace \Drupal\{your_module}\Plugin\Field\FieldType. See the
Chris@0:  * @link plugin_api Plugin API topic @endlink for more information on how to
Chris@0:  * define plugins.
Chris@0:  *
Chris@0:  * The Field Types API also defines two kinds of pluggable handlers: widgets
Chris@0:  * and formatters. @link field_widget Widgets @endlink specify how the field
Chris@0:  * appears in edit forms, while @link field_formatter formatters @endlink
Chris@0:  * specify how the field appears in displayed entities.
Chris@0:  *
Chris@0:  * See @link field Field API @endlink for information about the other parts of
Chris@0:  * the Field API.
Chris@0:  *
Chris@0:  * @see field
Chris@0:  * @see field_widget
Chris@0:  * @see field_formatter
Chris@0:  * @see plugin_api
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Perform alterations on Field API field types.
Chris@0:  *
Chris@0:  * @param $info
Chris@0:  *   Array of information on field types as collected by the "field type" plugin
Chris@0:  *   manager.
Chris@0:  */
Chris@0: function hook_field_info_alter(&$info) {
Chris@0:   // Change the default widget for fields of type 'foo'.
Chris@0:   if (isset($info['foo'])) {
Chris@0:     $info['foo']['default widget'] = 'mymodule_widget';
Chris@0:   }
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@14:  * Perform alterations on preconfigured field options.
Chris@14:  *
Chris@14:  * @param array $options
Chris@14:  *   Array of options as returned from
Chris@14:  *   \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface::getPreconfiguredOptions().
Chris@14:  * @param string $field_type
Chris@14:  *   The field type plugin ID.
Chris@14:  *
Chris@14:  * @see \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface::getPreconfiguredOptions()
Chris@14:  */
Chris@14: function hook_field_ui_preconfigured_options_alter(array &$options, $field_type) {
Chris@14:   // If the field is not an "entity_reference"-based field, bail out.
Chris@14:   /** @var \Drupal\Core\Field\FieldTypePluginManager $field_type_manager */
Chris@14:   $field_type_manager = \Drupal::service('plugin.manager.field.field_type');
Chris@14:   $class = $field_type_manager->getPluginClass($field_type);
Chris@14:   if (!is_a($class, 'Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem', TRUE)) {
Chris@14:     return;
Chris@14:   }
Chris@14: 
Chris@14:   // Set the default formatter for media in entity reference fields to be the
Chris@14:   // "Rendered entity" formatter.
Chris@14:   if (!empty($options['media'])) {
Chris@14:     $options['media']['entity_view_display']['type'] = 'entity_reference_entity_view';
Chris@14:   }
Chris@14: }
Chris@14: 
Chris@14: /**
Chris@0:  * Forbid a field storage update from occurring.
Chris@0:  *
Chris@0:  * Any module may forbid any update for any reason. For example, the
Chris@0:  * field's storage module might forbid an update if it would change
Chris@0:  * the storage schema while data for the field exists. A field type
Chris@0:  * module might forbid an update if it would change existing data's
Chris@0:  * semantics, or if there are external dependencies on field settings
Chris@0:  * that cannot be updated.
Chris@0:  *
Chris@0:  * To forbid the update from occurring, throw a
Chris@0:  * \Drupal\Core\Entity\Exception\FieldStorageDefinitionUpdateForbiddenException.
Chris@0:  *
Chris@0:  * @param \Drupal\field\FieldStorageConfigInterface $field_storage
Chris@0:  *   The field storage as it will be post-update.
Chris@0:  * @param \Drupal\field\FieldStorageConfigInterface $prior_field_storage
Chris@0:  *   The field storage as it is pre-update.
Chris@0:  *
Chris@0:  * @see entity_crud
Chris@0:  */
Chris@0: function hook_field_storage_config_update_forbid(\Drupal\field\FieldStorageConfigInterface $field_storage, \Drupal\field\FieldStorageConfigInterface $prior_field_storage) {
Chris@0:   if ($field_storage->module == 'options' && $field_storage->hasData()) {
Chris@0:     // Forbid any update that removes allowed values with actual data.
Chris@0:     $allowed_values = $field_storage->getSetting('allowed_values');
Chris@0:     $prior_allowed_values = $prior_field_storage->getSetting('allowed_values');
Chris@0:     $lost_keys = array_keys(array_diff_key($prior_allowed_values, $allowed_values));
Chris@0:     if (_options_values_in_use($field_storage->getTargetEntityTypeId(), $field_storage->getName(), $lost_keys)) {
Chris@0:       throw new \Drupal\Core\Entity\Exception\FieldStorageDefinitionUpdateForbiddenException(t('A list field (@field_name) with existing data cannot have its keys changed.', ['@field_name' => $field_storage->getName()]));
Chris@0:     }
Chris@0:   }
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * @} End of "defgroup field_types".
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * @defgroup field_widget Field Widget API
Chris@0:  * @{
Chris@0:  * Define Field API widget types.
Chris@0:  *
Chris@0:  * Field API widgets specify how fields are displayed in edit forms. Fields of a
Chris@0:  * given @link field_types field type @endlink may be edited using more than one
Chris@0:  * widget. In this case, the Field UI module allows the site builder to choose
Chris@0:  * which widget to use.
Chris@0:  *
Chris@0:  * Widgets are Plugins managed by the
Chris@0:  * \Drupal\Core\Field\WidgetPluginManager class. A widget is a plugin annotated
Chris@0:  * with class \Drupal\Core\Field\Annotation\FieldWidget that implements
Chris@0:  * \Drupal\Core\Field\WidgetInterface (in most cases, by
Chris@0:  * subclassing \Drupal\Core\Field\WidgetBase). Widget plugins need to be in the
Chris@0:  * namespace \Drupal\{your_module}\Plugin\Field\FieldWidget.
Chris@0:  *
Chris@0:  * Widgets are @link form_api Form API @endlink elements with additional
Chris@0:  * processing capabilities. The methods of the WidgetInterface object are
Chris@0:  * typically called by respective methods in the
Chris@0:  * \Drupal\Core\Entity\Entity\EntityFormDisplay class.
Chris@0:  *
Chris@0:  * @see field
Chris@0:  * @see field_types
Chris@0:  * @see field_formatter
Chris@0:  * @see plugin_api
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Perform alterations on Field API widget types.
Chris@0:  *
Chris@0:  * @param array $info
Chris@0:  *   An array of information on existing widget types, as collected by the
Chris@0:  *   annotation discovery mechanism.
Chris@0:  */
Chris@0: function hook_field_widget_info_alter(array &$info) {
Chris@0:   // Let a new field type re-use an existing widget.
Chris@0:   $info['options_select']['field_types'][] = 'my_field_type';
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * Alter forms for field widgets provided by other modules.
Chris@0:  *
Chris@14:  * This hook can only modify individual elements within a field widget and
Chris@14:  * cannot alter the top level (parent element) for multi-value fields. In most
Chris@14:  * cases, you should use hook_field_widget_multivalue_form_alter() instead and
Chris@14:  * loop over the elements.
Chris@14:  *
Chris@0:  * @param $element
Chris@12:  *   The field widget form element as constructed by
Chris@12:  *   \Drupal\Core\Field\WidgetBaseInterface::form().
Chris@0:  * @param $form_state
Chris@0:  *   The current state of the form.
Chris@0:  * @param $context
Chris@0:  *   An associative array containing the following key-value pairs:
Chris@0:  *   - form: The form structure to which widgets are being attached. This may be
Chris@0:  *     a full form structure, or a sub-element of a larger form.
Chris@0:  *   - widget: The widget plugin instance.
Chris@0:  *   - items: The field values, as a
Chris@0:  *     \Drupal\Core\Field\FieldItemListInterface object.
Chris@0:  *   - delta: The order of this item in the array of subelements (0, 1, 2, etc).
Chris@0:  *   - default: A boolean indicating whether the form is being shown as a dummy
Chris@0:  *     form to set default values.
Chris@0:  *
Chris@12:  * @see \Drupal\Core\Field\WidgetBaseInterface::form()
Chris@0:  * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
Chris@0:  * @see hook_field_widget_WIDGET_TYPE_form_alter()
Chris@14:  * @see hook_field_widget_multivalue_form_alter()
Chris@0:  */
Chris@0: function hook_field_widget_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
Chris@0:   // Add a css class to widget form elements for all fields of type mytype.
Chris@0:   $field_definition = $context['items']->getFieldDefinition();
Chris@0:   if ($field_definition->getType() == 'mytype') {
Chris@0:     // Be sure not to overwrite existing attributes.
Chris@0:     $element['#attributes']['class'][] = 'myclass';
Chris@0:   }
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * Alter widget forms for a specific widget provided by another module.
Chris@0:  *
Chris@0:  * Modules can implement hook_field_widget_WIDGET_TYPE_form_alter() to modify a
Chris@0:  * specific widget form, rather than using hook_field_widget_form_alter() and
Chris@0:  * checking the widget type.
Chris@0:  *
Chris@14:  * This hook can only modify individual elements within a field widget and
Chris@14:  * cannot alter the top level (parent element) for multi-value fields. In most
Chris@14:  * cases, you should use hook_field_widget_multivalue_WIDGET_TYPE_form_alter()
Chris@14:  * instead and loop over the elements.
Chris@14:  *
Chris@0:  * @param $element
Chris@12:  *   The field widget form element as constructed by
Chris@12:  *   \Drupal\Core\Field\WidgetBaseInterface::form().
Chris@0:  * @param $form_state
Chris@0:  *   The current state of the form.
Chris@0:  * @param $context
Chris@0:  *   An associative array. See hook_field_widget_form_alter() for the structure
Chris@0:  *   and content of the array.
Chris@0:  *
Chris@12:  * @see \Drupal\Core\Field\WidgetBaseInterface::form()
Chris@0:  * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
Chris@0:  * @see hook_field_widget_form_alter()
Chris@14:  * @see hook_field_widget_multivalue_WIDGET_TYPE_form_alter()
Chris@0:  */
Chris@0: function hook_field_widget_WIDGET_TYPE_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
Chris@0:   // Code here will only act on widgets of type WIDGET_TYPE.  For example,
Chris@0:   // hook_field_widget_mymodule_autocomplete_form_alter() will only act on
Chris@0:   // widgets of type 'mymodule_autocomplete'.
Chris@0:   $element['#autocomplete_route_name'] = 'mymodule.autocomplete_route';
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@14:  * Alter forms for multi-value field widgets provided by other modules.
Chris@14:  *
Chris@14:  * To alter the individual elements within the widget, loop over
Chris@14:  * \Drupal\Core\Render\Element::children($elements).
Chris@14:  *
Chris@14:  * @param array $elements
Chris@14:  *   The field widget form elements as constructed by
Chris@14:  *   \Drupal\Core\Field\WidgetBase::formMultipleElements().
Chris@14:  * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@14:  *   The current state of the form.
Chris@14:  * @param array $context
Chris@14:  *   An associative array containing the following key-value pairs:
Chris@14:  *   - form: The form structure to which widgets are being attached. This may be
Chris@14:  *     a full form structure, or a sub-element of a larger form.
Chris@14:  *   - widget: The widget plugin instance.
Chris@14:  *   - items: The field values, as a
Chris@14:  *     \Drupal\Core\Field\FieldItemListInterface object.
Chris@14:  *   - default: A boolean indicating whether the form is being shown as a dummy
Chris@14:  *     form to set default values.
Chris@14:  *
Chris@14:  * @see \Drupal\Core\Field\WidgetBaseInterface::form()
Chris@14:  * @see \Drupal\Core\Field\WidgetBase::formMultipleElements()
Chris@14:  * @see hook_field_widget_multivalue_WIDGET_TYPE_form_alter()
Chris@14:  */
Chris@14: function hook_field_widget_multivalue_form_alter(array &$elements, \Drupal\Core\Form\FormStateInterface $form_state, array $context) {
Chris@14:   // Add a css class to widget form elements for all fields of type mytype.
Chris@14:   $field_definition = $context['items']->getFieldDefinition();
Chris@14:   if ($field_definition->getType() == 'mytype') {
Chris@14:     // Be sure not to overwrite existing attributes.
Chris@14:     $elements['#attributes']['class'][] = 'myclass';
Chris@14:   }
Chris@14: }
Chris@14: 
Chris@14: /**
Chris@14:  * Alter multi-value widget forms for a widget provided by another module.
Chris@14:  *
Chris@14:  * Modules can implement hook_field_widget_multivalue_WIDGET_TYPE_form_alter() to
Chris@14:  * modify a specific widget form, rather than using
Chris@14:  * hook_field_widget_form_alter() and checking the widget type.
Chris@14:  *
Chris@14:  * To alter the individual elements within the widget, loop over
Chris@14:  * \Drupal\Core\Render\Element::children($elements).
Chris@14:  *
Chris@14:  * @param array $elements
Chris@14:  *   The field widget form elements as constructed by
Chris@14:  *   \Drupal\Core\Field\WidgetBase::formMultipleElements().
Chris@14:  * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@14:  *   The current state of the form.
Chris@14:  * @param array $context
Chris@14:  *   An associative array. See hook_field_widget_multivalue_form_alter() for
Chris@14:  *   the structure and content of the array.
Chris@14:  *
Chris@14:  * @see \Drupal\Core\Field\WidgetBaseInterface::form()
Chris@14:  * @see \Drupal\Core\Field\WidgetBase::formMultipleElements()
Chris@14:  * @see hook_field_widget_multivalue_form_alter()
Chris@14:  */
Chris@14: function hook_field_widget_multivalue_WIDGET_TYPE_form_alter(array &$elements, \Drupal\Core\Form\FormStateInterface $form_state, array $context) {
Chris@14:   // Code here will only act on widgets of type WIDGET_TYPE. For example,
Chris@14:   // hook_field_widget_multivalue_mymodule_autocomplete_form_alter() will only
Chris@14:   // act on widgets of type 'mymodule_autocomplete'.
Chris@17:   // Change the autocomplete route for each autocomplete element within the
Chris@14:   // multivalue widget.
Chris@14:   foreach (Element::children($elements) as $delta => $element) {
Chris@14:     $elements[$delta]['#autocomplete_route_name'] = 'mymodule.autocomplete_route';
Chris@14:   }
Chris@14: }
Chris@14: 
Chris@14: /**
Chris@0:  * @} End of "defgroup field_widget".
Chris@0:  */
Chris@0: 
Chris@0: 
Chris@0: /**
Chris@0:  * @defgroup field_formatter Field Formatter API
Chris@0:  * @{
Chris@0:  * Define Field API formatter types.
Chris@0:  *
Chris@0:  * Field API formatters specify how fields are displayed when the entity to
Chris@0:  * which the field is attached is displayed. Fields of a given
Chris@0:  * @link field_types field type @endlink may be displayed using more than one
Chris@0:  * formatter. In this case, the Field UI module allows the site builder to
Chris@0:  * choose which formatter to use.
Chris@0:  *
Chris@0:  * Formatters are Plugins managed by the
Chris@0:  * \Drupal\Core\Field\FormatterPluginManager class. A formatter is a plugin
Chris@0:  * annotated with class \Drupal\Core\Field\Annotation\FieldFormatter that
Chris@0:  * implements \Drupal\Core\Field\FormatterInterface (in most cases, by
Chris@0:  * subclassing \Drupal\Core\Field\FormatterBase). Formatter plugins need to be
Chris@0:  * in the namespace \Drupal\{your_module}\Plugin\Field\FieldFormatter.
Chris@0:  *
Chris@0:  * @see field
Chris@0:  * @see field_types
Chris@0:  * @see field_widget
Chris@0:  * @see plugin_api
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Perform alterations on Field API formatter types.
Chris@0:  *
Chris@0:  * @param array $info
Chris@0:  *   An array of information on existing formatter types, as collected by the
Chris@0:  *   annotation discovery mechanism.
Chris@0:  */
Chris@0: function hook_field_formatter_info_alter(array &$info) {
Chris@0:   // Let a new field type re-use an existing formatter.
Chris@0:   $info['text_default']['field_types'][] = 'my_field_type';
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * @} End of "defgroup field_formatter".
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Returns the maximum weight for the entity components handled by the module.
Chris@0:  *
Chris@0:  * Field API takes care of fields and 'extra_fields'. This hook is intended for
Chris@0:  * third-party modules adding other entity components (e.g. field_group).
Chris@0:  *
Chris@0:  * @param string $entity_type
Chris@0:  *   The type of entity; e.g. 'node' or 'user'.
Chris@0:  * @param string $bundle
Chris@0:  *   The bundle name.
Chris@0:  * @param string $context
Chris@0:  *   The context for which the maximum weight is requested. Either 'form' or
Chris@0:  *   'display'.
Chris@0:  * @param string $context_mode
Chris@0:  *   The view or form mode name.
Chris@0:  *
Chris@0:  * @return int
Chris@0:  *   The maximum weight of the entity's components, or NULL if no components
Chris@0:  *   were found.
Chris@0:  *
Chris@0:  * @ingroup field_info
Chris@0:  */
Chris@0: function hook_field_info_max_weight($entity_type, $bundle, $context, $context_mode) {
Chris@0:   $weights = [];
Chris@0: 
Chris@0:   foreach (my_module_entity_additions($entity_type, $bundle, $context, $context_mode) as $addition) {
Chris@0:     $weights[] = $addition['weight'];
Chris@0:   }
Chris@0: 
Chris@0:   return $weights ? max($weights) : NULL;
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * @addtogroup field_purge
Chris@0:  * @{
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * Acts when a field storage definition is being purged.
Chris@0:  *
Chris@0:  * In field_purge_field_storage(), after the storage definition has been removed
Chris@0:  * from the system, the entity storage has purged stored field data, and the
Chris@0:  * field definitions cache has been cleared, this hook is invoked on all modules
Chris@0:  * to allow them to respond to the field storage being purged.
Chris@0:  *
Chris@0:  * @param $field_storage \Drupal\field\Entity\FieldStorageConfig
Chris@0:  *   The field storage being purged.
Chris@0:  */
Chris@0: function hook_field_purge_field_storage(\Drupal\field\Entity\FieldStorageConfig $field_storage) {
Chris@18:   \Drupal::database()->delete('my_module_field_storage_info')
Chris@0:     ->condition('uuid', $field_storage->uuid())
Chris@0:     ->execute();
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * Acts when a field is being purged.
Chris@0:  *
Chris@0:  * In field_purge_field(), after the field definition has been removed
Chris@0:  * from the system, the entity storage has purged stored field data, and the
Chris@0:  * field info cache has been cleared, this hook is invoked on all modules to
Chris@0:  * allow them to respond to the field being purged.
Chris@0:  *
Chris@0:  * @param $field
Chris@0:  *   The field being purged.
Chris@0:  */
Chris@0: function hook_field_purge_field(\Drupal\field\Entity\FieldConfig $field) {
Chris@18:   \Drupal::database()->delete('my_module_field_info')
Chris@0:     ->condition('id', $field->id())
Chris@0:     ->execute();
Chris@0: }
Chris@0: 
Chris@0: /**
Chris@0:  * @} End of "addtogroup field_purge".
Chris@0:  */
Chris@0: 
Chris@0: /**
Chris@0:  * @} End of "addtogroup hooks".
Chris@0:  */