drupal_retrieve_form

• Drupal 5
• Drupal 6
• Drupal 7

• View documentation
• List references

Definition

drupal_retrieve_form($form_id)
includes/form.inc, line 178

Description

Retrieves the structured array that defines a given form.

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.

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

Related topics

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

Code

<?php
function drupal_retrieve_form($form_id) {
  static $forms;

  // We save two copies of the incoming arguments: one for modules to use
  // when mapping form ids to builder functions, and another to pass to
  // the builder function itself. We shift out the first argument -- the
  // $form_id itself -- from the list to pass into the builder function,
  // since it's already known.
  $args = func_get_args();
  $saved_args = $args;
  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 builder function,
    // such as the node editing form, modules can implement hook_forms(). It
    // maps one or more form_ids to the correct builder 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', $saved_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'];
    }
  }
  // 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;
}
?>