class Select in Drupal 9

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. @todo Address the above issue in Drupal 8.
  • If #required is not TRUE and this value is set (most commonly to an empty string), then an extra option (see #empty_option above) representing a "non-selection" is added with this as its value.
• #multiple: (optional) Indicates whether one or more options can be selected. Defaults to FALSE.
• #default_value: Must be NULL or not set in case there is no value for the element yet, in which case a first default option is inserted by default. Whether this first option is a valid option depends on whether the field is #required or not.
• #required: (optional) Whether the user needs to select an option (TRUE) or not (FALSE). Defaults to FALSE.
• #size: The number of rows in the list that should be visible at one time.

Usage example:

$form['example_select'] = [
  '#type' => 'select',
  '#title' => $this
    ->t('Select element'),
  '#options' => [
    '1' => $this
      ->t('One'),
    '2' => [
      '2.1' => $this
        ->t('Two point one'),
      '2.2' => $this
        ->t('Two point two'),
    ],
    '3' => $this
      ->t('Three'),
  ],
];

Plugin annotation

@FormElement("select");

Hierarchy

• class \Drupal\Component\Plugin\PluginBase implements DerivativeInspectionInterface, PluginInspectionInterface
  • class \Drupal\Core\Plugin\PluginBase uses DependencySerializationTrait, MessengerTrait, StringTranslationTrait
    • class \Drupal\Core\Render\Element\RenderElement implements ElementInterface
      • class \Drupal\Core\Render\Element\FormElement implements FormElementInterface
        • class \Drupal\Core\Render\Element\Select

1 file declares its use of Select

WeightTest.php in core/tests/Drupal/KernelTests/Core/Render/Element/WeightTest.php

8 string references to 'Select'

Connection::getDriverClass in core/lib/Drupal/Core/Database/Connection.php

Gets the driver-specific override class if any for the specified class.

Connection::select in core/lib/Drupal/Core/Database/Connection.php

Prepares and returns a SELECT query object.

ConnectionTest::providerGetDriverClass in core/tests/Drupal/Tests/Core/Database/ConnectionTest.php

Data provider for testGetDriverClass().

ConnectionTest::testConnectionOptions in core/tests/Drupal/KernelTests/Core/Database/ConnectionTest.php

Tests the connection options of the active database.

ContentModerationConfigureForm::buildConfigurationForm in core/modules/content_moderation/src/Form/ContentModerationConfigureForm.php

Form constructor.

... See full list

174 #type uses of Select

AccountForm::form in core/modules/user/src/AccountForm.php

Gets the actual form array to be built.

ActionAdminManageForm::buildForm in core/modules/action/src/Form/ActionAdminManageForm.php

Form constructor.

AddHandler::buildForm in core/modules/views_ui/src/Form/Ajax/AddHandler.php

Form constructor.

AggregatorFeedBlock::blockForm in core/modules/aggregator/src/Plugin/Block/AggregatorFeedBlock.php

AjaxFormBlock::buildForm in core/modules/system/tests/modules/ajax_forms_test/src/Plugin/Block/AjaxFormBlock.php

Form constructor.

... See full list

File

core/lib/Drupal/Core/Render/Element/Select.php, line 82

Namespace

Drupal\Core\Render\Element

class Select extends FormElement {

  /**
   * {@inheritdoc}
   */
  public function getInfo() {
    $class = static::class;
    return [
      '#input' => TRUE,
      '#multiple' => FALSE,
      '#sort_options' => FALSE,
      '#sort_start' => NULL,
      '#process' => [
        [
          $class,
          'processSelect',
        ],
        [
          $class,
          'processAjaxForm',
        ],
      ],
      '#pre_render' => [
        [
          $class,
          'preRenderSelect',
        ],
      ],
      '#theme' => 'select',
      '#theme_wrappers' => [
        'form_element',
      ],
      '#options' => [],
    ];
  }

  /**
   * 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.
   *
   * @param array $element
   *   The form element to process.
   * @param \Drupal\Core\Form\FormStateInterface $form_state
   *   The current state of the form.
   * @param array $complete_form
   *   The complete form structure.
   *
   * @return array
   *   The processed element.
   *
   * @see _form_validate()
   */
  public static function processSelect(&$element, FormStateInterface $form_state, &$complete_form) {

    // #multiple select fields need a special #name.
    if ($element['#multiple']) {
      $element['#attributes']['multiple'] = 'multiple';
      $element['#attributes']['name'] = $element['#name'] . '[]';
    }
    else {

      // If the element is set to #required through #states, override the
      // element's #required setting.
      $required = isset($element['#states']['required']) ? TRUE : $element['#required'];

      // If the element is required and there is no #default_value, then add an
      // empty option that will fail validation, so that the user is required to
      // make a choice. Also, if there's a value for #empty_value or
      // #empty_option, then add an option that represents emptiness.
      if ($required && !isset($element['#default_value']) || isset($element['#empty_value']) || isset($element['#empty_option'])) {
        $element += [
          '#empty_value' => '',
          '#empty_option' => $required ? t('- Select -') : t('- None -'),
        ];

        // The empty option is prepended to #options and purposively not merged
        // to prevent another option in #options mistakenly using the same value
        // as #empty_value.
        $empty_option = [
          $element['#empty_value'] => $element['#empty_option'],
        ];
        $element['#options'] = $empty_option + $element['#options'];
      }
    }

    // Provide the correct default value for #sort_start.
    $element['#sort_start'] = $element['#sort_start'] ?? (isset($element['#empty_value']) ? 1 : 0);
    return $element;
  }

  /**
   * {@inheritdoc}
   */
  public static function valueCallback(&$element, $input, FormStateInterface $form_state) {
    if ($input !== FALSE) {
      if (isset($element['#multiple']) && $element['#multiple']) {

        // If an enabled multi-select submits NULL, it means all items are
        // unselected. A disabled multi-select always submits NULL, and the
        // default value should be used.
        if (empty($element['#disabled'])) {
          return is_array($input) ? array_combine($input, $input) : [];
        }
        else {
          return isset($element['#default_value']) && is_array($element['#default_value']) ? $element['#default_value'] : [];
        }
      }
      elseif (isset($element['#empty_value']) && $input === (string) $element['#empty_value']) {
        return $element['#empty_value'];
      }
      else {
        return $input;
      }
    }
  }

  /**
   * Prepares a select render element.
   */
  public static function preRenderSelect($element) {
    Element::setAttributes($element, [
      'id',
      'name',
      'size',
    ]);
    static::setAttributes($element, [
      'form-select',
    ]);
    return $element;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
DependencySerializationTrait::$_entityStorages	protected	property
DependencySerializationTrait::$_serviceIds	protected	property
DependencySerializationTrait::__sleep	public	function		2
DependencySerializationTrait::__wakeup	public	function		2
FormElement::processAutocomplete	public static	function	Adds autocomplete functionality to elements.
FormElement::processPattern	public static	function	#process callback for #pattern form element property.
FormElement::validatePattern	public static	function	#element_validate callback for #pattern form element property.
MessengerTrait::$messenger	protected	property	The messenger.	27
MessengerTrait::messenger	public	function	Gets the messenger.	27
MessengerTrait::setMessenger	public	function	Sets the messenger.
PluginBase::$configuration	protected	property	Configuration information passed into the plugin.	1
PluginBase::$pluginDefinition	protected	property	The plugin implementation definition.	1
PluginBase::$pluginId	protected	property	The plugin_id.
PluginBase::DERIVATIVE_SEPARATOR		constant	A string which is used to separate base plugin IDs from the derivative ID.
PluginBase::getBaseId	public	function	Gets the base_plugin_id of the plugin instance. Overrides DerivativeInspectionInterface::getBaseId
PluginBase::getDerivativeId	public	function	Gets the derivative_id of the plugin instance. Overrides DerivativeInspectionInterface::getDerivativeId
PluginBase::getPluginDefinition	public	function	Gets the definition of the plugin implementation. Overrides PluginInspectionInterface::getPluginDefinition	2
PluginBase::getPluginId	public	function	Gets the plugin_id of the plugin instance. Overrides PluginInspectionInterface::getPluginId
PluginBase::isConfigurable	public	function	Determines if the plugin is configurable.
PluginBase::__construct	public	function	Constructs a \Drupal\Component\Plugin\PluginBase object.	98
RenderElement::preRenderAjaxForm	public static	function	Adds Ajax information about an element to communicate with JavaScript.
RenderElement::preRenderGroup	public static	function	Adds members of this group as actual elements for rendering.
RenderElement::processAjaxForm	public static	function	Form element processing handler for the #ajax form property.	1
RenderElement::processGroup	public static	function	Arranges elements into groups.
RenderElement::setAttributes	public static	function	Sets a form element's class attribute. Overrides ElementInterface::setAttributes
Select::getInfo	public	function	Returns the element properties for this element. Overrides ElementInterface::getInfo
Select::preRenderSelect	public static	function	Prepares a select render element.
Select::processSelect	public static	function	Processes a select list form element.
Select::valueCallback	public static	function	Determines how user input is mapped to an element's #value property. Overrides FormElement::valueCallback
StringTranslationTrait::$stringTranslation	protected	property	The string translation service.	4
StringTranslationTrait::formatPlural	protected	function	Formats a string containing a count of items.
StringTranslationTrait::getNumberOfPlurals	protected	function	Returns the number of plurals supported by a given language.
StringTranslationTrait::getStringTranslation	protected	function	Gets the string translation service.
StringTranslationTrait::setStringTranslation	public	function	Sets the string translation service to use.	2
StringTranslationTrait::t	protected	function	Translates a string to the current language or to a given language.