function form_process_select

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.

Parameters

$element: The form element to process. Properties used:

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

See also

_form_validate()

Related topics

Form generation
Functions to enable the processing and display of HTML forms.
1 string reference to 'form_process_select'
system_element_info in drupal/modules/system/system.module
Implements hook_element_info().

File

drupal/includes/form.inc, line 2738
Functions for form and batch generation and processing.

Code

function form_process_select($element) {

  // #multiple select fields need a special #name.
  if ($element['#multiple']) {
    $element['#attributes']['multiple'] = 'multiple';
    $element['#attributes']['name'] = $element['#name'] . '[]';
  }
  else {
    $required = $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 += array(
        '#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 = array(
        $element['#empty_value'] => $element['#empty_option'],
      );
      $element['#options'] = $empty_option + $element['#options'];
    }
  }
  return $element;
}