function drupal_get_form

Retrieves a form from a builder function, passes it on for processing, and renders the form or redirects to its destination as appropriate. In multi-step form scenarios, it handles properly processing the values using the previous step's form definition, then rendering the requested step for display.

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 building function. Examples may be found in node_forms(), search_forms(), and user_forms().

...: Any additional arguments needed by the form building function.

Return value

The rendered form.

Related topics

File

includes/form.inc, line 48

Code

function drupal_get_form($form_id) {

  // In multi-step form scenarios, the incoming $_POST values are not
  // necessarily intended for the current form. We need to build
  // a copy of the previously built form for validation and processing,
  // then go on to the one that was requested if everything works.
  $form_build_id = md5(mt_rand());
  if (isset($_POST['form_build_id']) && isset($_SESSION['form'][$_POST['form_build_id']]['args']) && $_POST['form_id'] == $form_id) {

    // There's a previously stored multi-step form. We should handle
    // IT first.
    $stored = TRUE;
    $args = $_SESSION['form'][$_POST['form_build_id']]['args'];
    $form = call_user_func_array('drupal_retrieve_form', $args);
    $form['#build_id'] = $_POST['form_build_id'];
  }
  else {

    // We're coming in fresh; build things as they would be. If the
    // form's #multistep flag is set, store the build parameters so
    // the same form can be reconstituted for validation.
    $args = func_get_args();
    $form = call_user_func_array('drupal_retrieve_form', $args);
    if (isset($form['#multistep']) && $form['#multistep']) {

      // Clean up old multistep form session data.
      _drupal_clean_form_sessions();
      $_SESSION['form'][$form_build_id] = array(
        'timestamp' => time(),
        'args' => $args,
      );
      $form['#build_id'] = $form_build_id;
    }
    $stored = FALSE;
  }

  // Process the form, submit it, and store any errors if necessary.
  drupal_process_form($args[0], $form);
  if ($stored && !form_get_errors()) {

    // If it's a stored form and there were no errors, we processed the
    // stored form successfully. Now we need to build the form that was
    // actually requested. We always pass in the current $_POST values
    // to the builder function, as values from one stage of a multistep
    // form can determine how subsequent steps are displayed.
    $args = func_get_args();
    $args[] = $_POST;
    $form = call_user_func_array('drupal_retrieve_form', $args);
    unset($_SESSION['form'][$_POST['form_build_id']]);
    if (isset($form['#multistep']) && $form['#multistep']) {
      $_SESSION['form'][$form_build_id] = array(
        'timestamp' => time(),
        'args' => $args,
      );
      $form['#build_id'] = $form_build_id;
    }
    drupal_prepare_form($args[0], $form);
  }
  return drupal_render_form($args[0], $form);
}