aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Entity/Display/EntityFormDisplayInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Entity\Display;
   4
   5 use Drupal\Core\Entity\EntityConstraintViolationListInterface;
   6 use Drupal\Core\Entity\FieldableEntityInterface;
   7 use Drupal\Core\Form\FormStateInterface;
   8
   9 /**
  10  * Provides a common interface for entity form displays.
  11  */
  12 interface EntityFormDisplayInterface extends EntityDisplayInterface {
  13
  14   /**
  15    * Adds field widgets to an entity form.
  16    *
  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
  20    * larger form.
  21    *
  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.
  28    *
  29    * Sample resulting structure in $form:
  30    * @code
  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,
  42    *       FALSE if not.
  43    *     'widget' => array(
  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
  50    *          this method,
  51    *
  52    *       // For 'multiple-value' widgets, the remaining elements in the
  53    *       // sub-array depend on the widget.
  54    *
  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.
  61    *       0 => array(
  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,
  65    *         '#delta' => 0,
  66    *         '#weight' => 0,
  67    *         '#field_parents' => Same as above,
  68    *         // The remaining elements in the sub-array depend on the widget.
  69    *         ...
  70    *       ),
  71    *       1 => array(
  72    *         ...
  73    *       ),
  74    *       ...
  75    *     ),
  76    *     ...
  77    *   ),
  78    * )
  79    * @endcode
  80    *
  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().
  84    *
  85    * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
  86    *   The entity.
  87    * @param array $form
  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
  95    *   The form state.
  96    */
  97   public function buildForm(FieldableEntityInterface $entity, array &$form, FormStateInterface $form_state);
  98
  99   /**
 100    * Extracts field values from the submitted widget values into the entity.
 101    *
 102    * This accounts for drag-and-drop reordering of field values, and filtering
 103    * of empty values.
 104    *
 105    * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
 106    *   The entity.
 107    * @param array $form
 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
 111    *   The form state.
 112    *
 113    * @return array
 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.
 118    */
 119   public function extractFormValues(FieldableEntityInterface $entity, array &$form, FormStateInterface $form_state);
 120
 121   /**
 122    * Validates submitted widget values and sets the corresponding form errors.
 123    *
 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.
 127    *
 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.
 132    *
 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.
 145    *
 146    * @param \Drupal\Core\Entity\FieldableEntityInterface $entity
 147    *   The entity.
 148    * @param array $form
 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
 152    *   The form state.
 153    */
 154   public function validateFormValues(FieldableEntityInterface $entity, array &$form, FormStateInterface $form_state);
 155
 156   /**
 157    * Flags entity validation violations as form errors.
 158    *
 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
 161    * is invoked.
 162    *
 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.
 168    *
 169    * @param \Drupal\Core\Entity\EntityConstraintViolationListInterface $violations
 170    *   The violations to flag.
 171    * @param array $form
 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
 175    *   The form state.
 176    */
 177   public function flagWidgetsErrorsFromViolations(EntityConstraintViolationListInterface $violations, array &$form, FormStateInterface $form_state);
 178
 179 }