Doing AHAH Correctly in Drupal 6

For an understanding about what AHAH is, and more specifically, what AHAH in Drupal is, please read the "Introduction to AHAH in Drupal" before reading this section. Here we will launch straight into the problem of adding dynamic form elements in Drupal without violating Form API security.

1. Understanding how your AHAH form should work

Once you have attached an #ahah binding to a form element, there is a pretty strict set-up involved in getting it to work according to best practices. Here is an overview of what needs to be in place:

• Your main function for building the form should react to $form_state, meaning that its elements and their values will be defined based on user-submitted data or data already existing in the database
• You need an AHAH callback function which is called by your #ahah binding
• Your AHAH callback retrieves the form from the cache and goes through the process of rebuilding it, which includes calling submit handlers, the first of which will be the element-specific submit handler for the element your #ahah behaviour is bound to
• Your submit handler needs to retain user-submitted information in $form_state which will then be used in the rebuilding of the form

Many people, when they first start trying to build an AHAH-enabled form, make the mistake of using the AHAH callback to make changes to the form, e.g. adding in a new element or altering an existing one. This is NOT what the AHAH callback is for. The callback simply retrieves, processes and rebuilds the form, then returns whatever portion of it needs to be re-rendered, replacing the originally rendered version of that portion.

So, how does your form actually get changed?
"Changes" to your form essentially translate as "different ways that your form can be built, depending on what's in $form_state". If you can grasp that, you are 90% of the way to nailing AHAH in Drupal.

2. The code you need to achieve this

There are essentially two main tricks beyond simply creating your form that you must follow for AHAH to work smoothly and soundly (and following these can also reduce security holes).

First of all - the form you see on screen and the $form array stored in the cache should always be the same.
Second, the form building function should create subsequent steps based on the contents of $form_state (which is populated in the form's submit handler), and recreate the whole form each time based only on $form_state and data already existing in the database. This function should not use $_POST or similar.

As an example, here is a small excerpt from the top of the function node_form in node.pages.inc:

While that may seem complex and hard to understand, it's really quite simple: we pretend that the user submitted data is already saved in the database and simply show the form that you will get the next time you edit the node.

If you follow the two tricks above, a nice cycle emerges:

1. The form generator creates the form.
2. It gets cached, and rendered.
3. The user submits the AHAH callback, which goes to your callback.
4. You retrieve the form from the cache.
5. You process it with drupal_process_form. Process calls the submit handlers, which put whatever was worthy of keeping into form_state.
6. You call drupal_rebuild_form which first destroys $_POST.
7. The form generator function is called and creates the form again but since it knows to react to form_state, the form will be different.
8. The new form gets cached and processed again, but because $_POST is destroyed, it knows not to call the submit handlers again.
9. Your AHAH callback picks a piece of the form and renders it.

This cycle leads to good and secure code, and also AHAH Zen.

Here's an example from poll.module* of AHAH done right.

Up until and including drupal_rebuild_form your code should be the very same. Yes, it should be a utility function, and it is in D7.

The following example, which comes from quicktabs.module, shows how the above works for non-node forms. There are three #ahah elements in the quicktabs admin form (this form allows you to create blocks of tabbed content, choosing either an existing block or a view for each tab): a button allowing you to add an extra tab to the form (essentially an extra set of elements); a button allowing you to remove a tab from the form; and a views dropdown which, when changed, instantly updates the view display options in another dropdown.

Below is the submit handler for the "add tab" button, followed by the ahah callback for all three ahah elements:

Here we don't need to include modules/node/node.pages.inc because the function that generated the form is in quicktabs.module itself. Notice that the change is being made to the form in the submit handler (incrementing the number of tabs by 1), which is called from drupal_process_form. For this to work, the function generating the form needs to react to $form_state:

Again you can see how $quicktabs = $form_state['quicktabs'] + (array)$quicktabs; we pretend that the user submitted data is already saved.

Finally, here is the submit handler for the views dropdown:

Notice that it doesn't seem to make any change to the form at all - the form is simply going to be rebuilt but with a different selected value for this dropdown, and that will change the options in the display dropdown. The ahah callback for this is the one shown above, which is also the callback used for the remove button, it just has a different submit handler, which decreases the number of tabs by one.

One other thing worth mentioning about the ahah callback is the use of the $javascript array. This trick comes from Wim Leers' AHAH Helper module and enables the re-attachment of ahah behaviors to the ahah-generated form items. Normal jQuery behaviors get re-attached anyway if they are used within Drupal.behaviors, but ahah behaviors only get attached to elements specified in Drupal.settings.ahah. This trick is not necessary for poll.module because the form elements themselves (textfields for entering poll choices) don't have any ahah functionality, but in the case of Quick Tabs, a new Views dropdown is being included with each new set of elements that's added via the "Add tab" button and this needs an ahah behavior attached to it.

To see the full code, visit http://drupal.org/project/quicktabs and download the quicktabs-6.x-2.0-rc1 release. To see the form in action, click here. You will need to change the tab type to "View" in order to see the views display dropdown working.

* the code shown from poll.module is from the D7 version, the ahah callback has not yet been changed in D6

Caution With File Uploads

Using something similar to the above with the 'file' type didn't work. It does work well to add fields, but you have a file to upload, the browser (any old browser) throws up the notorious "HTTP error 0" message.

The problem is detailed much more explicitly here:
http://drupal.org/node/399676

In a nutshell, the code here works perfectly, unless the field type is 'file'