Commit a31b5ea1 authored by jhodgdon's avatar jhodgdon

Issue #2283675 by er.pushpinderrana, amitgoyal, mparker17, joachim, mmarquez:...

Issue #2283675 by er.pushpinderrana, amitgoyal, mparker17, joachim, mmarquez: Document how optgroups are generated in form_select_options()
parent 1f380d88
......@@ -223,17 +223,43 @@ function template_preprocess_select(&$variables) {
}
/**
* Converts a select form element's options array into HTML.
*
* @param $element
* An associative array containing the properties of the element.
* @param $choices
* Mixed: Either an associative array of items to list as choices, or an
* object with an 'option' member that is an associative array. This
* parameter is only used internally and should not be passed.
*
* @return
* An HTML string of options for the select form element.
* Converts an array of options into HTML, for use in select list form elements.
*
* This function calls itself recursively to obtain the values for each optgroup
* within the list of options and when the function encounters an object with
* an 'options' property inside $element['#options'].
*
* @param array $element
* An associative array containing the following key-value pairs:
* - #multiple: Optional Boolean indicating if the user may select more than
* one item.
* - #options: An associative array of options to render as HTML. Each array
* value can be a string, an array, or an object with an 'option' property:
* - A string or integer key whose value is a translated string is
* interpreted as a single HTML option element. Do not use placeholders
* that sanitize data: doing so will lead to double-escaping. Note that
* the key will be visible in the HTML and could be modified by malicious
* users, so don't put sensitive information in it.
* - A translated string key whose value is an array indicates a group of
* options. The translated string is used as the label attribute for the
* optgroup. Do not use placeholders to sanitize data: doing so will lead
* to double-escaping. The array should contain the options you wish to
* group and should follow the syntax of $element['#options'].
* - If the function encounters a string or integer key whose value is an
* object with an 'option' property, the key is ignored, the contents of
* the option property are interpreted as $element['#options'], and the
* resulting HTML is added to the output.
* - #value: Optional integer, string, or array representing which option(s)
* to pre-select when the list is first displayed. The integer or string
* must match the key of an option in the '#options' list. If '#multiple' is
* TRUE, this can be an array of integers or strings.
* @param array|null $choices
* (optional) Either an associative array of options in the same format as
* $element['#options'] above, or NULL. This parameter is only used internally
* and is not intended to be passed in to the initial function call.
*
* @return string
* An HTML string of options and optgroups for use in a select form element.
*/
function form_select_options($element, $choices = NULL) {
if (!isset($choices)) {
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment