API@RTK0.NET

1. drupal
   1. 5 core.php
   2. 6 core.php
   3. 7

Map form_ids to form builder functions.

By default, when drupal_get_form() is called, the system will look for a function with the same name as the form ID, and use that function to build the form. This hook allows you to override that behavior in two ways.

First, you can use this hook to tell the form system to use a different function to build certain forms in your module; this is often used to define a form "factory" function that is used to build several similar forms. In this case, your hook implementation will likely ignore all of the input arguments. See node_forms() for an example of this.

Second, you could use this hook to define how to build a form with a dynamically-generated form ID. In this case, you would need to verify that the $form_id input matched your module's format for dynamically-generated form IDs, and if so, act appropriately.

Parameters

$form_id The unique string identifying the desired form.

$args An array containing the original arguments provided to drupal_get_form() or drupal_form_submit(). These are always passed to the form builder and do not have to be specified manually in 'callback arguments'.

Return value

An associative array whose keys define form_ids and whose values are an associative array defining the following keys:

• callback: The name of the form builder function to invoke.
• callback arguments: (optional) Additional arguments to pass to the function defined in 'callback', which are prepended to $args.
• wrapper_callback: (optional) The name of a form builder function to invoke before the form builder defined in 'callback' is invoked. This wrapper callback may prepopulate the $form array with form elements, which will then be already contained in the $form that is passed on to the form builder defined in 'callback'. For example, a wrapper callback could setup wizard-alike form buttons that are the same for a variety of forms that belong to the wizard, which all share the same wrapper callback.

Related topics

Hooks

Allow modules to interact with the Drupal core.

Code

drupal/modules/system/system.api.php, line 1689

<?php
function hook_forms($form_id, $args) {
  // Simply reroute the (non-existing) $form_id 'mymodule_first_form' to
  // 'mymodule_main_form'.
  $forms['mymodule_first_form'] = array(
    'callback' => 'mymodule_main_form',
  );

  // Reroute the $form_id and prepend an additional argument that gets passed to
  // the 'mymodule_main_form' form builder function.
  $forms['mymodule_second_form'] = array(
    'callback' => 'mymodule_main_form', 
    'callback arguments' => array('some parameter'),
  );

  // Reroute the $form_id, but invoke the form builder function
  // 'mymodule_main_form_wrapper' first, so we can prepopulate the $form array
  // that is passed to the actual form builder 'mymodule_main_form'.
  $forms['mymodule_wrapped_form'] = array(
    'callback' => 'mymodule_main_form', 
    'wrapper_callback' => 'mymodule_main_form_wrapper',
  );

  return $forms;
}
?>