hook_forms
- Versions
- 5
hook_forms()- 6 – 7
hook_forms($form_id, $args)
Map form_ids to builder functions.
This hook allows modules to build multiple forms from a single form "factory" function but each form will have a different form id for submission, validation, theming or alteration by other modules.
The callback arguments will be passed as parameters to the function. Callers of drupal_get_form() are also able to pass in parameters. These will be appended after those specified by hook_forms().
See node_forms() for an actual example of how multiple forms share a common building function.
Parameters
$form_id The unique string identifying the desired form.
$args An array containing the original arguments provided to drupal_get_form().
Return value
An array keyed by form id with callbacks and optional, callback arguments.
Related topics
Code
developer/hooks/core.php, line 794
<?php
function hook_forms($form_id, $args) {
$forms['mymodule_first_form'] = array(
'callback' => 'mymodule_form_builder',
'callback arguments' => array('some parameter'),
);
$forms['mymodule_second_form'] = array(
'callback' => 'mymodule_form_builder',
);
return $forms;
}
?>
Clarify purpose of the arguments.
The arguments $form_id and $args really don't make sense in this context, and they are not used in the node_forms implementation.
Is this a legacy thing? Then this should be explained. Or is it just a documentation mistake?
Thanks
donquixote
EDIT:
Ok probably I am wrong and the arguments do have a purpose. But still, that purpose is not obvious from the description. In one situation you want information about all forms, in another you want information about just one form.. why is that both the same hook?
http://drupal.org/node/405832
http://drupal.org/node/144132#hook-forms
EDIT II:
Ok, here is the explanation.
http://api.drupal.org/api/function/drupal_retrieve_form
<?php// 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);
}
?>
This information should go in this documentation page, I think.