Select
class Select extends FormElement (View source)
Provides a form element for a drop-down menu or scrolling selection box.
Properties:
-
options: An associative array of options for the select. Do not use
placeholders that sanitize data in any labels, as doing so will lead to double-escaping. Each array value can be:
- A single translated string representing an HTML option element, where the outer array key is the option value and the translated string array value is the option label. The option value will be visible in the HTML and can be modified by malicious users, so it should not contain sensitive information and should be treated as possibly malicious data in processing.
- An array representing an HTML optgroup element. The outer array key should be a translated string, and is used as the label for the group. The inner array contains the options for the group (with the keys as option values, and translated string values as option labels). Nesting option groups is not supported.
- An object with an 'option' property. In this case, the outer array key is ignored, and the contents of the 'option' property are interpreted as an array of options to be merged with any other regular options and option groups found in the outer array.
-
sort_options: (optional) If set to TRUE (default is FALSE), sort the
options by their labels, after rendering and translation is complete. Can be set within an option group to sort that group.
-
sort_start: (optional) Option index to start sorting at, where 0 is the
first option. Can be used within an option group. If an empty option is being added automatically (see #empty_option and #empty_value properties), this defaults to 1 to keep the empty option at the top of the list. Otherwise, it defaults to 0.
-
empty_option: (optional) The label to show for the first default option.
By default, the label is automatically set to "- Select -" for a required field and "- None -" for an optional field.
-
empty_value: (optional) The value for the first default option, which is
used to determine whether the user submitted a value or not.
- If #required is TRUE, this defaults to '' (an empty string).
- If #required is not TRUE and this value isn't set, then no extra option is added to the select control, leaving the control in a slightly illogical state, because there's no way for the user to select nothing, since all user agents automatically preselect the first available option. But people are used to this being the behavior of select controls.
Traits
Wrapper methods for \Drupal\Core\StringTranslation\TranslationInterface.
Provides dependency injection friendly methods for serialization.
Provides a trait for the messenger service.
Constants
| DERIVATIVE_SEPARATOR |
A string which is used to separate base plugin IDs from the derivative ID. |
Properties
| protected string | $pluginId | The plugin_id. |
from PluginBase |
| protected array | $pluginDefinition | The plugin implementation definition. |
from PluginBase |
| protected array | $configuration | Configuration information passed into the plugin. |
from PluginBase |
| protected TranslationInterface | $stringTranslation | The string translation service. |
from StringTranslationTrait |
| protected array | $_serviceIds | An array of service IDs keyed by property name used for serialization. |
from DependencySerializationTrait |
| protected array | $_entityStorages | An array of entity type IDs keyed by the property name of their storages. |
from DependencySerializationTrait |
| protected MessengerInterface | $messenger | The messenger. |
from MessengerTrait |
Methods
Constructs a \Drupal\Component\Plugin\PluginBase object.
Translates a string to the current language or to a given language.
Formats a string containing a count of items.
Returns the number of plurals supported by a given language.
Gets the string translation service.
Sets a form element's class attribute.
Adds members of this group as actual elements for rendering.
Form element processing handler for the #ajax form property.
Adds Ajax information about an element to communicate with JavaScript.
Arranges elements into groups.
Determines how user input is mapped to an element's #value property.
process callback for #pattern form element property.
element_validate callback for #pattern form element property.
Adds autocomplete functionality to elements.
Returns the element properties for this element.
Processes a select list form element.
Prepares a select render element.
Details
__construct(array $configuration, string $plugin_id, mixed $plugin_definition)
Constructs a \Drupal\Component\Plugin\PluginBase object.
string
getPluginId()
Gets the plugin_id of the plugin instance.
string
getBaseId()
Gets the base_plugin_id of the plugin instance.
string|null
getDerivativeId()
Gets the derivative_id of the plugin instance.
array
getPluginDefinition()
Gets the definition of the plugin implementation.
bool
isConfigurable()
Determines if the plugin is configurable.
protected TranslatableMarkup
t(string $string, array $args = [], array $options = [])
Translates a string to the current language or to a given language.
See \Drupal\Core\StringTranslation\TranslatableMarkup::__construct() for important security information and usage guidelines.
In order for strings to be localized, make them available in one of the ways supported by the
protected
formatPlural($count, $singular, $plural, array $args = [], array $options = [])
Formats a string containing a count of items.
protected
getNumberOfPlurals($langcode = NULL)
Returns the number of plurals supported by a given language.
protected TranslationInterface
getStringTranslation()
Gets the string translation service.
$this
setStringTranslation(TranslationInterface $translation)
Sets the string translation service to use.
__sleep()
{@inheritdoc}
__wakeup()
{@inheritdoc}
setMessenger(MessengerInterface $messenger)
Sets the messenger.
MessengerInterface
messenger()
Gets the messenger.
static
setAttributes(array $element, array $class = [])
Sets a form element's class attribute.
Adds 'required' and 'error' classes as needed.
static array
preRenderGroup(array $element)
Adds members of this group as actual elements for rendering.
static array
processAjaxForm(array $element, FormStateInterface $form_state, array $complete_form)
Form element processing handler for the #ajax form property.
This method is useful for non-input elements that can be used in and outside the context of a form.
static array
preRenderAjaxForm(array $element)
Adds Ajax information about an element to communicate with JavaScript.
If #ajax is set on an element, this additional JavaScript is added to the page header to attach the Ajax behaviors. See ajax.js for more information.
static array
processGroup(array $element, FormStateInterface $form_state, array $complete_form)
Arranges elements into groups.
This method is useful for non-input elements that can be used in and outside the context of a form.
static mixed
valueCallback(array $element, mixed $input, FormStateInterface $form_state)
Determines how user input is mapped to an element's #value property.
static array
processPattern(array $element, FormStateInterface $form_state, array $complete_form)
process callback for #pattern form element property.
static
validatePattern($element, FormStateInterface $form_state, array $complete_form)
element_validate callback for #pattern form element property.
static array
processAutocomplete(array $element, FormStateInterface $form_state, array $complete_form)
Adds autocomplete functionality to elements.
This sets up autocomplete functionality for elements with an
autocomplete_route_name property, using the #autocomplete_route_parameters
property if present.
For example, suppose your autocomplete route name is 'mymodule.autocomplete' and its path is '/mymodule/autocomplete/{a}/{b}'. In a form array, you would create a text field with properties:
array
getInfo()
Returns the element properties for this element.
static array
processSelect(array $element, FormStateInterface $form_state, array $complete_form)
Processes a select list form element.
This process callback is mandatory for select fields, since all user agents automatically preselect the first available option of single (non-multiple) select lists.
static
preRenderSelect($element)
Prepares a select render element.