interface WidgetInterface implements WidgetBaseInterface (View source)

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..

Methods

string

getPluginId()

Gets the plugin_id of the plugin instance.

from PluginInspectionInterface

array

getPluginDefinition()

Gets the definition of the plugin implementation.

from PluginInspectionInterface

$this

setThirdPartySetting(string $module, string $key, mixed $value)

Sets the value of a third-party setting.

from ThirdPartySettingsInterface

mixed

getThirdPartySetting(string $module, string $key, mixed $default = NULL)

Gets the value of a third-party setting.

from ThirdPartySettingsInterface

array

getThirdPartySettings(string $module)

Gets all third-party settings of a given module.

from ThirdPartySettingsInterface

mixed

unsetThirdPartySetting(string $module, string $key)

Unsets a third-party setting.

from ThirdPartySettingsInterface

array

getThirdPartyProviders()

Gets the list of third parties that store information.

from ThirdPartySettingsInterface

static array

defaultSettings()

Defines the default settings for this plugin.

from PluginSettingsInterface

array

getSettings()

Returns the array of settings, including defaults for missing settings.

from PluginSettingsInterface

mixed

getSetting(string $key)

Returns the value of a setting, or its default value if absent.

from PluginSettingsInterface

$this

setSettings(array $settings)

Sets the settings for the plugin.

from PluginSettingsInterface

$this

setSetting(string $key, mixed $value)

Sets the value of a setting for the plugin.

from PluginSettingsInterface

bool

onDependencyRemoval(array $dependencies)

Informs the plugin that some configuration it depends on will be deleted.

from PluginSettingsInterface

array

form(FieldItemListInterface $items, array $form, FormStateInterface $form_state, int $get_delta = NULL)

Creates a form element for a field.

from WidgetBaseInterface

extractFormValues(FieldItemListInterface $items, array $form, FormStateInterface $form_state)

Extracts field values from submitted form values.

from WidgetBaseInterface

flagErrors(FieldItemListInterface $items, ConstraintViolationListInterface $violations, array $form, FormStateInterface $form_state)

Reports field-level validation errors against actual form elements.

from WidgetBaseInterface

static array

getWidgetState(array $parents, string $field_name, FormStateInterface $form_state)

Retrieves processing information about the widget from $form_state.

from WidgetBaseInterface

static

setWidgetState(array $parents, string $field_name, FormStateInterface $form_state, array $field_state)

Stores processing information about the widget in $form_state.

from WidgetBaseInterface

array

settingsForm(array $form, FormStateInterface $form_state)

Returns a form to configure settings for the widget.

array

settingsSummary()

Returns a short summary for the current widget settings.

array

formElement(FieldItemListInterface $items, int $delta, array $element, array $form, FormStateInterface $form_state)

Returns the form for a single field widget.

array|bool

errorElement(array $element, ConstraintViolationInterface $violation, array $form, FormStateInterface $form_state)

Assigns a field-level validation error to the right widget sub-element.

array

massageFormValues(array $values, array $form, FormStateInterface $form_state)

Massages the form values into the format expected for field values.

static bool

isApplicable(FieldDefinitionInterface $field_definition)

Returns if the widget can be used for the provided field.

Details

in PluginInspectionInterface at line 21
`string getPluginId()`

Gets the plugin_id of the plugin instance.

Return Value

string

The plugin_id of the plugin instance.

in PluginInspectionInterface at line 30
`array getPluginDefinition()`

Gets the definition of the plugin implementation.

Return Value

array

The plugin definition, as returned by the discovery object used by the plugin manager.

in ThirdPartySettingsInterface at line 27
`$this setThirdPartySetting(string $module, string $key, mixed $value)`

Sets the value of a third-party setting.

Parameters

string	$module	The module providing the third-party setting.
string	$key	The setting name.
mixed	$value	The setting value.

Return Value

$this

in ThirdPartySettingsInterface at line 42
`mixed getThirdPartySetting(string $module, string $key, mixed $default = NULL)`

Gets the value of a third-party setting.

Parameters

string	$module	The module providing the third-party setting.
string	$key	The setting name.
mixed	$default	The default value

Return Value

mixed

The value.

in ThirdPartySettingsInterface at line 53
`array getThirdPartySettings(string $module)`

Gets all third-party settings of a given module.

Parameters

string

$module

The module providing the third-party settings.

Return Value

array

An array of key-value pairs.

in ThirdPartySettingsInterface at line 66
`mixed unsetThirdPartySetting(string $module, string $key)`

Unsets a third-party setting.

Parameters

string	$module	The module providing the third-party setting.
string	$key	The setting name.

Return Value

mixed

The value.

in ThirdPartySettingsInterface at line 74
`array getThirdPartyProviders()`

Gets the list of third parties that store information.

Return Value

array

The list of third parties.

in PluginSettingsInterface at line 22
`static array defaultSettings()`

Defines the default settings for this plugin.

Return Value

array

A list of default settings, keyed by the setting name.

in PluginSettingsInterface at line 30
`array getSettings()`

Returns the array of settings, including defaults for missing settings.

Return Value

array

The array of settings.

in PluginSettingsInterface at line 41
`mixed getSetting(string $key)`

Returns the value of a setting, or its default value if absent.

Parameters

string

$key

The setting name.

Return Value

mixed

The setting value.

in PluginSettingsInterface at line 52
`$this setSettings(array $settings)`

Sets the settings for the plugin.

Parameters

array

$settings

The array of settings, keyed by setting names. Missing settings will be assigned their default values.

Return Value

$this

in PluginSettingsInterface at line 64
`$this setSetting(string $key, mixed $value)`

Sets the value of a setting for the plugin.

Parameters

string	$key	The setting name.
mixed	$value	The setting value.

Return Value

$this

in PluginSettingsInterface at line 88
`bool onDependencyRemoval(array $dependencies)`

Informs the plugin that some configuration it depends on will be deleted.

This method allows plugins to keep their configuration up-to-date when a dependency calculated with ::calculateDependencies() is removed. For example, an entity view display contains a formatter having a setting pointing to an arbitrary config entity. When that config entity is deleted, this method is called by the view display to react to the dependency removal by updating its configuration.

This method must return TRUE if the removal event updated the plugin configuration or FALSE otherwise.

Parameters

array

$dependencies

An array of dependencies that will be deleted keyed by dependency type. Dependency types are 'config', 'content', 'module' and 'theme'.

Return Value

bool	TRUE if the plugin configuration has changed, FALSE if not.

See also

EntityDisplayBase

in WidgetBaseInterface at line 39
`array form(FieldItemListInterface $items, array $form, FormStateInterface $form_state, int $get_delta = NULL)`

Creates a form element for a field.

If the entity associated with the form is new (i.e., $entity->isNew() is TRUE), the 'default value', if any, is pre-populated. Also allows other modules to alter the form element by implementing their own hooks.

Parameters

FieldItemListInterface	$items	An array of the field values. When creating a new entity this may be NULL or an empty array to use default values.
array	$form	An array representing the form that the editing element will be attached to.
FormStateInterface	$form_state	The current state of the form.
int	$get_delta	Used to get only a specific delta value of a multiple value field.

Return Value

array

The form element array created for this field.

in WidgetBaseInterface at line 53
`extractFormValues(FieldItemListInterface $items, array $form, FormStateInterface $form_state)`

Extracts field values from submitted form values.

Parameters

FieldItemListInterface	$items	The field values. This parameter is altered by reference to receive the incoming form values.
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.
FormStateInterface	$form_state	The form state.

in WidgetBaseInterface at line 68
`flagErrors(FieldItemListInterface $items, ConstraintViolationListInterface $violations, array $form, FormStateInterface $form_state)`

Reports field-level validation errors against actual form elements.

Parameters

FieldItemListInterface	$items	The field values.
ConstraintViolationListInterface	$violations	A list of constraint violations to flag.
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.
FormStateInterface	$form_state	The form state.

in WidgetBaseInterface at line 88
`static array getWidgetState(array $parents, string $field_name, FormStateInterface $form_state)`

Retrieves processing information about the widget from $form_state.

This method is static so that it can be used in static Form API callbacks.

Parameters

array	$parents	The array of #parents where the field lives in the form.
string	$field_name	The field name.
FormStateInterface	$form_state	The form state.

Return Value

array

An array with the following key/value pairs:

items_count: The number of widgets to display for the field.
array_parents: The location of the field's widgets within the $form structure. This entry is populated at '#after_build' time.

in WidgetBaseInterface at line 105
`static setWidgetState(array $parents, string $field_name, FormStateInterface $form_state, array $field_state)`

Stores processing information about the widget in $form_state.

This method is static so that it can be used in static Form API #callbacks.

Parameters

array	$parents	The array of #parents where the widget lives in the form.
string	$field_name	The field name.
FormStateInterface	$form_state	The form state.
array	$field_state	The array of data to store. See getWidgetState() for the structure and content of the array.

at line 35
`array settingsForm(array $form, FormStateInterface $form_state)`

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.

Parameters

array	$form	The form where the settings form is being included in.
FormStateInterface	$form_state	The current state of the form.

Return Value

array

The form definition for the widget settings.

at line 46
`array settingsSummary()`

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 Value

array

A short summary of the widget settings.

at line 104
`array formElement(FieldItemListInterface $items, int $delta, array $element, array $form, FormStateInterface $form_state)`

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.

Parameters

FieldItemListInterface	$items	Array of default values for this field.
int	$delta	The order of this item in the array of sub-elements (0, 1, 2, etc.).
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.
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.
FormStateInterface	$form_state	The current state of the form.

Return Value

array

The form elements for a single widget for this field.

See also

hook_field_widget_single_element_form_alter()
hook_field_widget_single_element_WIDGET_TYPE_form_alter()

at line 127
`array|bool errorElement(array $element, ConstraintViolationInterface $violation, 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.

Parameters

array	$element	An array containing the form element for the widget, as generated by formElement().
ConstraintViolationInterface	$violation	A constraint violation reported during the validation phase.
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.
FormStateInterface	$form_state	The current state of the form.

Return Value

array|bool

The element on which the error should be flagged, or FALSE to completely ignore the violation (use with care!).

at line 148
`array massageFormValues(array $values, array $form, FormStateInterface $form_state)`

Massages the form values into the format expected for field values.

Parameters

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.

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.

FormStateInterface

$form_state

The form state.

Return Value

array

An array of field values, keyed by delta.

at line 159
`static bool isApplicable(FieldDefinitionInterface $field_definition)`

Returns if the widget can be used for the provided field.

Parameters

FieldDefinitionInterface

$field_definition

The field definition that should be checked.

Return Value

bool	TRUE if the widget can be used, FALSE otherwise.