field.api.php 10.9 KB
Newer Older
1 2 3
<?php

/**
4
 * @addtogroup hooks
5 6 7 8 9 10
 * @{
 */

/**
 * @defgroup field_types Field Types API
 * @{
11
 * Defines field, widget, display formatter, and storage types.
12
 *
13 14 15
 * In the Field API, each field has a type, which determines what kind of data
 * (integer, string, date, etc.) the field can hold, which settings it provides,
 * and so on. The data type(s) accepted by a field are defined in
16
 * hook_field_schema().
17
 *
18
 * Field types are plugins annotated with class
19
 * \Drupal\Core\Field\Annotation\FieldType, and implement plugin interface
20 21 22 23 24 25 26
 * \Drupal\Core\Field\FieldItemInterface. Field Type plugins are managed by the
 * \Drupal\Core\Field\FieldTypePluginManager class. Field type classes usually
 * extend base class \Drupal\Core\Field\FieldItemBase. Field-type plugins need
 * to be in the namespace \Drupal\{your_module}\Plugin\Field\FieldType. See the
 * @link plugin_api Plugin API topic @endlink for more information on how to
 * define plugins.
 *
27
 * The Field Types API also defines two kinds of pluggable handlers: widgets
28 29 30
 * and formatters. @link field_widget Widgets @endlink specify how the field
 * appears in edit forms, while @link field_formatter formatters @endlink
 * specify how the field appears in displayed entities.
31
 *
32 33
 * See @link field Field API @endlink for information about the other parts of
 * the Field API.
34 35 36 37 38
 *
 * @see field
 * @see field_widget
 * @see field_formatter
 * @see plugin_api
39 40 41
 */


42 43 44 45
/**
 * Perform alterations on Field API field types.
 *
 * @param $info
46 47
 *   Array of information on field types as collected by the "field type" plugin
 *   manager.
48 49 50 51 52 53 54 55
 */
function hook_field_info_alter(&$info) {
  // Change the default widget for fields of type 'foo'.
  if (isset($info['foo'])) {
    $info['foo']['default widget'] = 'mymodule_widget';
  }
}

56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76
/**
 * Forbid a field storage update from occurring.
 *
 * Any module may forbid any update for any reason. For example, the
 * field's storage module might forbid an update if it would change
 * the storage schema while data for the field exists. A field type
 * module might forbid an update if it would change existing data's
 * semantics, or if there are external dependencies on field settings
 * that cannot be updated.
 *
 * To forbid the update from occurring, throw a
 * \Drupal\Core\Entity\Exception\FieldStorageDefinitionUpdateForbiddenException.
 *
 * @param \Drupal\field\FieldStorageConfigInterface $field_storage
 *   The field storage as it will be post-update.
 * @param \Drupal\field\FieldStorageConfigInterface $prior_field_storage
 *   The field storage as it is pre-update.
 *
 * @see entity_crud
 */
function hook_field_storage_config_update_forbid(\Drupal\field\FieldStorageConfigInterface $field_storage, \Drupal\field\FieldStorageConfigInterface $prior_field_storage) {
77 78 79 80
  if ($field_storage->module == 'options' && $field_storage->hasData()) {
    // Forbid any update that removes allowed values with actual data.
    $allowed_values = $field_storage->getSetting('allowed_values');
    $prior_allowed_values = $prior_field_storage->getSetting('allowed_values');
81
    $lost_keys = array_keys(array_diff_key($prior_allowed_values,$allowed_values));
82
    if (_options_values_in_use($field_storage->getTargetEntityTypeId(), $field_storage->getName(), $lost_keys)) {
83
      throw new \Drupal\Core\Entity\Exception\FieldStorageDefinitionUpdateForbiddenException(t('A list field (@field_name) with existing data cannot have its keys changed.', array('@field_name' => $field_storage->getName())));
84 85 86 87
    }
  }
}

88
/**
89
 * @} End of "defgroup field_types".
90 91 92 93 94 95 96 97 98 99
 */

/**
 * @defgroup field_widget Field Widget API
 * @{
 * Define Field API widget types.
 *
 * Field API widgets specify how fields are displayed in edit forms. Fields of a
 * given @link field_types field type @endlink may be edited using more than one
 * widget. In this case, the Field UI module allows the site builder to choose
100 101 102
 * which widget to use.
 *
 * Widgets are Plugins managed by the
103
 * \Drupal\Core\Field\WidgetPluginManager class. A widget is a plugin annotated
104
 * with class \Drupal\Core\Field\Annotation\FieldWidget that implements
105 106 107
 * \Drupal\Core\Field\WidgetInterface (in most cases, by
 * subclassing \Drupal\Core\Field\WidgetBase). Widget plugins need to be in the
 * namespace \Drupal\{your_module}\Plugin\Field\FieldWidget.
108
 *
109
 * Widgets are @link forms_api_reference.html Form API @endlink
110
 * elements with additional processing capabilities. The methods of the
111
 * WidgetInterface object are typically called by respective methods in the
112
 * \Drupal\Core\Entity\Entity\EntityFormDisplay class.
113 114 115 116
 *
 * @see field
 * @see field_types
 * @see field_formatter
117
 * @see plugin_api
118 119
 */

120 121 122
/**
 * Perform alterations on Field API widget types.
 *
123
 * @param array $info
124
 *   An array of information on existing widget types, as collected by the
125
 *   annotation discovery mechanism.
126
 */
127
function hook_field_widget_info_alter(array &$info) {
128
  // Let a new field type re-use an existing widget.
129
  $info['options_select']['field_types'][] = 'my_field_type';
130 131
}

132 133 134 135 136 137
/**
 * Alter forms for field widgets provided by other modules.
 *
 * @param $element
 *   The field widget form element as constructed by hook_field_widget_form().
 * @param $form_state
138
 *   The current state of the form.
139
 * @param $context
140
 *   An associative array containing the following key-value pairs:
141 142
 *   - form: The form structure to which widgets are being attached. This may be
 *     a full form structure, or a sub-element of a larger form.
143
 *   - widget: The widget plugin instance.
144
 *   - items: The field values, as a
145
 *     \Drupal\Core\Field\FieldItemListInterface object.
146
 *   - delta: The order of this item in the array of subelements (0, 1, 2, etc).
147 148
 *   - default: A boolean indicating whether the form is being shown as a dummy
 *     form to set default values.
149
 *
150
 * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
151
 * @see hook_field_widget_WIDGET_TYPE_form_alter()
152
 */
153
function hook_field_widget_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
154
  // Add a css class to widget form elements for all fields of type mytype.
155
  $field_definition = $context['items']->getFieldDefinition();
156
  if ($field_definition->getType() == 'mytype') {
157 158 159 160 161 162 163 164 165 166 167 168 169 170 171
    // Be sure not to overwrite existing attributes.
    $element['#attributes']['class'][] = 'myclass';
  }
}

/**
 * Alter widget forms for a specific widget provided by another module.
 *
 * Modules can implement hook_field_widget_WIDGET_TYPE_form_alter() to modify a
 * specific widget form, rather than using hook_field_widget_form_alter() and
 * checking the widget type.
 *
 * @param $element
 *   The field widget form element as constructed by hook_field_widget_form().
 * @param $form_state
172
 *   The current state of the form.
173
 * @param $context
174 175
 *   An associative array. See hook_field_widget_form_alter() for the structure
 *   and content of the array.
176
 *
177
 * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
178 179
 * @see hook_field_widget_form_alter()
 */
180
function hook_field_widget_WIDGET_TYPE_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
181 182 183
  // Code here will only act on widgets of type WIDGET_TYPE.  For example,
  // hook_field_widget_mymodule_autocomplete_form_alter() will only act on
  // widgets of type 'mymodule_autocomplete'.
184
  $element['#autocomplete_route_name'] = 'mymodule.autocomplete_route';
185 186
}

187
/**
188
 * @} End of "defgroup field_widget".
189 190 191 192 193 194 195 196 197 198 199 200
 */


/**
 * @defgroup field_formatter Field Formatter API
 * @{
 * Define Field API formatter types.
 *
 * Field API formatters specify how fields are displayed when the entity to
 * which the field is attached is displayed. Fields of a given
 * @link field_types field type @endlink may be displayed using more than one
 * formatter. In this case, the Field UI module allows the site builder to
201 202 203
 * choose which formatter to use.
 *
 * Formatters are Plugins managed by the
204
 * \Drupal\Core\Field\FormatterPluginManager class. A formatter is a plugin
205
 * annotated with class \Drupal\Core\Field\Annotation\FieldFormatter that
206 207 208
 * implements \Drupal\Core\Field\FormatterInterface (in most cases, by
 * subclassing \Drupal\Core\Field\FormatterBase). Formatter plugins need to be
 * in the namespace \Drupal\{your_module}\Plugin\Field\FieldFormatter.
209 210 211 212
 *
 * @see field
 * @see field_types
 * @see field_widget
213
 * @see plugin_api
214 215
 */

216 217 218
/**
 * Perform alterations on Field API formatter types.
 *
219
 * @param array $info
220
 *   An array of information on existing formatter types, as collected by the
221
 *   annotation discovery mechanism.
222
 */
223
function hook_field_formatter_info_alter(array &$info) {
224
  // Let a new field type re-use an existing formatter.
225
  $info['text_default']['field_types'][] = 'my_field_type';
226 227
}

228
/**
229
 * @} End of "defgroup field_formatter".
230 231
 */

232 233 234 235 236 237
/**
 * Returns the maximum weight for the entity components handled by the module.
 *
 * Field API takes care of fields and 'extra_fields'. This hook is intended for
 * third-party modules adding other entity components (e.g. field_group).
 *
238
 * @param string $entity_type
239
 *   The type of entity; e.g. 'node' or 'user'.
240
 * @param string $bundle
241
 *   The bundle name.
242 243 244 245 246 247 248
 * @param string $context
 *   The context for which the maximum weight is requested. Either 'form' or
 *   'display'.
 * @param string $context_mode
 *   The view or form mode name.
 *
 * @return int
249 250
 *   The maximum weight of the entity's components, or NULL if no components
 *   were found.
251 252
 *
 * @ingroup field_info
253
 */
254
function hook_field_info_max_weight($entity_type, $bundle, $context, $context_mode) {
255 256
  $weights = array();

257
  foreach (my_module_entity_additions($entity_type, $bundle, $context, $context_mode) as $addition) {
258 259 260 261 262 263
    $weights[] = $addition['weight'];
  }

  return $weights ? max($weights) : NULL;
}

264
/**
265
 * @addtogroup field_purge
266 267 268
 * @{
 */

269
/**
270
 * Acts when a field storage definition is being purged.
271
 *
272 273 274 275
 * In field_purge_field_storage(), after the storage definition has been removed
 * from the system, the entity storage has purged stored field data, and the
 * field definitions cache has been cleared, this hook is invoked on all modules
 * to allow them to respond to the field storage being purged.
276
 *
277 278
 * @param $field_storage \Drupal\field\Entity\FieldStorageConfig
 *   The field storage being purged.
279
 */
280 281 282
function hook_field_purge_field_storage(\Drupal\field\Entity\FieldStorageConfig $field_storage) {
  db_delete('my_module_field_storage_info')
    ->condition('uuid', $field_storage->uuid())
283 284 285 286
    ->execute();
}

/**
287
 * Acts when a field is being purged.
288
 *
289
 * In field_purge_field(), after the field definition has been removed
290
 * from the system, the entity storage has purged stored field data, and the
291
 * field info cache has been cleared, this hook is invoked on all modules to
292
 * allow them to respond to the field being purged.
293
 *
294 295
 * @param $field
 *   The field being purged.
296
 */
297 298 299
function hook_field_purge_field(\Drupal\field\Entity\FieldConfig $field) {
  db_delete('my_module_field_info')
    ->condition('id', $field->id())
300 301 302
    ->execute();
}

303
/**
304
 * @} End of "addtogroup field_purge".
305 306
 */

307
/**
308
 * @} End of "addtogroup hooks".
309
 */