function drupal_rebuild_form in Drupal 6

Same name and namespace in other branches

1. 7 includes/form.inc \drupal_rebuild_form()

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

2 calls to drupal_rebuild_form()

drupal_get_form in includes/form.inc

Retrieves a form from a constructor function, or from the cache if the form was built in a previous page-load. The form is then passed on for processing, after and rendered for display if necessary.

poll_choice_js in modules/poll/poll.module

Menu callback for AHAH additions.

File

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;
}