Continuing from Form API Changes for Drupal 7, Part 1: $form_state changes.

One of the many pleasant improvements to the Drupal Form API is that AJAX Forms are now really easy. Really easy. We used to call them AHAH forms, and the concept was the same, but they were so complicated that few people attempted them. In D7 we even changed the name to distance ourselves from "AHAH" :-)

In Drupal 6 you had to make a menu entry in hook_menu() that pointed to an AJAX callback handler that was complete black magic. (See a sanitized example.) People did this part differently, and it was hard to figure out the right way. (If you're doing D6 AHAH, the gory details and resources are here.)

In Drupal 7 there is none of that. But we still have to start with the basics so that you'll understand what's going on:

• The key idea here is that manipulating a form element will make something active happen (usually replacement of a piece of the form) without a full page refresh. For example, changing a select might change the options in the rest of the form, without a page refresh.
• To use AJAX forms, you don't need to know or use or see any javascript. It's all handled for you by the Form API.
• To AJAX-enable a form element (to make it do something active when it's manipulated) you just set the #ajax property on it
• When the form element changes (or is clicked, or whatever) a form submission is done by the client in the background.
• The server-side code rebuilds the form (in the formbuilder function) in a different way
• The #ajax['callback'] function chooses what part of the form to replace on the page
• Replacement HTML is returned to the client javascript code, which replaces a part of the page.

OK, so here's all you have to do to AJAXify a form:

1. In your form, set #ajax on an element, perhaps a select.
2. Your formbuilder function should have logic to rebuild differently when the select changes. (See the simple formbuilder in ajax_example_autocheckboxes.)
3. #ajax['callback'] will point to a (typically simple) function which often only selects and returns the changed piece of the form. (See the tremendously simple ajax_example_autocheckboxes_callback.)

That's basically it. Of course you can do lots and lots more than this, but the basic entry point for AJAX forms is mighty easy.

Submit handler is not called when a non-submit is called

One key change from Drupal 6 to be aware of is that when you activate a non-submit AJAX-enabled form element, the submit handlers are not called. In Drupal 6, submit handlers were called, and a bit of spaghetti code was typically done there.

Drupal 7 AJAX Forms Resources

• Drupal.org handbook page on AJAX Forms
• Examples for Developers AJAX Example has many AJAX Form examples, including more complex gracefully-degrading techniques. This is also quickly accessible on api.drupal.org
• Explanation details for the some of the AJAX Examples

Key D7 AJAX Open Issues

There are still a few of important open issues for D7 AJAX that you may want to look at:

• Fix drupal_add_js() and drupal_add_css() to work for AJAX requests too by adding lazy-load to AJAX framework (Absolutely critical - add your +1 to this, or help out)
• #type 'link' is not ajaxifiable
• Improve drupalPostAJAX() to be used more easily, leading to better AJAX test coverage

Next time: Drupal 7 multistep form changes.