Drupal 7 has a very great Ajax framework which allow us to use Ajax feature when we build the module. One of Ajax feature that we can develop in Drupal module is Ajax dropdown list. In this tutorial, we will see how create it. For the example, we will create two dropdown list, one contains the list of provinces which already populated at page load, and the other one will be filled dynamically with the cities list based on the selected item in province dropdown list.

The #Ajax Attribute

First, we have to define the #ajax attribute to your select element. This attribute will enable Ajax for your form element, in this case is the dropdown list. The #ajax attribute accept array as its value. The array itself require at least three keys, event, callback, and wrapper. For the province dropdown list, we will use change as the value for event which means the Ajax request will be triggered when the selected province is changed. For the callback value we will fill it with the name of function which will be executed on Ajax request. And then, the wrapper must be filled with the ID of the element that will hold the returned result from the Ajax request.

<?php
/**
 * Function for generating form
 */
function sandbox_ajax_dropdown($form, &$form_state) {
  // Province dropdown list
  $form['sandbox_ajax_dropdown']['province'] = array(
    '#title' => t('Province'),
    '#type' => 'select',
    '#options' => _load_province(),
    '#ajax' => array(
      'event'=>'change',
      'callback' =>'sandbox_ajax_dropdown_city',
      'wrapper' => 'city-wrapper',
    ),
  );

  

// Wrapper for city dropdown list
 $form['sandbox_ajax_dropdown']['wrapper'] = array(
    '#prefix' => '<div id="city-wrapper">',
    '#suffix' => '</div>',
  );

  

// Options for city dropdown list
  $options = array('- Select city -');
  if (isset($form_state['values']['province'])) {
    // Pre-populate options for city dropdown list if province id is set
    $options = _load_city($form_state['values']['province']);
  }

  

// Province dropdown list
  $form['sandbox_ajax_dropdown']['wrapper']['city'] = array(
    '#title' => t('City'),
    '#type' => 'select',
    '#options' => $options,
  );

  

// Form submit button
  $form["sandbox_ajax_dropdown"]["submit"] = array(
    "#value"  => t("Submit"),
    "#type"   => "submit",
    "#submit" => array("sandbox_ajax_dropdown_submit"),
  );

  return 

$form;
}
?>

* Note: the city combobox should be created inside the wrapper.

The Callback Function

Remember the callback we have talked about? This function should return HTML code or renderable element like form element. In our case, we will return the dropdown list element which contains the list of city.

<?php
/**
 * Function for handling ajax request
 */
function sandbox_ajax_dropdown_city($form, $form_state) {
  // Return the dropdown list including the wrapper
  return $form['sandbox_ajax_dropdown']['wrapper'];
}
?>

* Note: the returned dropdown element should include its wrapper.

Prevent The 'Illegal Choice' Error

For you who already try to build the same kind of Ajax dropdown as in this tutorial, you might have the 'Illegal Choice' error for the second Ajax request and after if you put the code to load the city list inside the callback function. The same error might also happen again when you submit the form.

So, the trick to avoid that error is by populating the dropdown list options based on the form state values in the form generation function, not inside the callback function. The callback function only need to return the dropdown list including its wrapper.

<?php
// Options for city dropdown list
$options = array('- Select city -');
if (isset($form_state['values']['province'])) {
  // Pre-populate options for city dropdown list if province id is set
  $options = _load_city($form_state['values']['province']);
}

// Province dropdown list
$form['sandbox_ajax_dropdown']['wrapper']['city'] = array(
  '#title' => t('City'),
  '#type' => 'select',
  '#options' => $options,
);
?>

* Note: this code should be placed inside the function that you use for the form generation process.

Live Demo

You can try the live demo here.

The full source code can be downloaded from the attachment section.