Code Coverage for /Users/ericduran/Sites/drupal/drupal/core/lib/Drupal/Core/Field/WidgetInterface.php

	Code Coverage
	Classes and Traits		Functions and Methods				Lines
Total	100.00% covered (success)	0 / 0	100.00% covered (success)	100.00%	0 / 0	CRAP	100.00% covered (success)	100.00%	0 / 0

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