public function EntityFormDisplay::buildForm

public EntityFormDisplay::buildForm(FieldableEntityInterface $entity, array &$form, FormStateInterface $form_state)

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->getValues(). A different location within $form_state->getValues() 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:

  '#parents' => The location of field values in $form_state->getValues(),
  '#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, etc.).
  '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,
      '#title' => The label of the field,
      '#description' => The description text for the field,
      '#required' => Whether or not the field is required,
      '#field_parents' => The 'parents' space for the field in the form,
         equal to the #parents property of the $form parameter received by
         this method,

      // For 'multiple-value' widgets, the remaining elements in the
      // sub-array depend on the widget.

      // For 'single-value' 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(
        '#title' => The title to be displayed by the widget,
        '#description' => The description text for the field,
        '#required' => Whether the widget should be marked required,
        '#delta' => 0,
        '#weight' => 0,
        '#field_parents' => Same as above,
        // The remaining elements in the sub-array depend on the widget.
        ...
      ),
      1 => array(
        ...
      ),
      ...
    ),
    ...
  ),
)

Additionally, some processing data is placed in $form_state, and can be accessed by \Drupal\Core\Field\WidgetBaseInterface::getWidgetState() and \Drupal\Core\Field\WidgetBaseInterface::setWidgetState().

Parameters

\Drupal\Core\Entity\FieldableEntityInterface $entity: The entity.

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->getValues(). If not specified, $form['#parents'] is set to an empty array, which results in field values located at the top-level of $form_state->getValues().

\Drupal\Core\Form\FormStateInterface $form_state: The form state.

Overrides EntityFormDisplayInterface::buildForm

File

core/lib/Drupal/Core/Entity/Entity/EntityFormDisplay.php, line 159

Class

EntityFormDisplay

Configuration entity that contains widget options for all components of a entity form in a given form mode.

Namespace

Drupal\Core\Entity\Entity

Code

public function buildForm(FieldableEntityInterface $entity, array &$form, FormStateInterface $form_state) {
  // Set #parents to 'top-level' by default.
  $form += array('#parents' => array());

  // Let each widget generate the form elements.
  foreach ($this->getComponents() as $name => $options) {
    if ($widget = $this->getRenderer($name)) {
      $items = $entity->get($name);
      $items->filterEmptyItems();
      $form[$name] = $widget->form($items, $form, $form_state);
      $form[$name]['#access'] = $items->access('edit');

      // Assign the correct weight. This duplicates the reordering done in
      // processForm(), but is needed for other forms calling this method
      // directly.
      $form[$name]['#weight'] = $options['weight'];

      // Associate the cache tags for the field definition & field storage
      // definition.
      $field_definition = $this->getFieldDefinition($name);
      $this->renderer->addCacheableDependency($form[$name], $field_definition);
      $this->renderer->addCacheableDependency($form[$name], $field_definition->getFieldStorageDefinition());
    }
  }

  // Associate the cache tags for the form display.
  $this->renderer->addCacheableDependency($form, $this);

  // Add a process callback so we can assign weights and hide extra fields.
  $form['#process'][] = array($this, 'processForm');
}