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