Code Coverage for /Users/ericduran/Sites/drupal/drupal/core/lib/Drupal/Core/Entity/Display/EntityFormDisplayInterface.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\Entity\Display\EntityFormDisplayInterface.
6	*/
7
8	namespace Drupal\Core\Entity\Display;
9
10	use Drupal\Core\Entity\EntityConstraintViolationListInterface;
11	use Drupal\Core\Entity\FieldableEntityInterface;
12	use Drupal\Core\Form\FormStateInterface;
13
14	/**
15	* Provides a common interface for entity form displays.
16	*/
17	interface EntityFormDisplayInterface extends EntityDisplayInterface {
18
19	/**
20	* Adds field widgets to an entity form.
21	*
22	* The form elements for the entity's fields are added by reference as direct
23	* children in the $form parameter. This parameter can be a full form
24	* structure (most common case for entity edit forms), or a sub-element of a
25	* larger form.
26	*
27	* By default, submitted field values appear at the top-level of
28	* $form_state->getValues(). A different location within
29	* $form_state->getValues() can be specified by setting the '#parents'
30	* property on the incoming $form parameter. Because of name clashes, two
31	* instances of the same field cannot appear within the same $form element, or
32	* within the same '#parents' space.
33	*
34	* Sample resulting structure in $form:
35	* @code
36	* '#parents' => The location of field values in $form_state->getValues(),
37	* '#entity_type' => The name of the entity type,
38	* '#bundle' => The name of the bundle,
39	* // One sub-array per field appearing in the entity, keyed by field name.
40	* // The structure of the array differs slightly depending on whether the
41	* // widget is 'single-value' (provides the input for one field value,
42	* // most common case), and will therefore be repeated as many times as
43	* // needed, or 'multiple-values' (one single widget allows the input of
44	* // several values; e.g., checkboxes, select box, etc.).
45	* 'field_foo' => array(
46	* '#access' => TRUE if the current user has 'edit' grants for the field,
47	* FALSE if not.
48	* 'widget' => array(
49	* '#field_name' => The name of the field,
50	* '#title' => The label of the field,
51	* '#description' => The description text for the field,
52	* '#required' => Whether or not the field is required,
53	* '#field_parents' => The 'parents' space for the field in the form,
54	* equal to the #parents property of the $form parameter received by
55	* this method,
56	*
57	* // For 'multiple-value' widgets, the remaining elements in the
58	* // sub-array depend on the widget.
59	*
60	* // For 'single-value' widgets:
61	* '#theme' => 'field_multiple_value_form',
62	* '#cardinality' => The field cardinality,
63	* '#cardinality_multiple => TRUE if the field can contain multiple
64	* items, FALSE otherwise.
65	* // One sub-array per copy of the widget, keyed by delta.
66	* 0 => array(
67	* '#title' => The title to be displayed by the widget,
68	* '#description' => The description text for the field,
69	* '#required' => Whether the widget should be marked required,
70	* '#delta' => 0,
71	* '#weight' => 0,
72	* '#field_parents' => Same as above,
73	* // The remaining elements in the sub-array depend on the widget.
74	* ...
75	* ),
76	* 1 => array(
77	* ...
78	* ),
79	* ...
80	* ),
81	* ...
82	* ),
83	* )
84	* @endcode
85	*
86	* Additionally, some processing data is placed in $form_state, and can be
87	* accessed by \Drupal\Core\Field\WidgetBaseInterface::getWidgetState() and
88	* \Drupal\Core\Field\WidgetBaseInterface::setWidgetState().
89	*
90	* @param \Drupal\Core\Entity\FieldableEntityInterface $entity
91	* The entity.
92	* @param array $form
93	* The form structure to fill in. This can be a full form structure, or a
94	* sub-element of a larger form. The #parents property can be set to
95	* control the location of submitted field values within
96	* $form_state->getValues(). If not specified, $form['#parents'] is set to
97	* an empty array, which results in field values located at the top-level of
98	* $form_state->getValues().
99	* @param \Drupal\Core\Form\FormStateInterface $form_state
100	* The form state.
101	*/
102	public function buildForm(FieldableEntityInterface $entity, array &$form, FormStateInterface $form_state);
103
104	/**
105	* Extracts field values from the submitted widget values into the entity.
106	*
107	* This accounts for drag-and-drop reordering of field values, and filtering
108	* of empty values.
109	*
110	* @param \Drupal\Core\Entity\FieldableEntityInterface $entity
111	* The entity.
112	* @param array $form
113	* The form structure where field elements are attached to. This might be a
114	* full form structure, or a sub-element of a larger form.
115	* @param \Drupal\Core\Form\FormStateInterface $form_state
116	* The form state.
117	*
118	* @return array
119	* An array whose keys and values are the keys of the top-level entries in
120	* $form_state->getValues() that have been processed. The remaining entries,
121	* if any, do not correspond to widgets and should be extracted manually by
122	* the caller if needed.
123	*/
124	public function extractFormValues(FieldableEntityInterface $entity, array &$form, FormStateInterface $form_state);
125
126	/**
127	* Validates submitted widget values and sets the corresponding form errors.
128	*
129	* This method invokes entity validation and takes care of flagging them on
130	* the form. This is particularly useful when all elements on the form are
131	* managed by the form display.
132	*
133	* As an alternative, entity validation can be invoked separately such that
134	* some violations can be flagged manually. In that case
135	* \Drupal\Core\Entity\Display\EntityFormDisplayInterface::flagViolations()
136	* must be used for flagging violations related to the form display.
137	*
138	* Note that there are two levels of validation for fields in forms: widget
139	* validation and field validation:
140	* - Widget validation steps are specific to a given widget's own form
141	* structure and UI metaphors. They are executed during normal form
142	* validation, usually through Form API's #element_validate property.
143	* Errors reported at this level are typically those that prevent the
144	* extraction of proper field values from the submitted form input.
145	* - If no form / widget errors were reported for the field, field validation
146	* steps are performed according to the "constraints" specified by the
147	* field definition as part of the entity validation. That validation is
148	* independent of the specific widget being used in a given form, and is
149	* also performed on REST entity submissions.
150	*
151	* @param \Drupal\Core\Entity\FieldableEntityInterface $entity
152	* The entity.
153	* @param array $form
154	* The form structure where field elements are attached to. This might be a
155	* full form structure, or a sub-element of a larger form.
156	* @param \Drupal\Core\Form\FormStateInterface $form_state
157	* The form state.
158	*/
159	public function validateFormValues(FieldableEntityInterface $entity, array &$form, FormStateInterface $form_state);
160
161	/**
162	* Flags entity validation violations as form errors.
163	*
164	* This method processes all violations passed, thus any violations not
165	* related to fields of the form display must be processed before this method
166	* is invoked.
167	*
168	* The method flags constraint violations related to fields shown on the
169	* form as form errors on the correct form elements. Possibly pre-existing
170	* violations of hidden fields (so fields not appearing in the display) are
171	* ignored. Other, non-field related violations are passed through and set as
172	* form errors according to the property path of the violations.
173	*
174	* @param \Drupal\Core\Entity\EntityConstraintViolationListInterface $violations
175	* The violations to flag.
176	* @param array $form
177	* The form structure where field elements are attached to. This might be a
178	* full form structure, or a sub-element of a larger form.
179	* @param \Drupal\Core\Form\FormStateInterface $form_state
180	* The form state.
181	*/
182	public function flagWidgetsErrorsFromViolations(EntityConstraintViolationListInterface $violations, array &$form, FormStateInterface $form_state);
183
184	}