"Fossies" - the Fresh Open Source Software Archive

Member "drupal-8.9.10/core/lib/Drupal/Core/Entity/Display/EntityFormDisplayInterface.php" (26 Nov 2020, 8243 Bytes) of package /linux/www/drupal-8.9.10.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) PHP source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "EntityFormDisplayInterface.php" see the Fossies "Dox" file reference documentation.

    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 }