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;
}

Drupal Form API Ajax

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([email protected]' => $form_state['values']['fox_color'])); } $form['submit'] = array( '#type' => 'submit', '#value' => t('Save'), ); return $form; }

Drupal Form API Ajax

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

Shane Graham

Shane Graham

Shane Graham is a senior Drupal developer and co-founder of Deck Fifty Design.

Get in touch

Let's go!

We look forward to hearing from you!