field.api.php

  1. 7.x drupal/modules/field/field.api.php
  2. 8.x drupal/core/modules/field/field.api.php

Functions

Namesort descending Description
hook_field_formatter_info_alter Perform alterations on Field API formatter types.
hook_field_info_alter Perform alterations on Field API field types.
hook_field_info_max_weight Returns the maximum weight for the entity components handled by the module.
hook_field_purge_field_storage Acts when a field storage definition is being purged.
hook_field_purge_instance Acts when a field instance is being purged.
hook_field_storage_config_update_forbid Forbid a field storage update from occurring.
hook_field_widget_form_alter Alter forms for field widgets provided by other modules.
hook_field_widget_info_alter Perform alterations on Field API widget types.
hook_field_widget_WIDGET_TYPE_form_alter Alter widget forms for a specific widget provided by another module.

File

drupal/core/modules/field/field.api.php
View source
  1. <?php
  2. /**
  3. * @addtogroup hooks
  4. * @{
  5. */
  6. use Drupal\Component\Utility\NestedArray;
  7. /**
  8. * @defgroup field_types Field Types API
  9. * @{
  10. * Defines field, widget, display formatter, and storage types.
  11. *
  12. * In the Field API, each field has a type, which determines what kind of data
  13. * (integer, string, date, etc.) the field can hold, which settings it provides,
  14. * and so on. The data type(s) accepted by a field are defined in
  15. * hook_field_schema().
  16. *
  17. * Field types are plugins annotated with class
  18. * \Drupal\Core\Field\Annotation\FieldType, and implement plugin interface
  19. * \Drupal\Core\Field\FieldItemInterface. Field Type plugins are managed by the
  20. * \Drupal\Core\Field\FieldTypePluginManager class. Field type classes usually
  21. * extend base class \Drupal\Core\Field\FieldItemBase. Field-type plugins need
  22. * to be in the namespace \Drupal\{your_module}\Plugin\Field\FieldType. See the
  23. * @link plugin_api Plugin API topic @endlink for more information on how to
  24. * define plugins.
  25. *
  26. * The Field Types API also defines two kinds of pluggable handlers: widgets
  27. * and formatters. @link field_widget Widgets @endlink specify how the field
  28. * appears in edit forms, while @link field_formatter formatters @endlink
  29. * specify how the field appears in displayed entities.
  30. *
  31. * See @link field Field API @endlink for information about the other parts of
  32. * the Field API.
  33. *
  34. * @see field
  35. * @see field_widget
  36. * @see field_formatter
  37. * @see plugin_api
  38. */
  39. /**
  40. * Perform alterations on Field API field types.
  41. *
  42. * @param $info
  43. * Array of information on field types as collected by the "field type" plugin
  44. * manager.
  45. */
  46. function hook_field_info_alter(&$info) {
  47. // Change the default widget for fields of type 'foo'.
  48. if (isset($info['foo'])) {
  49. $info['foo']['default widget'] = 'mymodule_widget';
  50. }
  51. }
  52. /**
  53. * @} End of "defgroup field_types".
  54. */
  55. /**
  56. * @defgroup field_widget Field Widget API
  57. * @{
  58. * Define Field API widget types.
  59. *
  60. * Field API widgets specify how fields are displayed in edit forms. Fields of a
  61. * given @link field_types field type @endlink may be edited using more than one
  62. * widget. In this case, the Field UI module allows the site builder to choose
  63. * which widget to use.
  64. *
  65. * Widgets are Plugins managed by the
  66. * \Drupal\Core\Field\WidgetPluginManager class. A widget is a plugin annotated
  67. * with class \Drupal\Core\Field\Annotation\FieldWidget that implements
  68. * \Drupal\Core\Field\WidgetInterface (in most cases, by
  69. * subclassing \Drupal\Core\Field\WidgetBase). Widget plugins need to be in the
  70. * namespace \Drupal\{your_module}\Plugin\Field\FieldWidget.
  71. *
  72. * Widgets are @link forms_api_reference.html Form API @endlink
  73. * elements with additional processing capabilities. The methods of the
  74. * WidgetInterface object are typically called by respective methods in the
  75. * \Drupal\entity\Entity\EntityFormDisplay class.
  76. *
  77. * @see field
  78. * @see field_types
  79. * @see field_formatter
  80. * @see plugin_api
  81. */
  82. /**
  83. * Perform alterations on Field API widget types.
  84. *
  85. * @param array $info
  86. * An array of information on existing widget types, as collected by the
  87. * annotation discovery mechanism.
  88. */
  89. function hook_field_widget_info_alter(array &$info) {
  90. // Let a new field type re-use an existing widget.
  91. $info['options_select']['field_types'][] = 'my_field_type';
  92. }
  93. /**
  94. * Alter forms for field widgets provided by other modules.
  95. *
  96. * @param $element
  97. * The field widget form element as constructed by hook_field_widget_form().
  98. * @param $form_state
  99. * An associative array containing the current state of the form.
  100. * @param $context
  101. * An associative array containing the following key-value pairs:
  102. * - form: The form structure to which widgets are being attached. This may be
  103. * a full form structure, or a sub-element of a larger form.
  104. * - widget: The widget plugin instance.
  105. * - items: The field values, as a
  106. * \Drupal\Core\Field\FieldItemListInterface object.
  107. * - delta: The order of this item in the array of subelements (0, 1, 2, etc).
  108. * - default: A boolean indicating whether the form is being shown as a dummy
  109. * form to set default values.
  110. *
  111. * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
  112. * @see hook_field_widget_WIDGET_TYPE_form_alter()
  113. */
  114. function hook_field_widget_form_alter(&$element, &$form_state, $context) {
  115. // Add a css class to widget form elements for all fields of type mytype.
  116. $field_definition = $context['items']->getFieldDefinition();
  117. if ($field_definition->getType() == 'mytype') {
  118. // Be sure not to overwrite existing attributes.
  119. $element['#attributes']['class'][] = 'myclass';
  120. }
  121. }
  122. /**
  123. * Alter widget forms for a specific widget provided by another module.
  124. *
  125. * Modules can implement hook_field_widget_WIDGET_TYPE_form_alter() to modify a
  126. * specific widget form, rather than using hook_field_widget_form_alter() and
  127. * checking the widget type.
  128. *
  129. * @param $element
  130. * The field widget form element as constructed by hook_field_widget_form().
  131. * @param $form_state
  132. * An associative array containing the current state of the form.
  133. * @param $context
  134. * An associative array. See hook_field_widget_form_alter() for the structure
  135. * and content of the array.
  136. *
  137. * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
  138. * @see hook_field_widget_form_alter()
  139. */
  140. function hook_field_widget_WIDGET_TYPE_form_alter(&$element, &$form_state, $context) {
  141. // Code here will only act on widgets of type WIDGET_TYPE. For example,
  142. // hook_field_widget_mymodule_autocomplete_form_alter() will only act on
  143. // widgets of type 'mymodule_autocomplete'.
  144. $element['#autocomplete_route_name'] = 'mymodule.autocomplete_route';
  145. }
  146. /**
  147. * @} End of "defgroup field_widget".
  148. */
  149. /**
  150. * @defgroup field_formatter Field Formatter API
  151. * @{
  152. * Define Field API formatter types.
  153. *
  154. * Field API formatters specify how fields are displayed when the entity to
  155. * which the field is attached is displayed. Fields of a given
  156. * @link field_types field type @endlink may be displayed using more than one
  157. * formatter. In this case, the Field UI module allows the site builder to
  158. * choose which formatter to use.
  159. *
  160. * Formatters are Plugins managed by the
  161. * \Drupal\Core\Field\FormatterPluginManager class. A formatter is a plugin
  162. * annotated with class \Drupal\Core\Field\Annotation\FieldFormatter that
  163. * implements \Drupal\Core\Field\FormatterInterface (in most cases, by
  164. * subclassing \Drupal\Core\Field\FormatterBase). Formatter plugins need to be
  165. * in the namespace \Drupal\{your_module}\Plugin\Field\FieldFormatter.
  166. *
  167. * @see field
  168. * @see field_types
  169. * @see field_widget
  170. * @see plugin_api
  171. */
  172. /**
  173. * Perform alterations on Field API formatter types.
  174. *
  175. * @param array $info
  176. * An array of information on existing formatter types, as collected by the
  177. * annotation discovery mechanism.
  178. */
  179. function hook_field_formatter_info_alter(array &$info) {
  180. // Let a new field type re-use an existing formatter.
  181. $info['text_default']['field types'][] = 'my_field_type';
  182. }
  183. /**
  184. * @} End of "defgroup field_formatter".
  185. */
  186. /**
  187. * Returns the maximum weight for the entity components handled by the module.
  188. *
  189. * Field API takes care of fields and 'extra_fields'. This hook is intended for
  190. * third-party modules adding other entity components (e.g. field_group).
  191. *
  192. * @param string $entity_type
  193. * The type of entity; e.g. 'node' or 'user'.
  194. * @param string $bundle
  195. * The bundle name.
  196. * @param string $context
  197. * The context for which the maximum weight is requested. Either 'form' or
  198. * 'display'.
  199. * @param string $context_mode
  200. * The view or form mode name.
  201. *
  202. * @return int
  203. * The maximum weight of the entity's components, or NULL if no components
  204. * were found.
  205. *
  206. * @ingroup field_info
  207. */
  208. function hook_field_info_max_weight($entity_type, $bundle, $context, $context_mode) {
  209. $weights = array();
  210. foreach (my_module_entity_additions($entity_type, $bundle, $context, $context_mode) as $addition) {
  211. $weights[] = $addition['weight'];
  212. }
  213. return $weights ? max($weights) : NULL;
  214. }
  215. /**
  216. * @addtogroup field_purge
  217. * @{
  218. */
  219. /**
  220. * Forbid a field storage update from occurring.
  221. *
  222. * Any module may forbid any update for any reason. For example, the
  223. * field's storage module might forbid an update if it would change
  224. * the storage schema while data for the field exists. A field type
  225. * module might forbid an update if it would change existing data's
  226. * semantics, or if there are external dependencies on field settings
  227. * that cannot be updated.
  228. *
  229. * To forbid the update from occurring, throw a
  230. * \Drupal\Core\Entity\Exception\FieldStorageDefinitionUpdateForbiddenException.
  231. *
  232. * @param \Drupal\field\FieldStorageConfigInterface $field_storage
  233. * The field storage as it will be post-update.
  234. * @param \Drupal\field\FieldStorageConfigInterface $prior_field_storage
  235. * The field storage as it is pre-update.
  236. *
  237. * @see entity_crud
  238. */
  239. function hook_field_storage_config_update_forbid(\Drupal\field\FieldStorageConfigInterface $field_storage, \Drupal\field\FieldStorageConfigInterface $prior_field_storage) {
  240. // A 'list' field stores integer keys mapped to display values. If
  241. // the new field will have fewer values, and any data exists for the
  242. // abandoned keys, the field will have no way to display them. So,
  243. // forbid such an update.
  244. if ($field_storage->hasData() && count($field_storage['settings']['allowed_values']) < count($prior_field_storage['settings']['allowed_values'])) {
  245. // Identify the keys that will be lost.
  246. $lost_keys = array_diff(array_keys($field_storage['settings']['allowed_values']), array_keys($prior_field_storage['settings']['allowed_values']));
  247. // If any data exist for those keys, forbid the update.
  248. $query = new EntityFieldQuery();
  249. $found = $query
  250. ->fieldCondition($prior_field_storage['field_name'], 'value', $lost_keys)
  251. ->range(0, 1)
  252. ->execute();
  253. if ($found) {
  254. throw new \Drupal\Core\Entity\Exception\FieldStorageDefinitionUpdateForbiddenException("Cannot update a list field storage not to include keys with existing data");
  255. }
  256. }
  257. }
  258. /**
  259. * Acts when a field storage definition is being purged.
  260. *
  261. * In field_purge_field_storage(), after the storage definition has been removed
  262. * from the system, the entity storage has purged stored field data, and the
  263. * field definitions cache has been cleared, this hook is invoked on all modules
  264. * to allow them to respond to the field storage being purged.
  265. *
  266. * @param $field_storage \Drupal\field\Entity\FieldStorageConfig
  267. * The field storage being purged.
  268. */
  269. function hook_field_purge_field_storage(\Drupal\field\Entity\FieldStorageConfig $field_storage) {
  270. db_delete('my_module_field_storage_info')
  271. ->condition('uuid', $field_storage->uuid())
  272. ->execute();
  273. }
  274. /**
  275. * Acts when a field instance is being purged.
  276. *
  277. * In field_purge_instance(), after the instance definition has been removed
  278. * from the the system, the entity storage has purged stored field data, and the
  279. * field info cache has been cleared, this hook is invoked on all modules to
  280. * allow them to respond to the field instance being purged.
  281. *
  282. * @param $instance
  283. * The instance being purged.
  284. */
  285. function hook_field_purge_instance($instance) {
  286. db_delete('my_module_field_instance_info')
  287. ->condition('id', $instance['id'])
  288. ->execute();
  289. }
  290. /**
  291. * @} End of "addtogroup field_purge".
  292. */
  293. /**
  294. * @} End of "addtogroup hooks".
  295. */