diff core/modules/field/field.api.php @ 14:1fec387a4317

Update Drupal core to 8.5.2 via Composer

--- a/core/modules/field/field.api.php	Mon Apr 23 09:33:26 2018 +0100
+++ b/core/modules/field/field.api.php	Mon Apr 23 09:46:53 2018 +0100
@@ -59,6 +59,33 @@
 }
 
 /**
+ * Perform alterations on preconfigured field options.
+ *
+ * @param array $options
+ *   Array of options as returned from
+ *   \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface::getPreconfiguredOptions().
+ * @param string $field_type
+ *   The field type plugin ID.
+ *
+ * @see \Drupal\Core\Field\PreconfiguredFieldUiOptionsInterface::getPreconfiguredOptions()
+ */
+function hook_field_ui_preconfigured_options_alter(array &$options, $field_type) {
+  // If the field is not an "entity_reference"-based field, bail out.
+  /** @var \Drupal\Core\Field\FieldTypePluginManager $field_type_manager */
+  $field_type_manager = \Drupal::service('plugin.manager.field.field_type');
+  $class = $field_type_manager->getPluginClass($field_type);
+  if (!is_a($class, 'Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem', TRUE)) {
+    return;
+  }
+
+  // Set the default formatter for media in entity reference fields to be the
+  // "Rendered entity" formatter.
+  if (!empty($options['media'])) {
+    $options['media']['entity_view_display']['type'] = 'entity_reference_entity_view';
+  }
+}
+
+/**
  * Forbid a field storage update from occurring.
  *
  * Any module may forbid any update for any reason. For example, the
@@ -137,6 +164,11 @@
 /**
  * Alter forms for field widgets provided by other modules.
  *
+ * This hook can only modify individual elements within a field widget and
+ * cannot alter the top level (parent element) for multi-value fields. In most
+ * cases, you should use hook_field_widget_multivalue_form_alter() instead and
+ * loop over the elements.
+ *
  * @param $element
  *   The field widget form element as constructed by
  *   \Drupal\Core\Field\WidgetBaseInterface::form().
@@ -156,6 +188,7 @@
  * @see \Drupal\Core\Field\WidgetBaseInterface::form()
  * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
  * @see hook_field_widget_WIDGET_TYPE_form_alter()
+ * @see hook_field_widget_multivalue_form_alter()
  */
 function hook_field_widget_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
   // Add a css class to widget form elements for all fields of type mytype.
@@ -173,6 +206,11 @@
  * specific widget form, rather than using hook_field_widget_form_alter() and
  * checking the widget type.
  *
+ * This hook can only modify individual elements within a field widget and
+ * cannot alter the top level (parent element) for multi-value fields. In most
+ * cases, you should use hook_field_widget_multivalue_WIDGET_TYPE_form_alter()
+ * instead and loop over the elements.
+ *
  * @param $element
  *   The field widget form element as constructed by
  *   \Drupal\Core\Field\WidgetBaseInterface::form().
@@ -185,6 +223,7 @@
  * @see \Drupal\Core\Field\WidgetBaseInterface::form()
  * @see \Drupal\Core\Field\WidgetBase::formSingleElement()
  * @see hook_field_widget_form_alter()
+ * @see hook_field_widget_multivalue_WIDGET_TYPE_form_alter()
  */
 function hook_field_widget_WIDGET_TYPE_form_alter(&$element, \Drupal\Core\Form\FormStateInterface $form_state, $context) {
   // Code here will only act on widgets of type WIDGET_TYPE.  For example,
@@ -194,6 +233,74 @@
 }
 
 /**
+ * Alter forms for multi-value field widgets provided by other modules.
+ *
+ * To alter the individual elements within the widget, loop over
+ * \Drupal\Core\Render\Element::children($elements).
+ *
+ * @param array $elements
+ *   The field widget form elements as constructed by
+ *   \Drupal\Core\Field\WidgetBase::formMultipleElements().
+ * @param \Drupal\Core\Form\FormStateInterface $form_state
+ *   The current state of the form.
+ * @param array $context
+ *   An associative array containing the following key-value pairs:
+ *   - 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.
+ *   - widget: The widget plugin instance.
+ *   - items: The field values, as a
+ *     \Drupal\Core\Field\FieldItemListInterface object.
+ *   - default: A boolean indicating whether the form is being shown as a dummy
+ *     form to set default values.
+ *
+ * @see \Drupal\Core\Field\WidgetBaseInterface::form()
+ * @see \Drupal\Core\Field\WidgetBase::formMultipleElements()
+ * @see hook_field_widget_multivalue_WIDGET_TYPE_form_alter()
+ */
+function hook_field_widget_multivalue_form_alter(array &$elements, \Drupal\Core\Form\FormStateInterface $form_state, array $context) {
+  // Add a css class to widget form elements for all fields of type mytype.
+  $field_definition = $context['items']->getFieldDefinition();
+  if ($field_definition->getType() == 'mytype') {
+    // Be sure not to overwrite existing attributes.
+    $elements['#attributes']['class'][] = 'myclass';
+  }
+}
+
+/**
+ * Alter multi-value widget forms for a widget provided by another module.
+ *
+ * Modules can implement hook_field_widget_multivalue_WIDGET_TYPE_form_alter() to
+ * modify a specific widget form, rather than using
+ * hook_field_widget_form_alter() and checking the widget type.
+ *
+ * To alter the individual elements within the widget, loop over
+ * \Drupal\Core\Render\Element::children($elements).
+ *
+ * @param array $elements
+ *   The field widget form elements as constructed by
+ *   \Drupal\Core\Field\WidgetBase::formMultipleElements().
+ * @param \Drupal\Core\Form\FormStateInterface $form_state
+ *   The current state of the form.
+ * @param array $context
+ *   An associative array. See hook_field_widget_multivalue_form_alter() for
+ *   the structure and content of the array.
+ *
+ * @see \Drupal\Core\Field\WidgetBaseInterface::form()
+ * @see \Drupal\Core\Field\WidgetBase::formMultipleElements()
+ * @see hook_field_widget_multivalue_form_alter()
+ */
+function hook_field_widget_multivalue_WIDGET_TYPE_form_alter(array &$elements, \Drupal\Core\Form\FormStateInterface $form_state, array $context) {
+  // Code here will only act on widgets of type WIDGET_TYPE. For example,
+  // hook_field_widget_multivalue_mymodule_autocomplete_form_alter() will only
+  // act on widgets of type 'mymodule_autocomplete'.
+  // Change the autcomplete route for each autocomplete element within the
+  // multivalue widget.
+  foreach (Element::children($elements) as $delta => $element) {
+    $elements[$delta]['#autocomplete_route_name'] = 'mymodule.autocomplete_route';
+  }
+}
+
+/**
  * @} End of "defgroup field_widget".
  */