5.x form.inc drupal_prepare_form($form_id, &$form)
6.x form.inc drupal_prepare_form($form_id, &$form, &$form_state)
7.x form.inc drupal_prepare_form($form_id, &$form, &$form_state)

Prepares a structured form array by adding required elements, executing any hook_form_alter functions, and optionally inserting a validation token to prevent tampering.

Parameters

$form_id: A unique string identifying the form for validation, submission, theming, and hook_form_alter functions.

$form: An associative array containing the structure of the form.

Related topics

2 calls to drupal_prepare_form()
drupal_get_form in includes/form.inc
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…
drupal_process_form in includes/form.inc
This function is the heart of form API. The form gets built, validated and in appropriate cases, submitted.

File

includes/form.inc, line 281

Code

function drupal_prepare_form($form_id, &$form) {
  global $user;

  $form['#type'] = 'form';

  if (!isset($form['#post'])) {
    $form['#post'] = $_POST;
    $form['#programmed'] = FALSE;
  }
  else {
    $form['#programmed'] = TRUE;
  }

  // In multi-step form scenarios, this id is used to identify
  // a unique instance of a particular form for retrieval.
  if (isset($form['#build_id'])) {
    $form['form_build_id'] = array(
      '#type' => 'hidden',
      '#value' => $form['#build_id'],
      '#id' => $form['#build_id'],
      '#name' => 'form_build_id',
    );
  }

  // If $base is set, it is used in place of $form_id when constructing validation,
  // submission, and theming functions. Useful for mapping many similar or duplicate
  // forms with different $form_ids to the same processing functions.
  if (isset($form['#base'])) {
    $base = $form['#base'];
  }

  // Add a token, based on either #token or form_id, to any form displayed to
  // authenticated users. This ensures that any submitted form was actually
  // requested previously by the user and protects against cross site request
  // forgeries.
  if (isset($form['#token'])) {
    if ($form['#token'] === FALSE || $user->uid == 0 || $form['#programmed']) {
      unset($form['#token']);
    }
    else {
      $form['form_token'] = array('#type' => 'token', '#default_value' => drupal_get_token($form['#token']));
    }
  }
  else if ($user->uid && !$form['#programmed']) {
    $form['#token'] = $form_id;
    $form['form_token'] = array(
      '#id' => form_clean_id('edit-' . $form_id . '-form-token'),
      '#type' => 'token',
      '#default_value' => drupal_get_token($form['#token']),
    );
  }


  if (isset($form_id)) {
    $form['form_id'] = array('#type' => 'hidden', '#value' => $form_id, '#id' => form_clean_id("edit-$form_id"));
  }
  if (!isset($form['#id'])) {
    $form['#id'] = form_clean_id($form_id);
  }

  $form += _element_info('form');

  if (!isset($form['#validate'])) {
    if (function_exists($form_id . '_validate')) {
      $form['#validate'] = array($form_id . '_validate' => array());
    }
    elseif (function_exists($base . '_validate')) {
      $form['#validate'] = array($base . '_validate' => array());
    }
  }

  if (!isset($form['#submit'])) {
    if (function_exists($form_id . '_submit')) {
      // We set submit here so that it can be altered.
      $form['#submit'] = array($form_id . '_submit' => array());
    }
    elseif (function_exists($base . '_submit')) {
      $form['#submit'] = array($base . '_submit' => array());
    }
  }

  foreach (module_implements('form_alter') as $module) {
    $function = $module . '_form_alter';
    $function($form_id, $form);
  }

  $form = form_builder($form_id, $form);
}