drupal_rebuild_form

Versions
6: drupal_rebuild_form($form_id, &$form_state, $args, $form_build_id = NULL)
7: drupal_rebuild_form($form_id, &$form_state, $form_build_id = NULL)

Retrieves a form, caches it and processes it with an empty $_POST.

This function clears $_POST and passes the empty $_POST to the form_builder. To preserve some parts from $_POST, pass them in $form_state.

If your AHAH callback simulates the pressing of a button, then your AHAH callback will need to do the same as what drupal_get_form would do when the button is pressed: get the form from the cache, run drupal_process_form over it and then if it needs rebuild, run drupal_rebuild_form over it. Then send back a part of the returned form. $form_state['clicked_button']['#array_parents'] will help you to find which part.

Parameters

$form_id The unique string identifying the desired form. If a function with that name exists, it is called to build the form array. Modules that need to generate the same form (or very similar forms) using different $form_ids can implement hook_forms(), which maps different $form_id values to the proper form constructor function. Examples may be found in node_forms(), search_forms(), and user_forms().

$form_state A keyed array containing the current state of the form. Most important is the $form_state['storage'] collection.

$form_build_id If the AHAH callback calling this function only alters part of the form, then pass in the existing form_build_id so we can re-cache with the same csid.

Return value

The newly built form.

▸ 3 functions call drupal_rebuild_form()

▾ 3 functions call drupal_rebuild_form()

ajax_form_callback in includes/ajax.inc: Menu callback; handles AJAX requests for the #ajax Form API property.
drupal_build_form in includes/form.inc: Build and process a form based on a form id.
file_ajax_upload in modules/file/file.module: Menu callback; Shared AJAX callback for file uploads and deletions.

Code

includes/form.inc, line 311

<?php
function drupal_rebuild_form($form_id, &$form_state, $form_build_id = NULL) {
  $form = drupal_retrieve_form($form_id, $form_state);

  if (!isset($form_build_id)) {
    // We need a new build_id for the new version of the form.
    $form_build_id = 'form-' . md5(mt_rand());
  }
  $form['#build_id'] = $form_build_id;
  drupal_prepare_form($form_id, $form, $form_state);

  if (empty($form_state['no_cache'])) {
    // We cache the form structure so it can be retrieved later for validation.
    // If $form_state['storage'] is populated, we also cache it so that it can
    // be used to resume complex multi-step processes.
    form_set_cache($form_build_id, $form, $form_state);
  }

  // Clear out all post data, as we don't want the previous step's
  // data to pollute this one and trigger validate/submit handling,
  // then process the form for rendering.
  $form_state['input'] = array();

  // Also clear out all group associations as these might be different
  // when rerendering the form.
  $form_state['groups'] = array();

  // Do not call drupal_process_form(), since it would prevent the rebuilt form
  // to submit.
  $form = form_builder($form_id, $form, $form_state);
  return $form;
}
?>