class Select

Same name in this branch
  1. 8.9.x core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestMysql/Select.php \Drupal\driver_test\Driver\Database\DrivertestMysql\Select
  2. 8.9.x core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestPgsql/Select.php \Drupal\driver_test\Driver\Database\DrivertestPgsql\Select
  3. 8.9.x core/tests/Drupal/Tests/Core/Database/Stub/Select.php \Drupal\Tests\Core\Database\Stub\Select
  4. 8.9.x core/lib/Drupal/Core/Database/Driver/sqlite/Select.php \Drupal\Core\Database\Driver\sqlite\Select
  5. 8.9.x core/lib/Drupal/Core/Database/Driver/mysql/Select.php \Drupal\Core\Database\Driver\mysql\Select
  6. 8.9.x core/lib/Drupal/Core/Database/Driver/pgsql/Select.php \Drupal\Core\Database\Driver\pgsql\Select
  7. 8.9.x core/lib/Drupal/Core/Database/Query/Select.php \Drupal\Core\Database\Query\Select
Same name in other branches
  1. 9 core/modules/sqlite/src/Driver/Database/sqlite/Select.php \Drupal\sqlite\Driver\Database\sqlite\Select
  2. 9 core/modules/mysql/src/Driver/Database/mysql/Select.php \Drupal\mysql\Driver\Database\mysql\Select
  3. 9 core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestMysql/Select.php \Drupal\driver_test\Driver\Database\DrivertestMysql\Select
  4. 9 core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestMysqlDeprecatedVersion/Select.php \Drupal\driver_test\Driver\Database\DrivertestMysqlDeprecatedVersion\Select
  5. 9 core/modules/system/tests/modules/driver_test/src/Driver/Database/DrivertestPgsql/Select.php \Drupal\driver_test\Driver\Database\DrivertestPgsql\Select
  6. 9 core/modules/pgsql/src/Driver/Database/pgsql/Select.php \Drupal\pgsql\Driver\Database\pgsql\Select
  7. 9 core/tests/Drupal/Tests/Core/Database/Stub/Select.php \Drupal\Tests\Core\Database\Stub\Select
  8. 9 core/tests/fixtures/database_drivers/module/corefake/src/Driver/Database/corefakeWithAllCustomClasses/Select.php \Drupal\corefake\Driver\Database\corefakeWithAllCustomClasses\Select
  9. 9 core/lib/Drupal/Core/Render/Element/Select.php \Drupal\Core\Render\Element\Select
  10. 9 core/lib/Drupal/Core/Database/Driver/sqlite/Select.php \Drupal\Core\Database\Driver\sqlite\Select
  11. 9 core/lib/Drupal/Core/Database/Driver/pgsql/Select.php \Drupal\Core\Database\Driver\pgsql\Select
  12. 9 core/lib/Drupal/Core/Database/Query/Select.php \Drupal\Core\Database\Query\Select
  13. 10 core/modules/sqlite/src/Driver/Database/sqlite/Select.php \Drupal\sqlite\Driver\Database\sqlite\Select
  14. 10 core/modules/mysql/src/Driver/Database/mysql/Select.php \Drupal\mysql\Driver\Database\mysql\Select
  15. 10 core/modules/pgsql/src/Driver/Database/pgsql/Select.php \Drupal\pgsql\Driver\Database\pgsql\Select
  16. 10 core/tests/Drupal/Tests/Core/Database/Stub/Select.php \Drupal\Tests\Core\Database\Stub\Select
  17. 10 core/tests/fixtures/database_drivers/module/core_fake/src/Driver/Database/CoreFakeWithAllCustomClasses/Select.php \Drupal\core_fake\Driver\Database\CoreFakeWithAllCustomClasses\Select
  18. 10 core/lib/Drupal/Core/Render/Element/Select.php \Drupal\Core\Render\Element\Select
  19. 10 core/lib/Drupal/Core/Database/Driver/sqlite/Select.php \Drupal\Core\Database\Driver\sqlite\Select
  20. 10 core/lib/Drupal/Core/Database/Driver/pgsql/Select.php \Drupal\Core\Database\Driver\pgsql\Select
  21. 10 core/lib/Drupal/Core/Database/Query/Select.php \Drupal\Core\Database\Query\Select
  22. 11.x core/modules/sqlite/src/Driver/Database/sqlite/Select.php \Drupal\sqlite\Driver\Database\sqlite\Select
  23. 11.x core/modules/mysql/src/Driver/Database/mysql/Select.php \Drupal\mysql\Driver\Database\mysql\Select
  24. 11.x core/modules/pgsql/src/Driver/Database/pgsql/Select.php \Drupal\pgsql\Driver\Database\pgsql\Select
  25. 11.x core/tests/Drupal/Tests/Core/Database/Stub/Select.php \Drupal\Tests\Core\Database\Stub\Select
  26. 11.x core/tests/fixtures/database_drivers/module/core_fake/src/Driver/Database/CoreFakeWithAllCustomClasses/Select.php \Drupal\core_fake\Driver\Database\CoreFakeWithAllCustomClasses\Select
  27. 11.x core/lib/Drupal/Core/Render/Element/Select.php \Drupal\Core\Render\Element\Select
  28. 11.x core/lib/Drupal/Core/Database/Query/Select.php \Drupal\Core\Database\Query\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
129 string references to 'Select'
AjaxFormPageCacheTest::testSimpleAJAXFormValue in core/tests/Drupal/FunctionalJavascriptTests/Ajax/AjaxFormPageCacheTest.php
Create a simple form, then submit the form via AJAX to change to it.
block_content_post_update_add_views_reusable_filter in core/modules/block_content/block_content.post_update.php
Adds a 'reusable' filter to all Custom Block views.
BooleanOperator::valueForm in core/modules/views/src/Plugin/views/filter/BooleanOperator.php
Options form subform for setting options.
Callbacks::selectCallback in core/modules/system/tests/modules/ajax_forms_test/src/Callbacks.php
Ajax callback triggered by select.
Connection::select in core/lib/Drupal/Core/Database/Connection.php
Prepares and returns a SELECT query object.

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

Title Sort descending Modifiers Object type Summary Overriden Title Overrides
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.
PluginInspectionInterface::getPluginDefinition public function Gets the definition of the plugin implementation. 6
PluginInspectionInterface::getPluginId public function Gets the plugin_id of the plugin instance. 2
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

Buggy or inaccurate documentation? Please file an issue. Need support? Need help programming? Connect with the Drupal community.