Chris@0
|
1 <?php
|
Chris@0
|
2
|
Chris@0
|
3 namespace Drupal\Core\Field;
|
Chris@0
|
4
|
Chris@0
|
5 use Drupal\Core\Form\FormStateInterface;
|
Chris@0
|
6 use Symfony\Component\Validator\ConstraintViolationInterface;
|
Chris@0
|
7
|
Chris@0
|
8 /**
|
Chris@0
|
9 * Interface definition for field widget plugins.
|
Chris@0
|
10 *
|
Chris@0
|
11 * This interface details the methods that most plugin implementations will want
|
Chris@0
|
12 * to override. See Drupal\Core\Field\WidgetBaseInterface for base
|
Chris@0
|
13 * wrapping methods that should most likely be inherited directly from
|
Chris@0
|
14 * Drupal\Core\Field\WidgetBase..
|
Chris@0
|
15 *
|
Chris@0
|
16 * @ingroup field_widget
|
Chris@0
|
17 */
|
Chris@0
|
18 interface WidgetInterface extends WidgetBaseInterface {
|
Chris@0
|
19
|
Chris@0
|
20 /**
|
Chris@0
|
21 * Returns a form to configure settings for the widget.
|
Chris@0
|
22 *
|
Chris@0
|
23 * Invoked from \Drupal\field_ui\Form\EntityDisplayFormBase to allow
|
Chris@0
|
24 * administrators to configure the widget. The field_ui module takes care of
|
Chris@0
|
25 * handling submitted form values.
|
Chris@0
|
26 *
|
Chris@0
|
27 * @param array $form
|
Chris@0
|
28 * The form where the settings form is being included in.
|
Chris@0
|
29 * @param \Drupal\Core\Form\FormStateInterface $form_state
|
Chris@0
|
30 * The current state of the form.
|
Chris@0
|
31 *
|
Chris@0
|
32 * @return array
|
Chris@0
|
33 * The form definition for the widget settings.
|
Chris@0
|
34 */
|
Chris@0
|
35 public function settingsForm(array $form, FormStateInterface $form_state);
|
Chris@0
|
36
|
Chris@0
|
37 /**
|
Chris@0
|
38 * Returns a short summary for the current widget settings.
|
Chris@0
|
39 *
|
Chris@0
|
40 * If an empty result is returned, a UI can still be provided to display
|
Chris@0
|
41 * a settings form in case the widget has configurable settings.
|
Chris@0
|
42 *
|
Chris@0
|
43 * @return array
|
Chris@0
|
44 * A short summary of the widget settings.
|
Chris@0
|
45 */
|
Chris@0
|
46 public function settingsSummary();
|
Chris@0
|
47
|
Chris@0
|
48 /**
|
Chris@0
|
49 * Returns the form for a single field widget.
|
Chris@0
|
50 *
|
Chris@0
|
51 * Field widget form elements should be based on the passed-in $element, which
|
Chris@0
|
52 * contains the base form element properties derived from the field
|
Chris@0
|
53 * configuration.
|
Chris@0
|
54 *
|
Chris@0
|
55 * The BaseWidget methods will set the weight, field name and delta values for
|
Chris@0
|
56 * each form element. If there are multiple values for this field, the
|
Chris@0
|
57 * formElement() method will be called as many times as needed.
|
Chris@0
|
58 *
|
Chris@0
|
59 * Other modules may alter the form element provided by this function using
|
Chris@0
|
60 * hook_field_widget_form_alter() or
|
Chris@0
|
61 * hook_field_widget_WIDGET_TYPE_form_alter().
|
Chris@0
|
62 *
|
Chris@0
|
63 * The FAPI element callbacks (such as #process, #element_validate,
|
Chris@0
|
64 * #value_callback, etc.) used by the widget do not have access to the
|
Chris@0
|
65 * original $field_definition passed to the widget's constructor. Therefore,
|
Chris@0
|
66 * if any information is needed from that definition by those callbacks, the
|
Chris@0
|
67 * widget implementing this method, or a
|
Chris@0
|
68 * hook_field_widget[_WIDGET_TYPE]_form_alter() implementation, must extract
|
Chris@0
|
69 * the needed properties from the field definition and set them as ad-hoc
|
Chris@0
|
70 * $element['#custom'] properties, for later use by its element callbacks.
|
Chris@0
|
71 *
|
Chris@0
|
72 * @param \Drupal\Core\Field\FieldItemListInterface $items
|
Chris@0
|
73 * Array of default values for this field.
|
Chris@0
|
74 * @param int $delta
|
Chris@0
|
75 * The order of this item in the array of sub-elements (0, 1, 2, etc.).
|
Chris@0
|
76 * @param array $element
|
Chris@0
|
77 * A form element array containing basic properties for the widget:
|
Chris@0
|
78 * - #field_parents: The 'parents' space for the field in the form. Most
|
Chris@0
|
79 * widgets can simply overlook this property. This identifies the
|
Chris@0
|
80 * location where the field values are placed within
|
Chris@0
|
81 * $form_state->getValues(), and is used to access processing
|
Chris@0
|
82 * information for the field through the getWidgetState() and
|
Chris@0
|
83 * setWidgetState() methods.
|
Chris@0
|
84 * - #title: The sanitized element label for the field, ready for output.
|
Chris@0
|
85 * - #description: The sanitized element description for the field, ready
|
Chris@0
|
86 * for output.
|
Chris@0
|
87 * - #required: A Boolean indicating whether the element value is required;
|
Chris@0
|
88 * for required multiple value fields, only the first widget's values are
|
Chris@0
|
89 * required.
|
Chris@0
|
90 * - #delta: The order of this item in the array of sub-elements; see $delta
|
Chris@0
|
91 * above.
|
Chris@0
|
92 * @param array $form
|
Chris@0
|
93 * The form structure where widgets are being attached to. This might be a
|
Chris@0
|
94 * full form structure, or a sub-element of a larger form.
|
Chris@0
|
95 * @param \Drupal\Core\Form\FormStateInterface $form_state
|
Chris@0
|
96 * The current state of the form.
|
Chris@0
|
97 *
|
Chris@0
|
98 * @return array
|
Chris@0
|
99 * The form elements for a single widget for this field.
|
Chris@0
|
100 *
|
Chris@0
|
101 * @see hook_field_widget_form_alter()
|
Chris@0
|
102 * @see hook_field_widget_WIDGET_TYPE_form_alter()
|
Chris@0
|
103 */
|
Chris@0
|
104 public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state);
|
Chris@0
|
105
|
Chris@0
|
106 /**
|
Chris@0
|
107 * Assigns a field-level validation error to the right widget sub-element.
|
Chris@0
|
108 *
|
Chris@0
|
109 * Depending on the widget's internal structure, a field-level validation
|
Chris@0
|
110 * error needs to be flagged on the right sub-element.
|
Chris@0
|
111 *
|
Chris@0
|
112 * @param array $element
|
Chris@0
|
113 * An array containing the form element for the widget, as generated by
|
Chris@0
|
114 * formElement().
|
Chris@0
|
115 * @param \Symfony\Component\Validator\ConstraintViolationInterface $violation
|
Chris@0
|
116 * A constraint violation reported during the validation phase.
|
Chris@0
|
117 * @param array $form
|
Chris@0
|
118 * The form structure where field elements are attached to. This might be a
|
Chris@0
|
119 * full form structure, or a sub-element of a larger form.
|
Chris@0
|
120 * @param \Drupal\Core\Form\FormStateInterface $form_state
|
Chris@0
|
121 * The current state of the form.
|
Chris@0
|
122 *
|
Chris@0
|
123 * @return array|bool
|
Chris@0
|
124 * The element on which the error should be flagged, or FALSE to completely
|
Chris@0
|
125 * ignore the violation (use with care!).
|
Chris@0
|
126 */
|
Chris@0
|
127 public function errorElement(array $element, ConstraintViolationInterface $violation, array $form, FormStateInterface $form_state);
|
Chris@0
|
128
|
Chris@0
|
129 /**
|
Chris@0
|
130 * Massages the form values into the format expected for field values.
|
Chris@0
|
131 *
|
Chris@0
|
132 * @param array $values
|
Chris@0
|
133 * The submitted form values produced by the widget.
|
Chris@0
|
134 * - If the widget does not manage multiple values itself, the array holds
|
Chris@0
|
135 * the values generated by the multiple copies of the $element generated
|
Chris@0
|
136 * by the formElement() method, keyed by delta.
|
Chris@0
|
137 * - If the widget manages multiple values, the array holds the values
|
Chris@0
|
138 * of the form element generated by the formElement() method.
|
Chris@0
|
139 * @param array $form
|
Chris@0
|
140 * The form structure where field elements are attached to. This might be a
|
Chris@0
|
141 * full form structure, or a sub-element of a larger form.
|
Chris@0
|
142 * @param \Drupal\Core\Form\FormStateInterface $form_state
|
Chris@0
|
143 * The form state.
|
Chris@0
|
144 *
|
Chris@0
|
145 * @return array
|
Chris@0
|
146 * An array of field values, keyed by delta.
|
Chris@0
|
147 */
|
Chris@0
|
148 public function massageFormValues(array $values, array $form, FormStateInterface $form_state);
|
Chris@0
|
149
|
Chris@0
|
150 /**
|
Chris@0
|
151 * Returns if the widget can be used for the provided field.
|
Chris@0
|
152 *
|
Chris@0
|
153 * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
|
Chris@0
|
154 * The field definition that should be checked.
|
Chris@0
|
155 *
|
Chris@0
|
156 * @return bool
|
Chris@0
|
157 * TRUE if the widget can be used, FALSE otherwise.
|
Chris@0
|
158 */
|
Chris@0
|
159 public static function isApplicable(FieldDefinitionInterface $field_definition);
|
Chris@0
|
160
|
Chris@0
|
161 }
|