<?php

// $Id: form.inc,v 1.265.2.25 2009/05/26 08:18:46 goba Exp $

/**

 * @defgroup forms Form builder functions

 * @{

 * Functions that build an abstract representation of a HTML form.

 *

 * All modules should declare their form builder functions to be in this

 * group and each builder function should reference its validate and submit

 * functions using \@see. Conversely, validate and submit functions should

 * reference the form builder function using \@see. For examples, of this see

 * system_modules_uninstall() or user_pass(), the latter of which has the

 * following in its doxygen documentation:

 *

 * \@ingroup forms

 * \@see user_pass_validate().

 * \@see user_pass_submit().

 *

 * @} End of "defgroup forms".

 */

/**

 * @defgroup form_api Form generation

 * @{

 * Functions to enable the processing and display of HTML forms.

 *

 * Drupal uses these functions to achieve consistency in its form processing and

 * presentation, while simplifying code and reducing the amount of HTML that

 * must be explicitly generated by modules.

 *

 * The drupal_get_form() function handles retrieving, processing, and

 * displaying a rendered HTML form for modules automatically. For example:

 *

 * @code

 * // Display the user registration form.

 * $output = drupal_get_form('user_register');

 * @endcode

 *

 * Forms can also be built and submitted programmatically without any user input

 * using the drupal_execute() function.

 *

 * For information on the format of the structured arrays used to define forms,

 * and more detailed explanations of the Form API workflow, see the

 * @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html reference @endlink

 * and the @link http://api.drupal.org/api/file/developer/topics/forms_api.html quickstart guide. @endlink

 */

/**

 * 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 passesed

 * on for processing, after and rendered for display if necessary.

 *

 * @param $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().

 * @param ...

 *   Any additional arguments are passed on to the functions called by

 *   drupal_get_form(), including the unique form constructor function.

 *   For example, the node_edit form requires that a node object be passed

 *   in here when it is called.

 * @return

 *   The rendered form.

 */

function drupal_get_form($form_id) {

  $form_state = array('storage' => NULL, 'submitted' => FALSE);

  $args = func_get_args();

  $cacheable = FALSE;

  if (isset($_SESSION['batch_form_state'])) {

    // We've been redirected here after a batch processing : the form has

    // already been processed, so we grab the post-process $form_state value

    // and move on to form display. See _batch_finished() function.

    $form_state = $_SESSION['batch_form_state'];

    unset($_SESSION['batch_form_state']);

  }

  else {

    // If the incoming $_POST contains a form_build_id, we'll check the

    // cache for a copy of the form in question. If it's there, we don't

    // have to rebuild the form to proceed. In addition, if there is stored

    // form_state data from a previous step, we'll retrieve it so it can

    // be passed on to the form processing code.

    if (isset($_POST['form_id']) && $_POST['form_id'] == $form_id && !empty($_POST['form_build_id'])) {

      $form = form_get_cache($_POST['form_build_id'], $form_state);

    }

    // If the previous bit of code didn't result in a populated $form

    // object, we're hitting the form for the first time and we need

    // to build it from scratch.

    if (!isset($form)) {

      $form_state['post'] = $_POST;

      // Use a copy of the function's arguments for manipulation

      $args_temp = $args;

      $args_temp[0] = &$form_state;

      array_unshift($args_temp, $form_id);

      $form = call_user_func_array('drupal_retrieve_form', $args_temp);

      $form_build_id = 'form-'. md5(uniqid(mt_rand(), true));

      $form['#build_id'] = $form_build_id;

      drupal_prepare_form($form_id, $form, $form_state);

      // Store a copy of the unprocessed form for caching and indicate that it

      // is cacheable if #cache will be set.

      $original_form = $form;

      $cacheable = TRUE;

      unset($form_state['post']);

    }

    $form['#post'] = $_POST;

    // Now that we know we have a form, we'll process it (validating,

    // submitting, and handling the results returned by its submission

    // handlers. Submit handlers accumulate data in the form_state by

    // altering the $form_state variable, which is passed into them by

    // reference.

    drupal_process_form($form_id, $form, $form_state);

    if ($cacheable && !empty($form['#cache'])) {

      // Caching is done past drupal_process_form so #process callbacks can

      // set #cache. By not sending the form state, we avoid storing

      // $form_state['storage'].

      form_set_cache($form_build_id, $original_form, NULL);

    }

  }

  // Most simple, single-step forms will be finished by this point --

  // drupal_process_form() usually redirects to another page (or to

  // a 'fresh' copy of the form) once processing is complete. If one

  // of the form's handlers has set $form_state['redirect'] to FALSE,

  // the form will simply be re-rendered with the values still in its

  // fields.

  //

  // If $form_state['storage'] or $form_state['rebuild'] have been

  // set by any submit or validate handlers, however, we know that

  // we're in a complex multi-part process of some sort and the form's

  // workflow is NOT complete. We need to construct a fresh copy of

  // the form, passing in the latest $form_state in addition to any

  // other variables passed into drupal_get_form().

  if (!empty($form_state['rebuild']) || !empty($form_state['storage'])) {

    $form = drupal_rebuild_form($form_id, $form_state, $args);

  }

  // If we haven't redirected to a new location by now, we want to

  // render whatever form array is currently in hand.

  return drupal_render_form($form_id, $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.

 *

 * @param $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().

 * @param $form_state

 *   A keyed array containing the current state of the form. Most

 *   important is the $form_state['storage'] collection.

 * @param $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.

 * @param $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

 *   The newly built form.

 */

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-'. md5(mt_rand());

  }

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

}

/**

 * Store a form in the cache.

 */

function form_set_cache($form_build_id, $form, $form_state) {

  global $user;

  // 6 hours cache life time for forms should be plenty.

  $expire = 21600;

  if ($user->uid) {

    $form['#cache_token'] = drupal_get_token();

  }

  cache_set('form_'. $form_build_id, $form, 'cache_form', time() + $expire);

  if (!empty($form_state['storage'])) {

    cache_set('storage_'. $form_build_id, $form_state['storage'], 'cache_form', time() + $expire);

  }

}

/**

 * Fetch a form from cache.

 */

function form_get_cache($form_build_id, &$form_state) {

  global $user;

  if ($cached = cache_get('form_'. $form_build_id, 'cache_form')) {

    $form = $cached->data;

    if ((isset($form['#cache_token']) && drupal_valid_token($form['#cache_token'])) || (!isset($form['#cache_token']) && !$user->uid)) {

      if ($cached = cache_get('storage_'. $form_build_id, 'cache_form')) {

        $form_state['storage'] = $cached->data;

      }

      return $form;

    }

  }

}

/**

 * Retrieves a form using a form_id, populates it with $form_state['values'],

 * processes it, and returns any validation errors encountered. This

 * function is the programmatic counterpart to drupal_get_form().

 *

 * @param $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().

 * @param $form_state

 *   A keyed array containing the current state of the form. Most

 *   important is the $form_state['values'] collection, a tree of data

 *   used to simulate the incoming $_POST information from a user's

 *   form submission.

 * @param ...

 *   Any additional arguments are passed on to the functions called by

 *   drupal_execute(), including the unique form constructor function.

 *   For example, the node_edit form requires that a node object be passed

 *   in here when it is called.

 * For example:

 *

 * // register a new user

 * $form_state = array();

 * $form_state['values']['name'] = 'robo-user';

 * $form_state['values']['mail'] = 'robouser@example.com';

 * $form_state['values']['pass'] = 'password';

 * $form_state['values']['op'] = t('Create new account');

 * drupal_execute('user_register', $form_state);

 *

 * // Create a new node

 * $form_state = array();

 * module_load_include('inc', 'node', 'node.pages');

 * $node = array('type' => 'story');

 * $form_state['values']['title'] = 'My node';

 * $form_state['values']['body'] = 'This is the body text!';

 * $form_state['values']['name'] = 'robo-user';

 * $form_state['values']['op'] = t('Save');

 * drupal_execute('story_node_form', $form_state, (object)$node);

 */

function drupal_execute($form_id, &$form_state) {

  $args = func_get_args();

  $form = call_user_func_array('drupal_retrieve_form', $args);

  $form['#post'] = $form_state['values'];

  drupal_prepare_form($form_id, $form, $form_state);

  drupal_process_form($form_id, $form, $form_state);

}

/**

 * Retrieves the structured array that defines a given form.

 *

 * @param $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.

 * @param $form_state

 *   A keyed array containing the current state of the form.

 * @param ...

 *   Any additional arguments needed by the unique form constructor

 *   function. Generally, these are any arguments passed into the

 *   drupal_get_form() or drupal_execute() functions after the first

 *   argument. If a module implements hook_forms(), it can examine

 *   these additional arguments and conditionally return different

 *   builder functions as well.

 */

function drupal_retrieve_form($form_id, &$form_state) {

  static $forms;

  // We save two copies of the incoming arguments: one for modules to use

  // when mapping form ids to constructor functions, and another to pass to

  // the constructor function itself. We shift out the first argument -- the

  // $form_id itself -- from the list to pass into the constructor function,

  // since it's already known.

  $args = func_get_args();

  $saved_args = $args;

  array_shift($args);

  if (isset($form_state)) {

    array_shift($args);

  }

  // We first check to see if there's a function named after the $form_id.

  // If there is, we simply pass the arguments on to it to get the form.

  if (!function_exists($form_id)) {

    // In cases where many form_ids need to share a central constructor function,

    // such as the node editing form, modules can implement hook_forms(). It

    // maps one or more form_ids to the correct constructor functions.

    //

    // We cache the results of that hook to save time, but that only works

    // for modules that know all their form_ids in advance. (A module that

    // adds a small 'rate this comment' form to each comment in a list

    // would need a unique form_id for each one, for example.)

    //

    // So, we call the hook if $forms isn't yet populated, OR if it doesn't

    // yet have an entry for the requested form_id.

    if (!isset($forms) || !isset($forms[$form_id])) {

      $forms = module_invoke_all('forms', $form_id, $args);

    }

    $form_definition = $forms[$form_id];

    if (isset($form_definition['callback arguments'])) {

      $args = array_merge($form_definition['callback arguments'], $args);

    }

    if (isset($form_definition['callback'])) {

      $callback = $form_definition['callback'];

    }

  }

  array_unshift($args, NULL);

  $args[0] = &$form_state;

  // If $callback was returned by a hook_forms() implementation, call it.

  // Otherwise, call the function named after the form id.

  $form = call_user_func_array(isset($callback) ? $callback : $form_id, $args);

  // We store the original function arguments, rather than the final $arg

  // value, so that form_alter functions can see what was originally

  // passed to drupal_retrieve_form(). This allows the contents of #parameters

  // to be saved and passed in at a later date to recreate the form.

  $form['#parameters'] = $saved_args;

  return $form;

}

/**

 * This function is the heart of form API. The form gets built, validated and in

 * appropriate cases, submitted.

 *

 * @param $form_id

 *   The unique string identifying the current form.

 * @param $form

 *   An associative array containing the structure of the form.

 * @param $form_state

 *   A keyed array containing the current state of the form. This

 *   includes the current persistent storage data for the form, and

 *   any data passed along by earlier steps when displaying a

 *   multi-step form. Additional information, like the sanitized $_POST

 *   data, is also accumulated here.

 */

function drupal_process_form($form_id, &$form, &$form_state) {

  $form_state['values'] = array();

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

  // Only process the form if it is programmed or the form_id coming

  // from the POST data is set and matches the current form_id.

  if ((!empty($form['#programmed'])) || (!empty($form['#post']) && (isset($form['#post']['form_id']) && ($form['#post']['form_id'] == $form_id)))) {

    drupal_validate_form($form_id, $form, $form_state);

    // form_clean_id() maintains a cache of element IDs it has seen,

    // so it can prevent duplicates. We want to be sure we reset that

    // cache when a form is processed, so scenerios that result in

    // the form being built behind the scenes and again for the

    // browser don't increment all the element IDs needlessly.

    form_clean_id(NULL, TRUE);

    if ((!empty($form_state['submitted'])) && !form_get_errors() && empty($form_state['rebuild'])) {

      $form_state['redirect'] = NULL;

      form_execute_handlers('submit', $form, $form_state);

      // We'll clear out the cached copies of the form and its stored data

      // here, as we've finished with them. The in-memory copies are still

      // here, though.

      if (variable_get('cache', CACHE_DISABLED) == CACHE_DISABLED && !empty($form_state['values']['form_build_id'])) {

        cache_clear_all('form_'. $form_state['values']['form_build_id'], 'cache_form');

        cache_clear_all('storage_'. $form_state['values']['form_build_id'], 'cache_form');

      }

      // If batches were set in the submit handlers, we process them now,

      // possibly ending execution. We make sure we do not react to the batch

      // that is already being processed (if a batch operation performs a

      // drupal_execute).

      if ($batch =& batch_get() && !isset($batch['current_set'])) {

        // The batch uses its own copies of $form and $form_state for

        // late execution of submit handers and post-batch redirection.

        $batch['form'] = $form;

        $batch['form_state'] = $form_state;

        $batch['progressive'] = !$form['#programmed'];

        batch_process();

        // Execution continues only for programmatic forms.

        // For 'regular' forms, we get redirected to the batch processing

        // page. Form redirection will be handled in _batch_finished(),

        // after the batch is processed.

      }

      // If no submit handlers have populated the $form_state['storage']

      // bundle, and the $form_state['rebuild'] flag has not been set,

      // we're finished and should redirect to a new destination page

      // if one has been set (and a fresh, unpopulated copy of the form

      // if one hasn't). If the form was called by drupal_execute(),

      // however, we'll skip this and let the calling function examine

      // the resulting $form_state bundle itself.

      if (!$form['#programmed'] && empty($form_state['rebuild']) && empty($form_state['storage'])) {

        drupal_redirect_form($form, $form_state['redirect']);

      }

    }