drupal_get_form

Definition

drupal_get_form($form_id)
drupal/includes/form.inc, line 48

Description

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.

Name	Description
Form generation	Functions to enable the processing and display of HTML forms.

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

}

API Mirror