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