You are here

Home » API reference » Drupal 9 » WidgetInterface.php

interface WidgetInterface in Drupal 9

Same name and namespace in other branches
  1. 8 core/lib/Drupal/Core/Field/WidgetInterface.php \Drupal\Core\Field\WidgetInterface
  2. 10 core/lib/Drupal/Core/Field/WidgetInterface.php \Drupal\Core\Field\WidgetInterface

Interface definition for field widget plugins.

This interface details the methods that most plugin implementations will want to override. See Drupal\Core\Field\WidgetBaseInterface for base wrapping methods that should most likely be inherited directly from Drupal\Core\Field\WidgetBase..

Hierarchy

Expanded class hierarchy of WidgetInterface

All classes that implement WidgetInterface

Related topics

Field Widget API
Define Field API widget types.
1 file declares its use of WidgetInterface
field_third_party_test.module in core/modules/field/tests/modules/field_third_party_test/field_third_party_test.module
Test module.

File

core/lib/Drupal/Core/Field/WidgetInterface.php, line 18

Namespace

Drupal\Core\Field
View source 
interface WidgetInterface extends WidgetBaseInterface {

  /**
   * Returns a form to configure settings for the widget.
   *
   * Invoked from \Drupal\field_ui\Form\EntityDisplayFormBase to allow
   * administrators to configure the widget. The field_ui module takes care of
   * handling submitted form values.
   *
   * @param array $form
   *   The form where the settings form is being included in.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
   *
   * @return array
   *   The form definition for the widget settings.
   */
  public function settingsForm(array $form, FormStateInterface $form_state);

  /**
   * Returns a short summary for the current widget settings.
   *
   * If an empty result is returned, a UI can still be provided to display
   * a settings form in case the widget has configurable settings.
   *
   * @return array
   *   A short summary of the widget settings.
   */
  public function settingsSummary();

  /**
   * Returns the form for a single field widget.
   *
   * Field widget form elements should be based on the passed-in $element, which
   * contains the base form element properties derived from the field
   * configuration.
   *
   * The BaseWidget methods will set the weight, field name and delta values for
   * each form element. If there are multiple values for this field, the
   * formElement() method will be called as many times as needed.
   *
   * Other modules may alter the form element provided by this function using
   * hook_field_widget_single_element_form_alter() or
   * hook_field_widget_single_element_WIDGET_TYPE_form_alter().
   *
   * The FAPI element callbacks (such as #process, #element_validate,
   * #value_callback, etc.) used by the widget do not have access to the
   * original $field_definition passed to the widget's constructor. Therefore,
   * if any information is needed from that definition by those callbacks, the
   * widget implementing this method, or a
   * hook_field_widget[_WIDGET_TYPE]_form_alter() implementation, must extract
   * the needed properties from the field definition and set them as ad-hoc
   * $element['#custom'] properties, for later use by its element callbacks.
   *
   * @param \Drupal\Core\Field\FieldItemListInterface $items
   *   Array of default values for this field.
   * @param int $delta
   *   The order of this item in the array of sub-elements (0, 1, 2, etc.).
   * @param array $element
   *   A form element array containing basic properties for the widget:
   *   - #field_parents: The 'parents' space for the field in the form. Most
   *       widgets can simply overlook this property. This identifies the
   *       location where the field values are placed within
   *       $form_state->getValues(), and is used to access processing
   *       information for the field through the getWidgetState() and
   *       setWidgetState() methods.
   *   - #title: The sanitized element label for the field, ready for output.
   *   - #description: The sanitized element description for the field, ready
   *     for output.
   *   - #required: A Boolean indicating whether the element value is required;
   *     for required multiple value fields, only the first widget's values are
   *     required.
   *   - #delta: The order of this item in the array of sub-elements; see $delta
   *     above.
   * @param array $form
   *   The form structure where widgets are being attached to. This might be a
   *   full form structure, or a sub-element of a larger form.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
   *
   * @return array
   *   The form elements for a single widget for this field.
   *
   * @see hook_field_widget_single_element_form_alter()
   * @see hook_field_widget_single_element_WIDGET_TYPE_form_alter()
   */
  public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, FormStateInterface $form_state);

  /**
   * Assigns a field-level validation error to the right widget sub-element.
   *
   * Depending on the widget's internal structure, a field-level validation
   * error needs to be flagged on the right sub-element.
   *
   * @param array $element
   *   An array containing the form element for the widget, as generated by
   *   formElement().
   * @param \Symfony\Component\Validator\ConstraintViolationInterface $violation
   *   A constraint violation reported during the validation phase.
   * @param array $form
   *   The form structure where field elements are attached to. This might be a
   *   full form structure, or a sub-element of a larger form.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
   *
   * @return array|bool
   *   The element on which the error should be flagged, or FALSE to completely
   *   ignore the violation (use with care!).
   */
  public function errorElement(array $element, ConstraintViolationInterface $violation, array $form, FormStateInterface $form_state);

  /**
   * Massages the form values into the format expected for field values.
   *
   * @param array $values
   *   The submitted form values produced by the widget.
   *   - If the widget does not manage multiple values itself, the array holds
   *     the values generated by the multiple copies of the $element generated
   *     by the formElement() method, keyed by delta.
   *   - If the widget manages multiple values, the array holds the values
   *     of the form element generated by the formElement() method.
   * @param array $form
   *   The form structure where field elements are attached to. This might be a
   *   full form structure, or a sub-element of a larger form.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The form state.
   *
   * @return array
   *   An array of field values, keyed by delta.
   */
  public function massageFormValues(array $values, array $form, FormStateInterface $form_state);

  /**
   * Returns if the widget can be used for the provided field.
   *
   * @param \Drupal\Core\Field\FieldDefinitionInterface $field_definition
   *   The field definition that should be checked.
   *
   * @return bool
   *   TRUE if the widget can be used, FALSE otherwise.
   */
  public static function isApplicable(FieldDefinitionInterface $field_definition);

}

Members

Namesort descending Modifiers Type Description Overrides
PluginInspectionInterface::getPluginDefinition public function Gets the definition of the plugin implementation. 4
PluginInspectionInterface::getPluginId public function Gets the plugin_id of the plugin instance. 2
PluginSettingsInterface::defaultSettings public static function Defines the default settings for this plugin. 1
PluginSettingsInterface::getSetting public function Returns the value of a setting, or its default value if absent. 1
PluginSettingsInterface::getSettings public function Returns the array of settings, including defaults for missing settings. 1
PluginSettingsInterface::onDependencyRemoval public function Informs the plugin that some configuration it depends on will be deleted. 1
PluginSettingsInterface::setSetting public function Sets the value of a setting for the plugin. 1
PluginSettingsInterface::setSettings public function Sets the settings for the plugin. 1
ThirdPartySettingsInterface::getThirdPartyProviders public function Gets the list of third parties that store information. 5
ThirdPartySettingsInterface::getThirdPartySetting public function Gets the value of a third-party setting. 5
ThirdPartySettingsInterface::getThirdPartySettings public function Gets all third-party settings of a given module. 5
ThirdPartySettingsInterface::setThirdPartySetting public function Sets the value of a third-party setting. 5
ThirdPartySettingsInterface::unsetThirdPartySetting public function Unsets a third-party setting. 5
WidgetBaseInterface::extractFormValues public function Extracts field values from submitted form values. 1
WidgetBaseInterface::flagErrors public function Reports field-level validation errors against actual form elements. 1
WidgetBaseInterface::form public function Creates a form element for a field. 1
WidgetBaseInterface::getWidgetState public static function Retrieves processing information about the widget from $form_state. 1
WidgetBaseInterface::setWidgetState public static function Stores processing information about the widget in $form_state. 1
WidgetInterface::errorElement public function Assigns a field-level validation error to the right widget sub-element. 1
WidgetInterface::formElement public function Returns the form for a single field widget. 22
WidgetInterface::isApplicable public static function Returns if the widget can be used for the provided field. 1
WidgetInterface::massageFormValues public function Massages the form values into the format expected for field values. 1
WidgetInterface::settingsForm public function Returns a form to configure settings for the widget. 1
WidgetInterface::settingsSummary public function Returns a short summary for the current widget settings. 1