WidgetInterface.php 6.26 KB
Newer Older
1 2 3 4
<?php

/**
 * @file
5
 * Contains \Drupal\Core\Field\WidgetInterface.
6 7
 */

8
namespace Drupal\Core\Field;
9

10
use Symfony\Component\Validator\ConstraintViolationInterface;
11 12 13 14 15

/**
 * Interface definition for field widget plugins.
 *
 * This interface details the methods that most plugin implementations will want
16
 * to override. See Drupal\Core\Field\WidgetBaseInterface for base
17
 * wrapping methods that should most likely be inherited directly from
18
 * Drupal\Core\Field\WidgetBase..
19 20
 *
 * @ingroup field_widget
21 22 23 24 25 26
 */
interface WidgetInterface extends WidgetBaseInterface {

  /**
   * Returns a form to configure settings for the widget.
   *
27 28 29
   * Invoked from \Drupal\field_ui\Form\FieldInstanceEditForm to allow
   * administrators to configure the widget. The field_ui module takes care of
   * handling submitted form values.
30 31 32 33 34 35 36 37 38 39 40
   *
   * @param array $form
   *   The form where the settings form is being included in.
   * @param array $form_state
   *   An associative array containing the current state of the form.
   *
   * @return array
   *   The form definition for the widget settings.
   */
  public function settingsForm(array $form, array &$form_state);

41 42 43
  /**
   * Returns a short summary for the current widget settings.
   *
44 45
   * If an empty result is returned, a UI can still be provided to display
   * a settings form in case the widget has configurable settings.
46 47 48 49 50 51
   *
   * @return array
   *   A short summary of the widget settings.
   */
  public function settingsSummary();

52 53 54 55 56 57 58 59 60 61 62 63
  /**
   * Returns the form for a single field widget.
   *
   * Field widget form elements should be based on the passed-in $element, which
   * contains the base form element properties derived from the field
   * configuration.
   *
   * The BaseWidget methods will set the weight, field name and delta values for
   * each form element. If there are multiple values for this field, the
   * formElement() method will be called as many times as needed.
   *
   * Other modules may alter the form element provided by this function using
64 65 66 67 68 69 70 71 72 73 74
   * hook_field_widget_form_alter() or
   * hook_field_widget_WIDGET_TYPE_form_alter().
   *
   * The FAPI element callbacks (such as #process, #element_validate,
   * #value_callback...) used by the widget do not have access to the original
   * $field_definition passed to the widget's constructor. Therefore, if any
   * information is needed from that definition by those callbacks, the widget
   * implementing this method, or a hook_field_widget[_WIDGET_TYPE]_form_alter()
   * implementation, must extract the needed properties from the field
   * definition and set them as ad-hoc $element['#custom'] properties, for later
   * use by its element callbacks.
75
   *
76
   * @param \Drupal\Core\Field\FieldItemListInterface $items
77 78 79 80 81 82 83 84 85
   *   Array of default values for this field.
   * @param int $delta
   *   The order of this item in the array of subelements (0, 1, 2, etc).
   * @param array $element
   *   A form element array containing basic properties for the widget:
   *   - #field_parents: The 'parents' space for the field in the form. Most
   *       widgets can simply overlook this property. This identifies the
   *       location where the field values are placed within
   *       $form_state['values'], and is used to access processing information
86 87
   *       for the field through the getWidgetState() and setWidgetState()
   *       methods.
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
   *   - #title: The sanitized element label for the field instance, ready for
   *     output.
   *   - #description: The sanitized element description for the field instance,
   *     ready for output.
   *   - #required: A Boolean indicating whether the element value is required;
   *     for required multiple value fields, only the first widget's values are
   *     required.
   *   - #delta: The order of this item in the array of subelements; see $delta
   *     above.
   * @param string $form
   *   The form structure where widgets are being attached to. This might be a
   *   full form structure, or a sub-element of a larger form.
   * @param string $form_state
   *   An associative array containing the current state of the form.
   *
   * @return array
   *   The form elements for a single widget for this field.
   *
   * @see hook_field_widget_form_alter()
   * @see hook_field_widget_WIDGET_TYPE_form_alter()
   */
109
  public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, array &$form_state);
110 111 112 113 114 115 116 117 118 119

  /**
   * Assigns a field-level validation error to the right widget sub-element.
   *
   * Depending on the widget's internal structure, a field-level validation
   * error needs to be flagged on the right sub-element.
   *
   * @param array $element
   *   An array containing the form element for the widget, as generated by
   *   formElement().
120 121
   * @param \Symfony\Component\Validator\ConstraintViolationInterface $violation
   *   A constraint violation reported during the validation phase.
122 123 124 125 126 127
   * @param array $form
   *   The form structure where field elements are attached to. This might be a
   *   full form structure, or a sub-element of a larger form.
   * @param array $form_state
   *   An associative array containing the current state of the form.
   *
128 129 130
   * @return array|bool
   *   The element on which the error should be flagged, or FALSE to completely
   *   ignore the violation (use with care!).
131
   */
132
  public function errorElement(array $element, ConstraintViolationInterface $violation, array $form, array &$form_state);
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155

  /**
   * Massages the form values into the format expected for field values.
   *
   * @param array $values
   *   The submitted form values produced by the widget.
   *   - If the widget does not manage multiple values itself, the array holds
   *     the values generated by the multiple copies of the $element generated
   *     by the formElement() method, keyed by delta.
   *   - If the widget manages multiple values, the array holds the values
   *     of the form element generated by the formElement() method.
   * @param array $form
   *   The form structure where field elements are attached to. This might be a
   *   full form structure, or a sub-element of a larger form.
   * @param array $form_state
   *   The form state.
   *
   * @return array
   *   An array of field values, keyed by delta.
   */
  public function massageFormValues(array $values, array $form, array &$form_state);

}