| 5 core.php | hook_form_alter($form_id, &$form) |
| 6 core.php | hook_form_alter(&$form, &$form_state, $form_id) |
| 7 system.api.php | hook_form_alter(&$form, &$form_state, $form_id) |
| 8 system.api.php | hook_form_alter(&$form, &$form_state, $form_id) |
Perform alterations before a form is rendered.
One popular use of this hook is to add form elements to the node form. When altering a node form, the node object can be accessed at $form['#node'].
In addition to hook_form_alter(), which is called for all forms, there are two more specific form hooks available. The first, hook_form_BASE_FORM_ID_alter(), allows targeting of a form/forms via a base form (if one exists). The second, hook_form_FORM_ID_alter(), can be used to target a specific form directly.
The call order is as follows: all existing form alter functions are called for module A, then all for module B, etc., followed by all for any base theme(s), and finally for the theme itself. The module order is determined by system weight, then by module name.
Within each module, form alter hooks are called in the following order: first, hook_form_alter(); second, hook_form_BASE_FORM_ID_alter(); third, hook_form_FORM_ID_alter(). So, for each module, the more general hooks are called first followed by the more specific.
Parameters
$form: Nested array of form elements that comprise the form.
$form_state: A keyed array containing the current state of the form. The arguments that drupal_get_form() was originally called with are available in the array $form_state['build_info']['args'].
$form_id: String representing the name of the form itself. Typically this is the name of the function that generated the form.
See also
hook_form_BASE_FORM_ID_alter()
Related topics
File
- modules/
system/ system.api.php, line 1616 - Hooks provided by Drupal core and the System module.
Code
<?php
function hook_form_alter(&$form, &$form_state, $form_id) {
if (isset($form['type']) && $form['type']['#value'] . '_node_settings' == $form_id) {
$form['workflow']['upload_' . $form['type']['#value']] = array(
'#type' => 'radios',
'#title' => t('Attachments'),
'#default_value' => variable_get('upload_' . $form['type']['#value'], 1),
'#options' => array(t('Disabled'), t('Enabled')),
);
}
}
?>
Comments
D7 Newbie Notes
To modify a form, check $form['#id'] for the name of the form.
It wasn't obvious to me, but you are only supposed to modify $form.
A way to discover the name of forms is to add this line to your hook_form_alter on your dev site
hook_form_alter{
watchdog('cg_volunteer', 'cg form_alter has run %formly', array('%formly' => $form['#id']), WATCHDOG_NOTICE, $link = NULL);
}
The best way to do that is
The best way to do that is with drupal_set_message, or even better with the devel module's dsm() function. Then you can do handy stuff like this:
<?phpfunction example_form_alter(&$form, &$form_state, $form_id) {
dsm($form_id); // print form ID to messages
dsm($form); // pretty print array using Krumo to messages
}
?>
That way you get it right there in the page you're looking at without having to go dig around in the watchdog. Here's the equivalent without devel (though why you wouldn't want to use devel I don't know...):
<?phpfunction example_form_alter(&$form, &$form_state, $form_id) {
drupal_set_message($form_id); // print form ID to messages
drupal_set_message(print_r($form, TRUE)); // print array to messages
}
?>
One obvious advantage of using devel's dsm() function is you don't even have to know wether the variable is a string, array, or object - devel takes care of all that for you so you don't have to use print_r().
hooks can be called in template.php in D7
If for some reason devel is not installed:
<?phpfunction mytheme_form_alter(&$form, &$form_state, $form_id) {
$print = '<pre>' . print_r($form, TRUE) . '</pre>';
if (module_exists('devel')) {
dsm($form_id); // print form ID to messages
}
else {
drupal_set_message($form_id); // print form ID to messages
}
if (module_exists('devel')) {
dsm($form); // pretty print array using Krumo to messages
}
else {
drupal_set_message($print); // print array to messages
}
}
?>
Wrapping
print_r($form, TRUE)with<pre>tags returns the variable data in a easier to read format, although Krumo is better.