You are here

class Select in Drupal 8

Same name in this branch
  1. 8 core/lib/Drupal/Core/Render/Element/Select.php \Drupal\Core\Render\Element\Select
  2. 8 core/lib/Drupal/Core/Database/Query/Select.php \Drupal\Core\Database\Query\Select
  3. 8 core/lib/Drupal/Core/Database/Driver/sqlite/Select.php \Drupal\Core\Database\Driver\sqlite\Select
  4. 8 core/lib/Drupal/Core/Database/Driver/pgsql/Select.php \Drupal\Core\Database\Driver\pgsql\Select
  5. 8 core/lib/Drupal/Core/Database/Driver/mysql/Select.php \Drupal\Core\Database\Driver\mysql\Select
  6. 8 core/tests/Drupal/Tests/Core/Database/Stub/Select.php \Drupal\Tests\Core\Database\Stub\Select
  7. 8 core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestMysql/Select.php \Drupal\driver_test\Driver\Database\DrivertestMysql\Select
  8. 8 core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestPgsql/Select.php \Drupal\driver_test\Driver\Database\DrivertestPgsql\Select
Same name and namespace in other branches
  1. 9 core/lib/Drupal/Core/Render/Element/Select.php \Drupal\Core\Render\Element\Select

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

Expanded class hierarchy of Select

1 file declares its use of Select
WeightTest.php in core/tests/Drupal/KernelTests/Core/Render/Element/WeightTest.php
7 string references to 'Select'
Connection::select in core/lib/Drupal/Core/Database/Connection.php
Prepares and returns a SELECT query object.
Connection::__construct in core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestMysqlDeprecatedVersion/Connection.php
Constructs a Connection object.
ConnectionTest::providerGetDriverClass in core/tests/Drupal/Tests/Core/Database/ConnectionTest.php
Dataprovider for testGetDriverClass().
ContentModerationConfigureForm::buildConfigurationForm in core/modules/content_moderation/src/Form/ContentModerationConfigureForm.php
Form constructor.
FilterPluginBase::buildExposedFiltersGroupForm in core/modules/views/src/Plugin/views/filter/FilterPluginBase.php
Build the form to let users create the group of exposed filters. This form is displayed when users click on button 'Build group'

... See full list

176 #type uses of Select
AccountForm::form in core/modules/user/src/AccountForm.php
Gets the actual form array to be built.
AccountSettingsForm::buildForm in core/modules/user/src/AccountSettingsForm.php
Form constructor.
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

... See full list

File

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

Namespace

Drupal\Core\Render\Element
View source
class Select extends FormElement {

  /**
   * {@inheritdoc}
   */
  public function getInfo() {
    $class = get_class($this);
    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

Namesort descending Modifiers Type Description Overrides
DependencySerializationTrait::$_entityStorages protected property An array of entity type IDs keyed by the property name of their storages.
DependencySerializationTrait::$_serviceIds protected property An array of service IDs keyed by property name used for serialization.
DependencySerializationTrait::__sleep public function 1
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. 29
MessengerTrait::messenger public function Gets the messenger. 29
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 3
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. 92
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. 1
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.