EntityFormDisplayInterface.php 6.79 KB
Newer Older
1 2 3 4 5 6 7 8 9
<?php

/**
 * @file
 * Contains \Drupal\Core\Entity\Display\EntityFormDisplayInterface.
 */

namespace Drupal\Core\Entity\Display;

10 11
use Drupal\Core\Entity\ContentEntityInterface;

12 13 14 15 16
/**
 * Provides a common interface for entity form displays.
 */
interface EntityFormDisplayInterface extends EntityDisplayInterface {

17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
  /**
   * Adds field widgets to an entity form.
   *
   * The form elements for the entity's fields are added by reference as direct
   * children in the $form parameter. This parameter can be a full form
   * structure (most common case for entity edit forms), or a sub-element of a
   * larger form.
   *
   * By default, submitted field values appear at the top-level of
   * $form_state['values']. A different location within $form_state['values']
   * can be specified by setting the '#parents' property on the incoming $form
   * parameter. Because of name clashes, two instances of the same field cannot
   * appear within the same $form element, or within the same '#parents' space.
   *
   * Sample resulting structure in $form:
   * @code
   *   '#parents' => The location of field values in $form_state['values'],
   *   '#entity_type' => The name of the entity type,
   *   '#bundle' => The name of the bundle,
   *   // One sub-array per field appearing in the entity, keyed by field name.
   *   // The structure of the array differs slightly depending on whether the
   *   // widget is 'single-value' (provides the input for one field value,
   *   // most common case), and will therefore be repeated as many times as
   *   // needed, or 'multiple-values' (one single widget allows the input of
   *   // several values, e.g checkboxes, select box...).
   *   'field_foo' => array(
   *     '#access' => TRUE if the current user has 'edit' grants for the field,
   *       FALSE if not.
   *     'widget' => array(
   *       '#field_name' => The name of the field,
   *       '#language' => $langcode,
   *       '#field_parents' => The 'parents' space for the field in the form,
   *          equal to the #parents property of the $form parameter received by
   *          this method,
   *       '#required' => Whether or not the field is required,
   *       '#title' => The label of the field instance,
   *       '#description' => The description text for the field instance,
   *
   *       // Only for 'single' widgets:
   *       '#theme' => 'field_multiple_value_form',
   *       '#cardinality' => The field cardinality,
   *       '#cardinality_multiple => TRUE if the field can contain multiple
   *         items, FALSE otherwise.
   *       // One sub-array per copy of the widget, keyed by delta.
   *       0 => array(
   *         '#entity_type' => The name of the entity type,
   *         '#bundle' => The name of the bundle,
   *         '#field_name' => The name of the field,
   *         '#field_parents' => The 'parents' space for the field in the form,
   *            equal to the #parents property of the $form parameter,
   *         '#title' => The title to be displayed by the widget,
   *         '#default_value' => The field value for delta 0,
   *         '#required' => Whether the widget should be marked required,
   *         '#delta' => 0,
   *         // The remaining elements in the sub-array depend on the widget.
   *         '#type' => The type of the widget,
   *         ...
   *       ),
   *       1 => array(
   *         ...
   *       ),
   *
   *       // Only for multiple widgets:
   *       '#entity_type' => The name of the entity type,
   *       '#bundle' => $instance['bundle'],
   *       // The remaining elements in the sub-array depend on the widget.
   *       '#type' => The type of the widget,
   *       ...
   *     ),
   *     ...
   *   ),
   * )
   * @endcode
   *
   * Additionally, some processing data is placed in $form_state, and can be
   * accessed by field_form_get_state() and field_form_set_state().
   *
   * @param \Drupal\Core\Entity\ContentEntityInterface $entity
   *   The entity.
   * @param array $form
   *   The form structure to fill in. This can be a full form structure, or a
   *   sub-element of a larger form. The #parents property can be set to
   *   control the location of submitted field values within
   *   $form_state['values']. If not specified, $form['#parents'] is set to an
   *   empty array, which results in field values located at the top-level of
   *   $form_state['values'].
   * @param array $form_state
   *   The form state.
   */
  public function buildForm(ContentEntityInterface $entity, array &$form, array &$form_state);

  /**
   * Validates submitted widget values and sets the corresponding form errors.
   *
   * There are two levels of validation for fields in forms: widget validation
   * and field validation.
   * - Widget validation steps are specific to a given widget's own form
   *   structure and UI metaphors. They are executed during normal form
   *   validation, usually through Form API's #element_validate property.
   *   Errors reported at this level are typically those that prevent the
   *   extraction of proper field values from the submitted form input.
   * - If no form / widget errors were reported for the field, field validation
   *   steps are performed according to the "constraints" specified by the
   *   field definition. Those are independent of the specific widget being
   *   used in a given form, and are also performed on REST entity submissions.
   *
   * This function performs field validation in the context of a form submission.
   * It reports field constraint violations as form errors on the correct form
   * elements.
   *
   * @param \Drupal\Core\Entity\ContentEntityInterface $entity
   *   The entity.
   * @param array $form
   *   The form structure where field elements are attached to. This might be a
   *   full form structure, or a sub-element of a larger form.
   * @param array $form_state
   *   The form state.
   */
  public function validateFormValues(ContentEntityInterface $entity, array &$form, array &$form_state);

  /**
   * Extracts field values from the submitted widget values into the entity.
   *
   * This accounts for drag-and-drop reordering of field values, and filtering
   * of empty values.
   *
   * @param \Drupal\Core\Entity\ContentEntityInterface $entity
   *   The entity.
   * @param array $form
   *   The form structure where field elements are attached to. This might be a
   *   full form structure, or a sub-element of a larger form.
   * @param array $form_state
   *   The form state.
   *
   * @return array
   *   An array whose keys and values are the keys of the top-level entries in
   *   $form_state['values'] that have been processed. The remaining entries, if
   *   any, do not correspond to widgets and should be extracted manually by
   *   the caller if needed.
   */
  public function extractFormValues(ContentEntityInterface $entity, array &$form, array &$form_state);

159
}