Format a dropdown menu or scrolling selection box.

Parameters

$title: The label for the form element.

$name: The internal name used to refer to the form element.

$value: The key of the currently selected item, or a linear array of keys of all the currently selected items if multiple selections are allowed.

$options: An associative array of buttons to display. The keys in this array are button values, while the values are the labels to display for each button.

$description: Explanatory text to display after the form item.

$extra: Additional HTML to inject into the select element tag.

$multiple: Whether the user may select more than one item.

$required: Whether the user must select a value before submitting the form.

Return value

A themed HTML string representing the form element.

It is possible to group options together; to do this, change the format of $options to an associative array in which the keys are group labels, and the values are associative arrays in the normal $options format.

Related topics

Form generation
Functions to enable output of HTML forms and form elements.
Input validation
Functions to validate user input.
28 calls to form_select()
aggregator_form_feed in modules/aggregator.module
aggregator_settings in modules/aggregator.module
archive_page in modules/archive.module
Menu callback; lists all nodes posted on a given date.
blogapi_settings in modules/blogapi.module
book_form in modules/book.module
Implementation of hook_form().

... See full list

File

includes/common.inc, line 1319
Common functions that many Drupal modules will need to reference.

Code

function form_select($title, $name, $value, $options, $description = NULL, $extra = 0, $multiple = FALSE, $required = FALSE) {
  $select = '';
  foreach ($options as $key => $choice) {
    if (is_array($choice)) {
      $select .= '<optgroup label="' . check_plain($key) . '">';
      foreach ($choice as $key => $choice) {
        $select .= '<option value="' . check_plain($key) . '"' . (is_array($value) ? in_array($key, $value) ? ' selected="selected"' : '' : ($value == $key ? ' selected="selected"' : '')) . '>' . check_plain($choice) . '</option>';
      }
      $select .= '</optgroup>';
    }
    else {
      $select .= '<option value="' . check_plain($key) . '"' . (is_array($value) ? in_array($key, $value) ? ' selected="selected"' : '' : ($value == $key ? ' selected="selected"' : '')) . '>' . check_plain($choice) . '</option>';
    }
  }
  return theme('form_element', $title, '<select name="edit[' . $name . ']' . ($multiple ? '[]' : '') . '"' . ($multiple ? ' multiple="multiple" ' : '') . ($extra ? ' ' . $extra : '') . ' id="edit-' . $name . '">' . $select . '</select>', $description, 'edit-' . $name, $required, _form_get_error($name));
}