summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJennifer Hodgdon2014-09-26 14:32:17 (GMT)
committer Jennifer Hodgdon2014-09-26 14:32:17 (GMT)
commitf2c8d9550ec95b207dde99f45050b81337ae0065 (patch)
tree4de5f3e3ed2f88df4957bcce32c02200a3aae62c
parent8d1e5167f6b40177732f37ce693a189ab6f49021 (diff)
Issue #2283675 by er.pushpinderrana, amitgoyal, mparker17, joachim, mmarquez: Document how optgroups are generated in form_select_options()7.x
-rw-r--r--includes/form.inc48
1 files changed, 37 insertions, 11 deletions
diff --git a/includes/form.inc b/includes/form.inc
index 3840885..b139e43 100644
--- a/includes/form.inc
+++ b/includes/form.inc
@@ -2699,17 +2699,43 @@ function theme_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)) {