From aac6a3f9db53637b217b45543848d247c10a36fb Mon Sep 17 00:00:00 2001
From: Alex Pott <alex.a.pott@googlemail.com>
Date: Tue, 22 Dec 2015 00:49:22 +0000
Subject: [PATCH] Issue #2283703 by pjonckiere, jhodgdon: Document how
optgroups work on 'select' form elements
---
.../lib/Drupal/Core/Render/Element/Select.php | 24 ++++++++++++++++---
1 file changed, 21 insertions(+), 3 deletions(-)
diff --git a/core/lib/Drupal/Core/Render/Element/Select.php b/core/lib/Drupal/Core/Render/Element/Select.php
index b028c428aa97..31487372240a 100644
--- a/core/lib/Drupal/Core/Render/Element/Select.php
+++ b/core/lib/Drupal/Core/Render/Element/Select.php
@@ -14,12 +14,30 @@
* Provides a form element for a drop-down menu or scrolling selection box.
*
* Properties:
- * - #options: An associative array, where the keys are the retured values for
- * each option, and the values are the options to be shown in the drop-down
- * list.
+ * - #options: An associative array, where the keys are the values for each
+ * option, and the values are the option labels to be shown in the drop-down
+ * list. If a value is an array, it will be rendered similarly, but as an
+ * optgroup. The key of the sub-array will be used as the label for the
+ * optgroup. Nesting optgroups is not allowed.
* - #empty_option: The label that will be displayed to denote no selection.
* - #empty_value: The value of the option that is used to denote no selection.
*
+ * Usage example:
+ * @code
+ * $form['example_select'] = [
+ * '#type' => 'select',
+ * '#title' => t('Select element'),
+ * '#options' => [
+ * '1' => t('One'),
+ * '2' => [
+ * '2.1' => t('Two point one'),
+ * '2.2' => t('Two point two'),
+ * ],
+ * '3' => t('Three'),
+ * ],
+ * ];
+ * @endcode
+ *
* @FormElement("select")
*/
class Select extends FormElement {
--
GitLab