Drupal Form API - Using Ajax

I love Drupal's Form API. In just about every project we are either modifying or creating custom forms and thankfully, Drupal's Form API makes executing these tasks a fairly easy process. Everybody loves Ajax so in this tutorial we'll combine these two bits of awesomeness to produce some custom 'ajaxified' forms.

Lets start out with a hook_menu so we have a nice page for our example form. You'll see the "page callback" is the function "drupal_get_form" and our "page argument" is our function that will simply return our associative array.

/**
 * Implements hook_menu().
 */
function deckfifty_menu() {
  $items['example'] = array(
    'title' => 'Example Page',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('deckfifty_example_form'),
    'access arguments' => array('access content'),
  );

  return $items;
}

Next we'll create our form with just a basic select to start. We'll also add a submit button, though it's just there for looks - not that we'll be submitting anything in this tutorial.

/**
 * Custom Example Form.
 */
function deckfifty_example_form($form, &$form_state) {
  $form['fox_color'] = array(
    '#title' => t('Specify the color of the fox:'),
    '#type' => 'select',
    '#options' => drupal_map_assoc(array('', 'brown', 'black', 'white')),
  );

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
  );

  return $form;
}

Now that we have our select in place and we are returning a basic form, let's add the ajax callback function. We'll also need to specify a wrapper - where our ajax content will go.

function deckfifty_example_form($form, &$form_state) {
  $form['fox_color'] = array(
    '#title' => t('Specify the color of the fox:'),
    '#type' => 'select',
    '#options' => drupal_map_assoc(array('', 'brown', 'black', 'white')),
    '#ajax' => array(
      'callback' => 'deckfifty_fox_ajax_callback',
      'wrapper' => 'deckfifty_fox_ajax_wrapper',
    ),
  );

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
  );

  return $form;
}

Now let's add the "wrapper" to the form. We'll add this just below our select - it will just output an empty div.

function deckfifty_example_form($form, &$form_state) {
  $form['fox_color'] = array(
    '#title' => t('Specify the color of the fox:'),
    '#type' => 'select',
    '#options' => drupal_map_assoc(array('', 'brown', 'black', 'white')),
    '#ajax' => array(
      'callback' => 'deckfifty_fox_ajax_callback',
      'wrapper' => 'deckfifty_fox_ajax_wrapper',
    ),
  );
  $form['fox_wrapper'] = array(
    '#type' => 'markup',
    '#prefix' => '
',
    '#suffix' => '
',
  );

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
  );

  return $form;
}

Next, we'll create our callback function and simply return the "fox wrapper" element we just created.

function deckfifty_fox_ajax_callback($form, $form_state) {
  return $form['fox_wrapper'];
}

Lastly, we'll populate that empty wrapper div. This will consist of the "color" that was selected.

function deckfifty_example_form($form, &$form_state) {
  $form['fox_color'] = array(
    '#title' => t('Specify the color of the fox:'),
    '#type' => 'select',
    '#options' => drupal_map_assoc(array('', 'brown', 'black', 'white')),
    '#ajax' => array(
      'callback' => 'deckfifty_fox_ajax_callback',
      'wrapper' => 'deckfifty_fox_ajax_wrapper',
    ),
  );
  $form['fox_wrapper'] = array(
    '#type' => 'markup',
    '#prefix' => '
',
    '#suffix' => '
',
  );

  if( (isset($form_state['values']['fox_color'])) && ($form_state['values']['fox_color'] != '') ) {
    $form['fox_wrapper']['#markup'] = t('The quick @color fox jumps over the lazy dog.', array('@color' => $form_state['values']['fox_color']));
  }

  $form['submit'] = array(
    '#type' => 'submit',
    '#value' => t('Save'),
  );

  return $form;
}

That's it! When the color is changed the sentence will update. Have fun using Ajax with the Form API on your next project!