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

   1 <?php
   2
   3 namespace Drupal\Core\Field;
   4
   5 use Drupal\Core\Form\FormStateInterface;
   6 use Symfony\Component\Validator\ConstraintViolationInterface;
   7
   8 /**
   9  * Interface definition for field widget plugins.
  10  *
  11  * This interface details the methods that most plugin implementations will want
  12  * to override. See Drupal\Core\Field\WidgetBaseInterface for base
  13  * wrapping methods that should most likely be inherited directly from
  14  * Drupal\Core\Field\WidgetBase..
  15  *
  16  * @ingroup field_widget
  17  */
  18 interface WidgetInterface extends WidgetBaseInterface {
  19
  20   /**
  21    * Returns a form to configure settings for the widget.
  22    *
  23    * Invoked from \Drupal\field_ui\Form\EntityDisplayFormBase to allow
  24    * administrators to configure the widget. The field_ui module takes care of
  25    * handling submitted form values.
  26    *
  27    * @param array $form
  28    *   The form where the settings form is being included in.
  29    * @param \Drupal\Core\Form\FormStateInterface $form_state
  30    *   The current state of the form.
  31    *
  32    * @return array
  33    *   The form definition for the widget settings.
  34    */
  35   public function settingsForm(array $form, FormStateInterface $form_state);
  36
  37   /**
  38    * Returns a short summary for the current widget settings.
  39    *
  40    * If an empty result is returned, a UI can still be provided to display
  41    * a settings form in case the widget has configurable settings.
  42    *
  43    * @return array
  44    *   A short summary of the widget settings.
  45    */
  46   public function settingsSummary();
  47
  48   /**
  49    * Returns the form for a single field widget.
  50    *
  51    * Field widget form elements should be based on the passed-in $element, which
  52    * contains the base form element properties derived from the field
  53    * configuration.
  54    *
  55    * The BaseWidget methods will set the weight, field name and delta values for
  56    * each form element. If there are multiple values for this field, the
  57    * formElement() method will be called as many times as needed.
  58    *
  59    * Other modules may alter the form element provided by this function using
  60    * hook_field_widget_form_alter() or
  61    * hook_field_widget_WIDGET_TYPE_form_alter().
  62    *
  63    * The FAPI element callbacks (such as #process, #element_validate,
  64    * #value_callback, etc.) used by the widget do not have access to the
  65    * original $field_definition passed to the widget's constructor. Therefore,
  66    * if any information is needed from that definition by those callbacks, the
  67    * widget implementing this method, or a
  68    * hook_field_widget[_WIDGET_TYPE]_form_alter() implementation, must extract
  69    * the needed properties from the field definition and set them as ad-hoc
  70    * $element['#custom'] properties, for later use by its element callbacks.
  71    *
  72    * @param \Drupal\Core\Field\FieldItemListInterface $items
  73    *   Array of default values for this field.
  74    * @param int $delta
  75    *   The order of this item in the array of sub-elements (0, 1, 2, etc.).
  76    * @param array $element
  77    *   A form element array containing basic properties for the widget:
  78    *   - #field_parents: The 'parents' space for the field in the form. Most
  79    *       widgets can simply overlook this property. This identifies the
  80    *       location where the field values are placed within
  81    *       $form_state->getValues(), and is used to access processing
  82    *       information for the field through the getWidgetState() and
  83    *       setWidgetState() methods.
  84    *   - #title: The sanitized element label for the field, ready for output.
  85    *   - #description: The sanitized element description for the field, ready
  86    *     for output.
  87    *   - #required: A Boolean indicating whether the element value is required;
  88    *     for required multiple value fields, only the first widget's values are
  89    *     required.
  90    *   - #delta: The order of this item in the array of sub-elements; see $delta
  91    *     above.
  92    * @param array $form
  93    *   The form structure where widgets are being attached to. This might be a
  94    *   full form structure, or a sub-element of a larger form.
  95    * @param \Drupal\Core\Form\FormStateInterface $form_state
  96    *   The current state of the form.
  97    *
  98    * @return array
  99    *   The form elements for a single widget for this field.
 100    *
 101    * @see hook_field_widget_form_alter()
 102    * @see hook_field_widget_WIDGET_TYPE_form_alter()
 103    */
 104   public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state);
 105
 106   /**
 107    * Assigns a field-level validation error to the right widget sub-element.
 108    *
 109    * Depending on the widget's internal structure, a field-level validation
 110    * error needs to be flagged on the right sub-element.
 111    *
 112    * @param array $element
 113    *   An array containing the form element for the widget, as generated by
 114    *   formElement().
 115    * @param \Symfony\Component\Validator\ConstraintViolationInterface $violation
 116    *   A constraint violation reported during the validation phase.
 117    * @param array $form
 118    *   The form structure where field elements are attached to. This might be a
 119    *   full form structure, or a sub-element of a larger form.
 120    * @param \Drupal\Core\Form\FormStateInterface $form_state
 121    *   The current state of the form.
 122    *
 123    * @return array|bool
 124    *   The element on which the error should be flagged, or FALSE to completely
 125    *   ignore the violation (use with care!).
 126    */
 127   public function errorElement(array $element, ConstraintViolationInterface $violation, array $form, FormStateInterface $form_state);
 128
 129   /**
 130    * Massages the form values into the format expected for field values.
 131    *
 132    * @param array $values
 133    *   The submitted form values produced by the widget.
 134    *   - If the widget does not manage multiple values itself, the array holds
 135    *     the values generated by the multiple copies of the $element generated
 136    *     by the formElement() method, keyed by delta.
 137    *   - If the widget manages multiple values, the array holds the values
 138    *     of the form element generated by the formElement() method.
 139    * @param array $form
 140    *   The form structure where field elements are attached to. This might be a
 141    *   full form structure, or a sub-element of a larger form.
 142    * @param \Drupal\Core\Form\FormStateInterface $form_state
 143    *   The form state.
 144    *
 145    * @return array
 146    *   An array of field values, keyed by delta.
 147    */
 148   public function massageFormValues(array $values, array $form, FormStateInterface $form_state);
 149
 150   /**
 151    * Returns if the widget can be used for the provided field.
 152    *
 153    * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
 154    *   The field definition that should be checked.
 155    *
 156    * @return bool
 157    *   TRUE if the widget can be used, FALSE otherwise.
 158    */
 159   public static function isApplicable(FieldDefinitionInterface $field_definition);
 160
 161 }