www.aleph1.co.uk Git - yaffs-website/blob - web/core/lib/Drupal/Core/Field/WidgetBaseInterface.php

   1 <?php
   2
   3 namespace Drupal\Core\Field;
   4
   5 use Drupal\Core\Form\FormStateInterface;
   6 use Symfony\Component\Validator\ConstraintViolationListInterface;
   7
   8 /**
   9  * Base interface definition for "Field widget" plugins.
  10  *
  11  * This interface details base wrapping methods that most widget implementations
  12  * will want to directly inherit from Drupal\Core\Field\WidgetBase. See
  13  * Drupal\Core\Field\WidgetInterface for methods that will more likely be
  14  * overridden in actual widget implementations.
  15  */
  16 interface WidgetBaseInterface extends PluginSettingsInterface {
  17
  18   /**
  19    * Creates a form element for a field.
  20    *
  21    * If the entity associated with the form is new (i.e., $entity->isNew() is
  22    * TRUE), the 'default value', if any, is pre-populated. Also allows other
  23    * modules to alter the form element by implementing their own hooks.
  24    *
  25    * @param \Drupal\Core\Field\FieldItemListInterface $items
  26    *   An array of the field values. When creating a new entity this may be NULL
  27    *   or an empty array to use default values.
  28    * @param array $form
  29    *   An array representing the form that the editing element will be attached
  30    *   to.
  31    * @param \Drupal\Core\Form\FormStateInterface $form_state
  32    *   The current state of the form.
  33    * @param int $get_delta
  34    *   Used to get only a specific delta value of a multiple value field.
  35    *
  36    * @return array
  37    *   The form element array created for this field.
  38    */
  39   public function form(FieldItemListInterface $items, array &$form, FormStateInterface $form_state, $get_delta = NULL);
  40
  41   /**
  42    * Extracts field values from submitted form values.
  43    *
  44    * @param \Drupal\Core\Field\FieldItemListInterface $items
  45    *   The field values. This parameter is altered by reference to receive the
  46    *   incoming form values.
  47    * @param array $form
  48    *   The form structure where field elements are attached to. This might be a
  49    *   full form structure, or a sub-element of a larger form.
  50    * @param \Drupal\Core\Form\FormStateInterface $form_state
  51    *   The form state.
  52    */
  53   public function extractFormValues(FieldItemListInterface $items, array $form, FormStateInterface $form_state);
  54
  55   /**
  56    * Reports field-level validation errors against actual form elements.
  57    *
  58    * @param \Drupal\Core\Field\FieldItemListInterface $items
  59    *   The field values.
  60    * @param \Symfony\Component\Validator\ConstraintViolationListInterface $violations
  61    *   A list of constraint violations to flag.
  62    * @param array $form
  63    *   The form structure where field elements are attached to. This might be a
  64    *   full form structure, or a sub-element of a larger form.
  65    * @param \Drupal\Core\Form\FormStateInterface $form_state
  66    *   The form state.
  67    */
  68   public function flagErrors(FieldItemListInterface $items, ConstraintViolationListInterface $violations, array $form, FormStateInterface $form_state);
  69
  70   /**
  71    * Retrieves processing information about the widget from $form_state.
  72    *
  73    * This method is static so that it can be used in static Form API callbacks.
  74    *
  75    * @param array $parents
  76    *   The array of #parents where the field lives in the form.
  77    * @param string $field_name
  78    *   The field name.
  79    * @param \Drupal\Core\Form\FormStateInterface $form_state
  80    *   The form state.
  81    *
  82    * @return array
  83    *   An array with the following key/value pairs:
  84    *   - items_count: The number of widgets to display for the field.
  85    *   - array_parents: The location of the field's widgets within the $form
  86    *     structure. This entry is populated at '#after_build' time.
  87    */
  88   public static function getWidgetState(array $parents, $field_name, FormStateInterface $form_state);
  89
  90   /**
  91    * Stores processing information about the widget in $form_state.
  92    *
  93    * This method is static so that it can be used in static Form API #callbacks.
  94    *
  95    * @param array $parents
  96    *   The array of #parents where the widget lives in the form.
  97    * @param string $field_name
  98    *   The field name.
  99    * @param \Drupal\Core\Form\FormStateInterface $form_state
 100    *   The form state.
 101    * @param array $field_state
 102    *   The array of data to store. See getWidgetState() for the structure and
 103    *   content of the array.
 104    */
 105   public static function setWidgetState(array $parents, $field_name, FormStateInterface $form_state, array $field_state);
 106
 107 }