5 * Field API documentation.
14 * @defgroup field_types Field Types API
16 * Defines field, widget, display formatter, and storage types.
18 * In the Field API, each field has a type, which determines what kind of data
19 * (integer, string, date, etc.) the field can hold, which settings it provides,
20 * and so on. The data type(s) accepted by a field are defined in
21 * hook_field_schema().
23 * Field types are plugins annotated with class
24 * \Drupal\Core\Field\Annotation\FieldType, and implement plugin interface
25 * \Drupal\Core\Field\FieldItemInterface. Field Type plugins are managed by the
26 * \Drupal\Core\Field\FieldTypePluginManager class. Field type classes usually
27 * extend base class \Drupal\Core\Field\FieldItemBase. Field-type plugins need
28 * to be in the namespace \Drupal\{your_module}\Plugin\Field\FieldType. See the
29 * @link plugin_api Plugin API topic @endlink for more information on how to
32 * The Field Types API also defines two kinds of pluggable handlers: widgets
33 * and formatters. @link field_widget Widgets @endlink specify how the field
34 * appears in edit forms, while @link field_formatter formatters @endlink
35 * specify how the field appears in displayed entities.
37 * See @link field Field API @endlink for information about the other parts of
42 * @see field_formatter
48 * Perform alterations on Field API field types.
51 * Array of information on field types as collected by the "field type" plugin
54 function hook_field_info_alter(&$info) {
55 // Change the default widget for fields of type 'foo'.
56 if (isset($info['foo'])) {
57 $info['foo']['default widget'] = 'mymodule_widget';
62 * Forbid a field storage update from occurring.
64 * Any module may forbid any update for any reason. For example, the
65 * field's storage module might forbid an update if it would change
66 * the storage schema while data for the field exists. A field type
67 * module might forbid an update if it would change existing data's
68 * semantics, or if there are external dependencies on field settings
69 * that cannot be updated.
71 * To forbid the update from occurring, throw a
72 * \Drupal\Core\Entity\Exception\FieldStorageDefinitionUpdateForbiddenException.
74 * @param \Drupal\field\FieldStorageConfigInterface $field_storage
75 * The field storage as it will be post-update.
76 * @param \Drupal\field\FieldStorageConfigInterface $prior_field_storage
77 * The field storage as it is pre-update.
81 function hook_field_storage_config_update_forbid(\Drupal\field\FieldStorageConfigInterface $field_storage, \Drupal\field\FieldStorageConfigInterface $prior_field_storage) {
82 if ($field_storage->module == 'options' && $field_storage->hasData()) {
83 // Forbid any update that removes allowed values with actual data.
84 $allowed_values = $field_storage->getSetting('allowed_values');
85 $prior_allowed_values = $prior_field_storage->getSetting('allowed_values');
86 $lost_keys = array_keys(array_diff_key($prior_allowed_values, $allowed_values));
87 if (_options_values_in_use($field_storage->getTargetEntityTypeId(), $field_storage->getName(), $lost_keys)) {
88 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()]));
94 * @} End of "defgroup field_types".
98 * @defgroup field_widget Field Widget API
100 * Define Field API widget types.
102 * Field API widgets specify how fields are displayed in edit forms. Fields of a
103 * given @link field_types field type @endlink may be edited using more than one
104 * widget. In this case, the Field UI module allows the site builder to choose
105 * which widget to use.
107 * Widgets are Plugins managed by the
108 * \Drupal\Core\Field\WidgetPluginManager class. A widget is a plugin annotated
109 * with class \Drupal\Core\Field\Annotation\FieldWidget that implements
110 * \Drupal\Core\Field\WidgetInterface (in most cases, by
111 * subclassing \Drupal\Core\Field\WidgetBase). Widget plugins need to be in the
112 * namespace \Drupal\{your_module}\Plugin\Field\FieldWidget.
114 * Widgets are @link form_api Form API @endlink elements with additional
115 * processing capabilities. The methods of the WidgetInterface object are
116 * typically called by respective methods in the
117 * \Drupal\Core\Entity\Entity\EntityFormDisplay class.
121 * @see field_formatter
126 * Perform alterations on Field API widget types.
129 * An array of information on existing widget types, as collected by the
130 * annotation discovery mechanism.
132 function hook_field_widget_info_alter(array &$info) {
133 // Let a new field type re-use an existing widget.
134 $info['options_select']['field_types'][] = 'my_field_type';
138 * Alter forms for field widgets provided by other modules.
141 * The field widget form element as constructed by
142 * \Drupal\Core\Field\WidgetBaseInterface::form().
144 * The current state of the form.
146 * An associative array containing the following key-value pairs:
147 * - form: The form structure to which widgets are being attached. This may be
148 * a full form structure, or a sub-element of a larger form.
149 * - widget: The widget plugin instance.
150 * - items: The field values, as a
151 * \Drupal\Core\Field\FieldItemListInterface object.
152 * - delta: The order of this item in the array of subelements (0, 1, 2, etc).
153 * - default: A boolean indicating whether the form is being shown as a dummy
154 * form to set default values.
156 * @see \Drupal\Core\Field\WidgetBaseInterface::form()
157 * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
158 * @see hook_field_widget_WIDGET_TYPE_form_alter()
160 function hook_field_widget_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
161 // Add a css class to widget form elements for all fields of type mytype.
162 $field_definition = $context['items']->getFieldDefinition();
163 if ($field_definition->getType() == 'mytype') {
164 // Be sure not to overwrite existing attributes.
165 $element['#attributes']['class'][] = 'myclass';
170 * Alter widget forms for a specific widget provided by another module.
172 * Modules can implement hook_field_widget_WIDGET_TYPE_form_alter() to modify a
173 * specific widget form, rather than using hook_field_widget_form_alter() and
174 * checking the widget type.
177 * The field widget form element as constructed by
178 * \Drupal\Core\Field\WidgetBaseInterface::form().
180 * The current state of the form.
182 * An associative array. See hook_field_widget_form_alter() for the structure
183 * and content of the array.
185 * @see \Drupal\Core\Field\WidgetBaseInterface::form()
186 * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
187 * @see hook_field_widget_form_alter()
189 function hook_field_widget_WIDGET_TYPE_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
190 // Code here will only act on widgets of type WIDGET_TYPE. For example,
191 // hook_field_widget_mymodule_autocomplete_form_alter() will only act on
192 // widgets of type 'mymodule_autocomplete'.
193 $element['#autocomplete_route_name'] = 'mymodule.autocomplete_route';
197 * @} End of "defgroup field_widget".
202 * @defgroup field_formatter Field Formatter API
204 * Define Field API formatter types.
206 * Field API formatters specify how fields are displayed when the entity to
207 * which the field is attached is displayed. Fields of a given
208 * @link field_types field type @endlink may be displayed using more than one
209 * formatter. In this case, the Field UI module allows the site builder to
210 * choose which formatter to use.
212 * Formatters are Plugins managed by the
213 * \Drupal\Core\Field\FormatterPluginManager class. A formatter is a plugin
214 * annotated with class \Drupal\Core\Field\Annotation\FieldFormatter that
215 * implements \Drupal\Core\Field\FormatterInterface (in most cases, by
216 * subclassing \Drupal\Core\Field\FormatterBase). Formatter plugins need to be
217 * in the namespace \Drupal\{your_module}\Plugin\Field\FieldFormatter.
226 * Perform alterations on Field API formatter types.
229 * An array of information on existing formatter types, as collected by the
230 * annotation discovery mechanism.
232 function hook_field_formatter_info_alter(array &$info) {
233 // Let a new field type re-use an existing formatter.
234 $info['text_default']['field_types'][] = 'my_field_type';
238 * @} End of "defgroup field_formatter".
242 * Returns the maximum weight for the entity components handled by the module.
244 * Field API takes care of fields and 'extra_fields'. This hook is intended for
245 * third-party modules adding other entity components (e.g. field_group).
247 * @param string $entity_type
248 * The type of entity; e.g. 'node' or 'user'.
249 * @param string $bundle
251 * @param string $context
252 * The context for which the maximum weight is requested. Either 'form' or
254 * @param string $context_mode
255 * The view or form mode name.
258 * The maximum weight of the entity's components, or NULL if no components
261 * @ingroup field_info
263 function hook_field_info_max_weight($entity_type, $bundle, $context, $context_mode) {
266 foreach (my_module_entity_additions($entity_type, $bundle, $context, $context_mode) as $addition) {
267 $weights[] = $addition['weight'];
270 return $weights ? max($weights) : NULL;
274 * @addtogroup field_purge
279 * Acts when a field storage definition is being purged.
281 * In field_purge_field_storage(), after the storage definition has been removed
282 * from the system, the entity storage has purged stored field data, and the
283 * field definitions cache has been cleared, this hook is invoked on all modules
284 * to allow them to respond to the field storage being purged.
286 * @param $field_storage \Drupal\field\Entity\FieldStorageConfig
287 * The field storage being purged.
289 function hook_field_purge_field_storage(\Drupal\field\Entity\FieldStorageConfig $field_storage) {
290 db_delete('my_module_field_storage_info')
291 ->condition('uuid', $field_storage->uuid())
296 * Acts when a field is being purged.
298 * In field_purge_field(), after the field definition has been removed
299 * from the system, the entity storage has purged stored field data, and the
300 * field info cache has been cleared, this hook is invoked on all modules to
301 * allow them to respond to the field being purged.
304 * The field being purged.
306 function hook_field_purge_field(\Drupal\field\Entity\FieldConfig $field) {
307 db_delete('my_module_field_info')
308 ->condition('id', $field->id())
313 * @} End of "addtogroup field_purge".
317 * @} End of "addtogroup hooks".