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.

$args: Any additional arguments are passed on to the functions called by drupal_get_form(), plus the original form_state in the beginning. If you are getting a form from the cache, use $form['#parameters'] to shift off the $form_id from its beginning then the resulting array can be used as $arg here.

$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.

Related topics

File

drupal-6.x/includes/form.inc, line 188

Code

function drupal_rebuild_form($form_id, &$form_state, $args, $form_build_id = NULL) {
  // Remove the first argument. This is $form_id.when called from
  // drupal_get_form and the original $form_state when called from some AHAH
  // callback. Neither is needed. After that, put in the current state.
  $args[0] = &$form_state;
  // And the form_id.
  array_unshift($args, $form_id);
  $form = call_user_func_array('drupal_retrieve_form', $args);

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

  // Now, we cache the form structure so it can be retrieved later for
  // validation. If $form_state['storage'] is populated, we'll 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.
  $_POST = array();
  $form['#post'] = array();
  drupal_process_form($form_id, $form, $form_state);
  return $form;
}