annotate core/modules/field/field.api.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@0 1 <?php
Chris@0 2
Chris@0 3 /**
Chris@0 4 * @file
Chris@0 5 * Field API documentation.
Chris@0 6 */
Chris@0 7
Chris@0 8 /**
Chris@0 9 * @addtogroup hooks
Chris@0 10 * @{
Chris@0 11 */
Chris@0 12
Chris@0 13 /**
Chris@0 14 * @defgroup field_types Field Types API
Chris@0 15 * @{
Chris@0 16 * Defines field, widget, display formatter, and storage types.
Chris@0 17 *
Chris@0 18 * In the Field API, each field has a type, which determines what kind of data
Chris@0 19 * (integer, string, date, etc.) the field can hold, which settings it provides,
Chris@0 20 * and so on. The data type(s) accepted by a field are defined in
Chris@0 21 * hook_field_schema().
Chris@0 22 *
Chris@0 23 * Field types are plugins annotated with class
Chris@0 24 * \Drupal\Core\Field\Annotation\FieldType, and implement plugin interface
Chris@0 25 * \Drupal\Core\Field\FieldItemInterface. Field Type plugins are managed by the
Chris@0 26 * \Drupal\Core\Field\FieldTypePluginManager class. Field type classes usually
Chris@0 27 * extend base class \Drupal\Core\Field\FieldItemBase. Field-type plugins need
Chris@0 28 * to be in the namespace \Drupal\{your_module}\Plugin\Field\FieldType. See the
Chris@0 29 * @link plugin_api Plugin API topic @endlink for more information on how to
Chris@0 30 * define plugins.
Chris@0 31 *
Chris@0 32 * The Field Types API also defines two kinds of pluggable handlers: widgets
Chris@0 33 * and formatters. @link field_widget Widgets @endlink specify how the field
Chris@0 34 * appears in edit forms, while @link field_formatter formatters @endlink
Chris@0 35 * specify how the field appears in displayed entities.
Chris@0 36 *
Chris@0 37 * See @link field Field API @endlink for information about the other parts of
Chris@0 38 * the Field API.
Chris@0 39 *
Chris@0 40 * @see field
Chris@0 41 * @see field_widget
Chris@0 42 * @see field_formatter
Chris@0 43 * @see plugin_api
Chris@0 44 */
Chris@0 45
Chris@0 46 /**
Chris@0 47 * Perform alterations on Field API field types.
Chris@0 48 *
Chris@0 49 * @param $info
Chris@0 50 * Array of information on field types as collected by the "field type" plugin
Chris@0 51 * manager.
Chris@0 52 */
Chris@0 53 function hook_field_info_alter(&$info) {
Chris@0 54 // Change the default widget for fields of type 'foo'.
Chris@0 55 if (isset($info['foo'])) {
Chris@0 56 $info['foo']['default widget'] = 'mymodule_widget';
Chris@0 57 }
Chris@0 58 }
Chris@0 59
Chris@0 60 /**
Chris@14 61 * Perform alterations on preconfigured field options.
Chris@14 62 *
Chris@14 63 * @param array $options
Chris@14 64 * Array of options as returned from
Chris@14 65 * \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface::getPreconfiguredOptions().
Chris@14 66 * @param string $field_type
Chris@14 67 * The field type plugin ID.
Chris@14 68 *
Chris@14 69 * @see \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface::getPreconfiguredOptions()
Chris@14 70 */
Chris@14 71 function hook_field_ui_preconfigured_options_alter(array &$options, $field_type) {
Chris@14 72 // If the field is not an "entity_reference"-based field, bail out.
Chris@14 73 /** @var \Drupal\Core\Field\FieldTypePluginManager $field_type_manager */
Chris@14 74 $field_type_manager = \Drupal::service('plugin.manager.field.field_type');
Chris@14 75 $class = $field_type_manager->getPluginClass($field_type);
Chris@14 76 if (!is_a($class, 'Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem', TRUE)) {
Chris@14 77 return;
Chris@14 78 }
Chris@14 79
Chris@14 80 // Set the default formatter for media in entity reference fields to be the
Chris@14 81 // "Rendered entity" formatter.
Chris@14 82 if (!empty($options['media'])) {
Chris@14 83 $options['media']['entity_view_display']['type'] = 'entity_reference_entity_view';
Chris@14 84 }
Chris@14 85 }
Chris@14 86
Chris@14 87 /**
Chris@0 88 * Forbid a field storage update from occurring.
Chris@0 89 *
Chris@0 90 * Any module may forbid any update for any reason. For example, the
Chris@0 91 * field's storage module might forbid an update if it would change
Chris@0 92 * the storage schema while data for the field exists. A field type
Chris@0 93 * module might forbid an update if it would change existing data's
Chris@0 94 * semantics, or if there are external dependencies on field settings
Chris@0 95 * that cannot be updated.
Chris@0 96 *
Chris@0 97 * To forbid the update from occurring, throw a
Chris@0 98 * \Drupal\Core\Entity\Exception\FieldStorageDefinitionUpdateForbiddenException.
Chris@0 99 *
Chris@0 100 * @param \Drupal\field\FieldStorageConfigInterface $field_storage
Chris@0 101 * The field storage as it will be post-update.
Chris@0 102 * @param \Drupal\field\FieldStorageConfigInterface $prior_field_storage
Chris@0 103 * The field storage as it is pre-update.
Chris@0 104 *
Chris@0 105 * @see entity_crud
Chris@0 106 */
Chris@0 107 function hook_field_storage_config_update_forbid(\Drupal\field\FieldStorageConfigInterface $field_storage, \Drupal\field\FieldStorageConfigInterface $prior_field_storage) {
Chris@0 108 if ($field_storage->module == 'options' && $field_storage->hasData()) {
Chris@0 109 // Forbid any update that removes allowed values with actual data.
Chris@0 110 $allowed_values = $field_storage->getSetting('allowed_values');
Chris@0 111 $prior_allowed_values = $prior_field_storage->getSetting('allowed_values');
Chris@0 112 $lost_keys = array_keys(array_diff_key($prior_allowed_values, $allowed_values));
Chris@0 113 if (_options_values_in_use($field_storage->getTargetEntityTypeId(), $field_storage->getName(), $lost_keys)) {
Chris@0 114 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 115 }
Chris@0 116 }
Chris@0 117 }
Chris@0 118
Chris@0 119 /**
Chris@0 120 * @} End of "defgroup field_types".
Chris@0 121 */
Chris@0 122
Chris@0 123 /**
Chris@0 124 * @defgroup field_widget Field Widget API
Chris@0 125 * @{
Chris@0 126 * Define Field API widget types.
Chris@0 127 *
Chris@0 128 * Field API widgets specify how fields are displayed in edit forms. Fields of a
Chris@0 129 * given @link field_types field type @endlink may be edited using more than one
Chris@0 130 * widget. In this case, the Field UI module allows the site builder to choose
Chris@0 131 * which widget to use.
Chris@0 132 *
Chris@0 133 * Widgets are Plugins managed by the
Chris@0 134 * \Drupal\Core\Field\WidgetPluginManager class. A widget is a plugin annotated
Chris@0 135 * with class \Drupal\Core\Field\Annotation\FieldWidget that implements
Chris@0 136 * \Drupal\Core\Field\WidgetInterface (in most cases, by
Chris@0 137 * subclassing \Drupal\Core\Field\WidgetBase). Widget plugins need to be in the
Chris@0 138 * namespace \Drupal\{your_module}\Plugin\Field\FieldWidget.
Chris@0 139 *
Chris@0 140 * Widgets are @link form_api Form API @endlink elements with additional
Chris@0 141 * processing capabilities. The methods of the WidgetInterface object are
Chris@0 142 * typically called by respective methods in the
Chris@0 143 * \Drupal\Core\Entity\Entity\EntityFormDisplay class.
Chris@0 144 *
Chris@0 145 * @see field
Chris@0 146 * @see field_types
Chris@0 147 * @see field_formatter
Chris@0 148 * @see plugin_api
Chris@0 149 */
Chris@0 150
Chris@0 151 /**
Chris@0 152 * Perform alterations on Field API widget types.
Chris@0 153 *
Chris@0 154 * @param array $info
Chris@0 155 * An array of information on existing widget types, as collected by the
Chris@0 156 * annotation discovery mechanism.
Chris@0 157 */
Chris@0 158 function hook_field_widget_info_alter(array &$info) {
Chris@0 159 // Let a new field type re-use an existing widget.
Chris@0 160 $info['options_select']['field_types'][] = 'my_field_type';
Chris@0 161 }
Chris@0 162
Chris@0 163 /**
Chris@0 164 * Alter forms for field widgets provided by other modules.
Chris@0 165 *
Chris@14 166 * This hook can only modify individual elements within a field widget and
Chris@14 167 * cannot alter the top level (parent element) for multi-value fields. In most
Chris@14 168 * cases, you should use hook_field_widget_multivalue_form_alter() instead and
Chris@14 169 * loop over the elements.
Chris@14 170 *
Chris@0 171 * @param $element
Chris@12 172 * The field widget form element as constructed by
Chris@12 173 * \Drupal\Core\Field\WidgetBaseInterface::form().
Chris@0 174 * @param $form_state
Chris@0 175 * The current state of the form.
Chris@0 176 * @param $context
Chris@0 177 * An associative array containing the following key-value pairs:
Chris@0 178 * - form: The form structure to which widgets are being attached. This may be
Chris@0 179 * a full form structure, or a sub-element of a larger form.
Chris@0 180 * - widget: The widget plugin instance.
Chris@0 181 * - items: The field values, as a
Chris@0 182 * \Drupal\Core\Field\FieldItemListInterface object.
Chris@0 183 * - delta: The order of this item in the array of subelements (0, 1, 2, etc).
Chris@0 184 * - default: A boolean indicating whether the form is being shown as a dummy
Chris@0 185 * form to set default values.
Chris@0 186 *
Chris@12 187 * @see \Drupal\Core\Field\WidgetBaseInterface::form()
Chris@0 188 * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
Chris@0 189 * @see hook_field_widget_WIDGET_TYPE_form_alter()
Chris@14 190 * @see hook_field_widget_multivalue_form_alter()
Chris@0 191 */
Chris@0 192 function hook_field_widget_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
Chris@0 193 // Add a css class to widget form elements for all fields of type mytype.
Chris@0 194 $field_definition = $context['items']->getFieldDefinition();
Chris@0 195 if ($field_definition->getType() == 'mytype') {
Chris@0 196 // Be sure not to overwrite existing attributes.
Chris@0 197 $element['#attributes']['class'][] = 'myclass';
Chris@0 198 }
Chris@0 199 }
Chris@0 200
Chris@0 201 /**
Chris@0 202 * Alter widget forms for a specific widget provided by another module.
Chris@0 203 *
Chris@0 204 * Modules can implement hook_field_widget_WIDGET_TYPE_form_alter() to modify a
Chris@0 205 * specific widget form, rather than using hook_field_widget_form_alter() and
Chris@0 206 * checking the widget type.
Chris@0 207 *
Chris@14 208 * This hook can only modify individual elements within a field widget and
Chris@14 209 * cannot alter the top level (parent element) for multi-value fields. In most
Chris@14 210 * cases, you should use hook_field_widget_multivalue_WIDGET_TYPE_form_alter()
Chris@14 211 * instead and loop over the elements.
Chris@14 212 *
Chris@0 213 * @param $element
Chris@12 214 * The field widget form element as constructed by
Chris@12 215 * \Drupal\Core\Field\WidgetBaseInterface::form().
Chris@0 216 * @param $form_state
Chris@0 217 * The current state of the form.
Chris@0 218 * @param $context
Chris@0 219 * An associative array. See hook_field_widget_form_alter() for the structure
Chris@0 220 * and content of the array.
Chris@0 221 *
Chris@12 222 * @see \Drupal\Core\Field\WidgetBaseInterface::form()
Chris@0 223 * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
Chris@0 224 * @see hook_field_widget_form_alter()
Chris@14 225 * @see hook_field_widget_multivalue_WIDGET_TYPE_form_alter()
Chris@0 226 */
Chris@0 227 function hook_field_widget_WIDGET_TYPE_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
Chris@0 228 // Code here will only act on widgets of type WIDGET_TYPE. For example,
Chris@0 229 // hook_field_widget_mymodule_autocomplete_form_alter() will only act on
Chris@0 230 // widgets of type 'mymodule_autocomplete'.
Chris@0 231 $element['#autocomplete_route_name'] = 'mymodule.autocomplete_route';
Chris@0 232 }
Chris@0 233
Chris@0 234 /**
Chris@14 235 * Alter forms for multi-value field widgets provided by other modules.
Chris@14 236 *
Chris@14 237 * To alter the individual elements within the widget, loop over
Chris@14 238 * \Drupal\Core\Render\Element::children($elements).
Chris@14 239 *
Chris@14 240 * @param array $elements
Chris@14 241 * The field widget form elements as constructed by
Chris@14 242 * \Drupal\Core\Field\WidgetBase::formMultipleElements().
Chris@14 243 * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@14 244 * The current state of the form.
Chris@14 245 * @param array $context
Chris@14 246 * An associative array containing the following key-value pairs:
Chris@14 247 * - form: The form structure to which widgets are being attached. This may be
Chris@14 248 * a full form structure, or a sub-element of a larger form.
Chris@14 249 * - widget: The widget plugin instance.
Chris@14 250 * - items: The field values, as a
Chris@14 251 * \Drupal\Core\Field\FieldItemListInterface object.
Chris@14 252 * - default: A boolean indicating whether the form is being shown as a dummy
Chris@14 253 * form to set default values.
Chris@14 254 *
Chris@14 255 * @see \Drupal\Core\Field\WidgetBaseInterface::form()
Chris@14 256 * @see \Drupal\Core\Field\WidgetBase::formMultipleElements()
Chris@14 257 * @see hook_field_widget_multivalue_WIDGET_TYPE_form_alter()
Chris@14 258 */
Chris@14 259 function hook_field_widget_multivalue_form_alter(array &$elements, \Drupal\Core\Form\FormStateInterface $form_state, array $context) {
Chris@14 260 // Add a css class to widget form elements for all fields of type mytype.
Chris@14 261 $field_definition = $context['items']->getFieldDefinition();
Chris@14 262 if ($field_definition->getType() == 'mytype') {
Chris@14 263 // Be sure not to overwrite existing attributes.
Chris@14 264 $elements['#attributes']['class'][] = 'myclass';
Chris@14 265 }
Chris@14 266 }
Chris@14 267
Chris@14 268 /**
Chris@14 269 * Alter multi-value widget forms for a widget provided by another module.
Chris@14 270 *
Chris@14 271 * Modules can implement hook_field_widget_multivalue_WIDGET_TYPE_form_alter() to
Chris@14 272 * modify a specific widget form, rather than using
Chris@14 273 * hook_field_widget_form_alter() and checking the widget type.
Chris@14 274 *
Chris@14 275 * To alter the individual elements within the widget, loop over
Chris@14 276 * \Drupal\Core\Render\Element::children($elements).
Chris@14 277 *
Chris@14 278 * @param array $elements
Chris@14 279 * The field widget form elements as constructed by
Chris@14 280 * \Drupal\Core\Field\WidgetBase::formMultipleElements().
Chris@14 281 * @param \Drupal\Core\Form\FormStateInterface $form_state
Chris@14 282 * The current state of the form.
Chris@14 283 * @param array $context
Chris@14 284 * An associative array. See hook_field_widget_multivalue_form_alter() for
Chris@14 285 * the structure and content of the array.
Chris@14 286 *
Chris@14 287 * @see \Drupal\Core\Field\WidgetBaseInterface::form()
Chris@14 288 * @see \Drupal\Core\Field\WidgetBase::formMultipleElements()
Chris@14 289 * @see hook_field_widget_multivalue_form_alter()
Chris@14 290 */
Chris@14 291 function hook_field_widget_multivalue_WIDGET_TYPE_form_alter(array &$elements, \Drupal\Core\Form\FormStateInterface $form_state, array $context) {
Chris@14 292 // Code here will only act on widgets of type WIDGET_TYPE. For example,
Chris@14 293 // hook_field_widget_multivalue_mymodule_autocomplete_form_alter() will only
Chris@14 294 // act on widgets of type 'mymodule_autocomplete'.
Chris@17 295 // Change the autocomplete route for each autocomplete element within the
Chris@14 296 // multivalue widget.
Chris@14 297 foreach (Element::children($elements) as $delta => $element) {
Chris@14 298 $elements[$delta]['#autocomplete_route_name'] = 'mymodule.autocomplete_route';
Chris@14 299 }
Chris@14 300 }
Chris@14 301
Chris@14 302 /**
Chris@0 303 * @} End of "defgroup field_widget".
Chris@0 304 */
Chris@0 305
Chris@0 306
Chris@0 307 /**
Chris@0 308 * @defgroup field_formatter Field Formatter API
Chris@0 309 * @{
Chris@0 310 * Define Field API formatter types.
Chris@0 311 *
Chris@0 312 * Field API formatters specify how fields are displayed when the entity to
Chris@0 313 * which the field is attached is displayed. Fields of a given
Chris@0 314 * @link field_types field type @endlink may be displayed using more than one
Chris@0 315 * formatter. In this case, the Field UI module allows the site builder to
Chris@0 316 * choose which formatter to use.
Chris@0 317 *
Chris@0 318 * Formatters are Plugins managed by the
Chris@0 319 * \Drupal\Core\Field\FormatterPluginManager class. A formatter is a plugin
Chris@0 320 * annotated with class \Drupal\Core\Field\Annotation\FieldFormatter that
Chris@0 321 * implements \Drupal\Core\Field\FormatterInterface (in most cases, by
Chris@0 322 * subclassing \Drupal\Core\Field\FormatterBase). Formatter plugins need to be
Chris@0 323 * in the namespace \Drupal\{your_module}\Plugin\Field\FieldFormatter.
Chris@0 324 *
Chris@0 325 * @see field
Chris@0 326 * @see field_types
Chris@0 327 * @see field_widget
Chris@0 328 * @see plugin_api
Chris@0 329 */
Chris@0 330
Chris@0 331 /**
Chris@0 332 * Perform alterations on Field API formatter types.
Chris@0 333 *
Chris@0 334 * @param array $info
Chris@0 335 * An array of information on existing formatter types, as collected by the
Chris@0 336 * annotation discovery mechanism.
Chris@0 337 */
Chris@0 338 function hook_field_formatter_info_alter(array &$info) {
Chris@0 339 // Let a new field type re-use an existing formatter.
Chris@0 340 $info['text_default']['field_types'][] = 'my_field_type';
Chris@0 341 }
Chris@0 342
Chris@0 343 /**
Chris@0 344 * @} End of "defgroup field_formatter".
Chris@0 345 */
Chris@0 346
Chris@0 347 /**
Chris@0 348 * Returns the maximum weight for the entity components handled by the module.
Chris@0 349 *
Chris@0 350 * Field API takes care of fields and 'extra_fields'. This hook is intended for
Chris@0 351 * third-party modules adding other entity components (e.g. field_group).
Chris@0 352 *
Chris@0 353 * @param string $entity_type
Chris@0 354 * The type of entity; e.g. 'node' or 'user'.
Chris@0 355 * @param string $bundle
Chris@0 356 * The bundle name.
Chris@0 357 * @param string $context
Chris@0 358 * The context for which the maximum weight is requested. Either 'form' or
Chris@0 359 * 'display'.
Chris@0 360 * @param string $context_mode
Chris@0 361 * The view or form mode name.
Chris@0 362 *
Chris@0 363 * @return int
Chris@0 364 * The maximum weight of the entity's components, or NULL if no components
Chris@0 365 * were found.
Chris@0 366 *
Chris@0 367 * @ingroup field_info
Chris@0 368 */
Chris@0 369 function hook_field_info_max_weight($entity_type, $bundle, $context, $context_mode) {
Chris@0 370 $weights = [];
Chris@0 371
Chris@0 372 foreach (my_module_entity_additions($entity_type, $bundle, $context, $context_mode) as $addition) {
Chris@0 373 $weights[] = $addition['weight'];
Chris@0 374 }
Chris@0 375
Chris@0 376 return $weights ? max($weights) : NULL;
Chris@0 377 }
Chris@0 378
Chris@0 379 /**
Chris@0 380 * @addtogroup field_purge
Chris@0 381 * @{
Chris@0 382 */
Chris@0 383
Chris@0 384 /**
Chris@0 385 * Acts when a field storage definition is being purged.
Chris@0 386 *
Chris@0 387 * In field_purge_field_storage(), after the storage definition has been removed
Chris@0 388 * from the system, the entity storage has purged stored field data, and the
Chris@0 389 * field definitions cache has been cleared, this hook is invoked on all modules
Chris@0 390 * to allow them to respond to the field storage being purged.
Chris@0 391 *
Chris@0 392 * @param $field_storage \Drupal\field\Entity\FieldStorageConfig
Chris@0 393 * The field storage being purged.
Chris@0 394 */
Chris@0 395 function hook_field_purge_field_storage(\Drupal\field\Entity\FieldStorageConfig $field_storage) {
Chris@18 396 \Drupal::database()->delete('my_module_field_storage_info')
Chris@0 397 ->condition('uuid', $field_storage->uuid())
Chris@0 398 ->execute();
Chris@0 399 }
Chris@0 400
Chris@0 401 /**
Chris@0 402 * Acts when a field is being purged.
Chris@0 403 *
Chris@0 404 * In field_purge_field(), after the field definition has been removed
Chris@0 405 * from the system, the entity storage has purged stored field data, and the
Chris@0 406 * field info cache has been cleared, this hook is invoked on all modules to
Chris@0 407 * allow them to respond to the field being purged.
Chris@0 408 *
Chris@0 409 * @param $field
Chris@0 410 * The field being purged.
Chris@0 411 */
Chris@0 412 function hook_field_purge_field(\Drupal\field\Entity\FieldConfig $field) {
Chris@18 413 \Drupal::database()->delete('my_module_field_info')
Chris@0 414 ->condition('id', $field->id())
Chris@0 415 ->execute();
Chris@0 416 }
Chris@0 417
Chris@0 418 /**
Chris@0 419 * @} End of "addtogroup field_purge".
Chris@0 420 */
Chris@0 421
Chris@0 422 /**
Chris@0 423 * @} End of "addtogroup hooks".
Chris@0 424 */