Lately I've been wrapped up pretty seriously helping dww migrate Project Issue Tracking to Drupal 6 as part of the Drupal.org sprint in Boston (I'll be joining them on Wednesday). Today I continued work on this issue, specifically converting an old hard coded AHAH routine to use #ahah, eliminating custom security checks and an entire custom Javascript file, not to mention fixing the sheer brokenness of the thing in Drupal 6. I won't walk you through the whole #ahah process; you can get that here. All I want to do is use #ahah to change the structure of a form--and do it it right. Here's what I learned.

So here's the scenario: When replying to an issue, users can change the parent project of that issue. When they select a new project in the dropdown, the version, assigned, and components elements update to display the relevant data for the newly selected project.

And here's the problem with that scenario: The form structure is cached, so even when we changed the elements on the page using the old Drupal 5 way (with the aforementioned custom Javascript), crazy validation errors occured because the form displayed to the user was not the form in the cache. So we decided to abandon the custom approach entirely for Drupal's beautiful #ahah support.

What this boils down to is reflected in the title of this article; using #ahah for a helper function rather than actually submitting a form with it. We need to be able to use the results of the #ahah callback in our form structure so that when the form is actually submitted via plain old POST, the submit and validate functions are none the wiser.

The aforementioned wiki page on Drupal.org was a very helpful starting point, but I needed to do a little more. Here are the issues:

1. The form's #submit callbacks need not to fire. There's a simple way to do that, set $form_state['rebuild'] = TRUE in your #ahah callback.
2. In the #ahah handler drupal_rebuild_form sets $form['#action'] to be the current page. If you're actually submitting the form using #ahah, no big deal. But we're not, we're just altering it. So we needed to set $form['#action'] ourselves in our hook_form_alter function. The end result is not pretty--you get a page full of JSON grossness.
3. The project_issue #validate function needs not to fire in the #ahah callback. So I set an arbitrary flag in the #ahah callback in $form_state (can be anything). I checked for its presence at the beginning of the validate function; if it's there, just return.
4. We also agreed to make a concession to the #ahah system: We moved the assigned dropdown to the same row as component, version, and project because it can also be updated when project changes. It was either this, custom Javascript, or two callbacks.

So here's the replicable part of the #ahah handler. Note where it varies from the wiki example. If you want the full code, check the patches posted against this issue.

$form_state = array('storage' => NULL, 'submitted' => FALSE, 'rebuild' => TRUE);
$form_build_id = $_POST['form_build_id'];
$form = form_get_cache($form_build_id, $form_state);
$args = $form['#parameters'];
$form_id = array_shift($args);
$form_state['post'] = $form['#post'] = $_POST;
$form['#programmed'] = $form['#redirect'] = FALSE;
 
// Skip validation in project issue.
$form_state['project_issue_ahah'] = TRUE;
drupal_process_form($form_id, $form, $form_state);
// everything beyond here just alters the form and then renders the desired chunk.

And here are the relevant snips of hook_form_alter:

// Set the right #action
if (!empty($form['pid']['#value'])) {
  $form['#action'] = url('comment/reply/' . $nid . '/' . $form['pid']['#value']);
}
else {
  $form['#action'] = url('comment/reply/' . $nid);
}
 
// Snip
 
// The #ahah enabled dropdown
$form['project_info']['pid'] = array(
  '#type' => 'select',
  '#title' => t('Project'),
  '#default_value' => $node->project_issue['pid'],
  '#options' => $projects,
  '#required' => TRUE,
  '#ahah' => array(
    'path' => 'project/issues/update_project',
    'wrapper' => 'project-info-wrapper',
    'event' => 'change',
  ),
);
 
// Snip
 
// Need this to have a predictable updatable div.
$form['project_info']['#prefix'] = '<div id="project-info-wrapper" class="inline-options">';
$form['project_info']['#suffix'] = '</div>';

You get a few cool freebies out of this: standardization, security (via form build ID; if the user didn't see the form, they can't change it), less custom code overall, and best of all: an awesome AJAX spinner!

Thanks to chx for the initial explanation and many subsequent clarifications, and to dww for being so patient! Hope this helps someone; I'm quick to correct errors, so if there are any, please say so!