function hook_form_alter

7 system.api.php hook_form_alter(&$form, &$form_state, $form_id)
4.7 core.php hook_form_alter($form_id, &$form)
5 core.php hook_form_alter($form_id, &$form)
6 core.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()

hook_form_FORM_ID_alter()

forms_api_reference.html

Related topics

Hooks
Allow modules to interact with the Drupal core.
42 functions implement hook_form_alter()

Note: this list is generated by pattern matching, so it may include some functions that are not actually implementations of this hook.

aggregator_form_aggregator_admin_form_alter in modules/aggregator/aggregator.processor.inc
Implements hook_form_aggregator_admin_form_alter().
block_form_form_test_alter_form_alter in modules/simpletest/tests/form_test.module
Implements hook_form_FORM_ID_alter() on behalf of block.module.
block_form_user_profile_form_alter in modules/block/block.module
Implements hook_form_FORM_ID_alter() for user_profile_form().
book_form_node_form_alter in modules/book/book.module
Implements hook_form_BASE_FORM_ID_alter() for node_form().
comment_form_node_form_alter in modules/comment/comment.module
Implements hook_form_BASE_FORM_ID_alter().

... See full list

File

modules/system/system.api.php, line 1661
Hooks provided by Drupal core and the System module.

Code

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

Posted by mpapet on

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);
}

Posted by seanr on

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:

<?php
function 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...):

<?php
function 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().

Posted by johnlaine on

Thanks!

Posted by esod on

If for some reason devel is not installed:

<?php
function 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.

Posted by sunchaser on
function <themename>_form_alter(&$form, &$form_state, $form_id) {
    drupal_set_message("This is the form id : $form_id");
}

just doesn't fire in my node/add form

any thoughts ?

Posted by chellman on

If the theme you're editing is not active on the page of interest, this won't work. If, for example, is the default theme, but you're using Seven as your admin theme (and your admin theme is used for content editing -- checking the settings at the bottom of the Appearance page), this form_alter won't be called on node/add or node/*/edit pages.

If you're sure you have the themes set correctly, you should try clearing the Drupal cache to make sure the form_alter is being picked up. This is on Admin > Configuration > Development > Performance.

Fix those two things, and you should be in business.

(I posted this in the forum, then remembered I saw it here first, so I'm reposting it here).

Posted by yaworsk on

nope, it doesn't look like hook_form_alter fires on node add forms. I'm calling it from template.php and it works on other forms on my site, just not node add forms....

Posted by subhojit777 on

Suppose you have created a custom module and you want to create hook_form_alter for that module. Here are some easy steps to implement and test the working of hook_form_alter.

Suppose you want to add a new field in your in your comments form , say a checkbox. You can do this using the hook_form_alter of your custom module. Before doing this make sure that writing comment is enabled in your content type. hook_form_alter takes three parameters $form, $form_date and $form_id. If you just want to see the working of form_alter then you need to worry about only $form_id.

Just write this piece of code in your mymodule.module file:

function mymodule_form_alter(&$form, $form_state, $form_id)  {
  switch ($form_id)  {
  case 'comment_form_id':
  $form['your_comment_form_name'] = array (
    '#type' => 'checkbox',
    '#title' => t ('Subscribe to replies to this comment'),
  );
  break;
  }
  }

The name of comment form is of your choice.

If you are wondering what $form_id would in your case, then add this piece of code before switch($form_id):
drupal_set_message($form_id);

You will see all the form_id's of your page after refreshing the page. Just copy the form_id of your comments form and paste it in place of comment_form_id.

Enable your module and view your comments form. You will see the checkbox in there.
Even if you dont see the checkbox in your comments form, try clearing the cache. If you have followed the above steps correctly, you will surely see the checkbox in comments form.

I hope I have made myself clear :)

Thank you Mukesh for your guidance

Posted by schlicki.heissgroup on

Hey guys..

I searched the internet for hours and didnt find a solution.
I want to add form states in hook_form_alter. Therefore I tried the following code:

<?php
  $form['field_dependent']['#states'] = array(
    'visible' => array(
      ':input[name="field_dependee"]' => array('empty' => false),
    ),
  );
?>

All fields are textfields and I minimized my modules code to exactly this and created a node type with the fields available.. The result is: nothing happens.
What am I doing wrong? Any ideas? or am I on a completely wrong way to achieve the goal of putting dependencies into forms that already exist?

Thanks in advance,
Johannes

Posted by schlicki.heissgroup on

Ok

Now i should have waited with commenting ;)

As a last attempt I tried:

<?php
  $form['field_dependent']['#states'] = array(
    'visible' => array(
      ':input[name="field_dependee[und][0][value]"]' => array('empty' => false),
    ),
  );
?>

.. and it worked. I dont get the logic behind that, but it works ;)

Posted by Vincent.R on

It seems that this function can only be called in the mymodule.module file,elsewhere like mymodule.admin.inc give no response when you use dsm($form_id); inside this hook function