Ajax Chain Select

Custom form field comprising chain of dependent select fields (i.e Hierarchical select dropdown) that can be plugged into Drupal forms pro-grammatically. This module is for developers only.

Some usage examples are:

• Hierarchy based country state city drop-downs.
• Hierarchy based select field for Education.

Features:

1. Light Weight and Efficient
2. Simple to Use
3. Customizable as Per Need
4. Scalable
5. On Demand Required Validation
6. Bundle Includes an Example Module

1. Light Weight and Efficient

Instead of using #ajax, direct ajax call is made to fetch the next level data. #ajax is avoided as its a heavy operation involving submission of all form values and various other form processing steps.
Even though direct ajax call is made but its designed in a way that it goes through the regular form validation process checking for any illegal values.

2. Simple to Use

Any beginner level user can also use it easily as follows:

$config = array(
    'country' => array(
      '#title' => t("Country"),
      '#empty_option' => 'Select Country',
      '#default_value' => 1,
      '#title_display' => 'before',
    ),
    'state' => array(
      '#title' => t("State"),
      '#empty_option' => 'Select State',
      '#default_value' => 1,
    ),
    'city' => array(
      '#title' => t("City"),
      '#empty_option' => 'Select City',
    ),
    'locality' => array(
      '#title' => t("Locality"),
    ),
  );

$form['region'] = array(
    '#type' => 'ajax_chain_select',
    '#title' => t('Region'),
    '#config' => $config,
    '#required_levels' => 3,
    '#show_throbber' => TRUE,
    '#progress_message' => t('Please wait..'),
    '#data_callback' => 'my_data_callback',
  );

This will yield following fieldset:

3. Customizable as Per Need

Following things can be customized as follows:

Fieldset Configuration

1. #type: String Should be set to 'ajax_chain_select'.
2. #title String The title of the fieldset. Default is empty string.
3. #config 2-D array Select fields configuration (explained below).
4. #required_levels Integer Till which level the selection is mandatory. E.g: if #required_levels is set to 2, the first 2 levels will be mandatory and rest will be optional. Default is 0 (zero).
5. #show_throbber Boolean Whether to show throbber or not. Default is TRUE.
6. #progress_message String The message to be shown with throbber. Default is 'Please wait..'
7. #data_callback String A valid function name that takes the previous level selection and returns an array of next level elements. (Refer to example module for better understanding)

E.g:

$form['region'] = array(
    '#type' => 'ajax_chain_select',
    '#title' => t('Region'),
    '#config' => $config,
    '#required_levels' => 3,
    '#show_throbber' => TRUE,
    '#progress_message' => t('Please wait..'),
    '#data_callback' => 'my_data_callback',
  );

Select Fields Configuration

Select fields configuration can be set using a 2-D array, where key represent the select field name and the value array represent its configuration as follows:

1. #title: String The title of the select field. Default is empty string.
2. #title_display: String The tile display of select field. Default is 'before'.
3. #empty_option: String The empty option to be shown when no value is selected. Default is '- Select -'.
4. #default_value: Integer The value for pre-selection. Default is NULL.

E.g:

$config = array(
    'country' => array(
      '#title' => t("Country"),
      '#empty_option' => 'Select Country',
      '#default_value' => 1,
      '#title_display' => 'before',
    ),
    'state' => array(
      '#title' => t("State"),
    ),
);

4. Scalable

Depending on the size of array passed to #config, the number of levels are scalable.

5. On Demand Required Validation

Ajax Chain Select executes required validation only for the select fields for which data is present. If data is not present for a level, the required validation is by-passed for that level and the levels after it.

6. Example Module

An example module titled 'Ajax Chain Select Example' is included with it that elaborates how to use Ajax Chain Select.