annotate core/lib/Drupal/Core/Field/WidgetBaseInterface.php @ 19:fa3358dc1485 tip

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