Using Ajax in Forms

Have you ever needed to refresh only part of a page on a specific event, such as a button click? The best way to do this is using Ajax. Drupal provides an Ajax framework that allows you to partly update a page’s HTML. It is commonly used in forms. For example, on a field change, update this part of the page, or on a button click, update that part of the page. Many form elements have the #ajax property that allows you to use Ajax in the form. The #ajax property accepts an array as value with the following parameters:

#ajax[‘callback’]: The callback function that is called when an event is triggered on the form element.

#ajax[‘path’]: The menu path to be used for the request. It defaults to ‘system/ajax’ and invokes the function ajax_form_callback() that calls the callback function defined in #ajax[‘callback’].

#ajax[‘wrapper’]: The ID of the element to be replaced by the content returned by the callback function.

#ajax[‘effect’]: The jQuery effect that would be produced when replacing the replacing the specified element. Valid options are ‘none’ (which is the default option), ‘slide’, or ‘fade’.

#ajax[‘speed’]: The speed of the jQuery effect. Valid options are ‘slow’ (which is the default option), ‘fast’, or a number in milliseconds.

#ajax[‘event’]: The JavaScript event on which the callback function is invoked. It is only needed if overriding the default behavior of the form widget is necessary.

#ajax[‘prevent’]: A JavaScript event that will be prevented on the specified event trigger. The default event prevented is the click on buttons.

#ajax[‘method’]: The jQuery method that is used to apply the changes on the target element.

#ajax[‘progress’]: The image that represents the progress of getting a response from the server, can be a throbber or a progress bar.

Here is an example of using Ajax in a custom form:

function example_form($form, &$form_state) {
  $form = array();
  $form['selection'] = array(
    '#type' => 'select',
    '#title' => t('Selection'),
    '#options' => array(
      'selection1' => 'Selection 1',
      'selection2' => 'Selection 2',
      'selection3' => 'Selection 3',
    ),
    '#empty_value' => '',
    '#ajax' => array(
      'callback' => 'example_selection_callback',
      'wrapper' => 'message_id',
     ),
  );

  $form['message'] = array(
    '#type' => 'item',
    '#markup' => t('You have not made a selection yet.'),
  );

  return $form;
}

The function example_selection_callback is invoked when the selection of the element $form[‘selection’] is changed and would replace the element $form[‘message’] which contains the ID ‘message_id’.

function example_selection_callback($form, &$form_state) {
  $ajax = array(
    '#type' => 'ajax',
    '#commands' => array(),
  );

  $message = !empty($form_state['values']['selection']) ? t("I choose") . ' ' . $form_state['values']['selection'] : t('You have not made a selection.');

  $ajax['#commands'][] = ajax_command_html('#message_id', $message);

  return $ajax;
} 

This is the function callback for the form element ‘selection’. Whenever the selection is changed, the form element ‘message’ would be updated with the appropriate message. Notice that Ajax helper functions are used in the commands array. In this example, ajax_command_html() is used in order to replace the HTML inside of #message_id without having to refresh the whole page. For a complete list of Ajax commands, please visit Ajax framework commands.