The Definitive Guide to Drupal 7

Modifying Forms Using Alter Hooks

The ability of themes to use alter hooks is new in Drupal 7. Templates are great for situations where you want to have a lot of control over the markup itself, but there are quite a few situations where simply using hook_form_alter() can make things a lot easier, especially if you are comfortable with Drupal’s form markup either by default, or in combination with changes you can make site-wide via theme functions. Using an alter hook is perfect for quick changes like:

  • Simple changes to form labels, descriptions, and other properties.
  • Changing the order in which the form elements print using the #weight property.
  • Wrapping a few elements in a <div> or <fieldset>.
  • Hiding or removing form elements that are not required.
  • Adding some markup to a form.

It’s also arguably easier because there are fewer steps involved in the process. You don’t need to implement hook_theme(). You also get full control over the elements. There are certain limitations to the changes you can make within theme functions, as it’s already too late in the process.

  1. hook_form_alter(): Runs for all forms.
  2. hook_form_FORM_ID_alter(): Runs for a specific form ID.

There are reasons for using hook_form_alter() over hook_form_FORM_ID_alter() all the time, but those reasons mainly apply to the tasks a module developer needs to perform. Unless you are specifically targeting more than one form to do the same thing, as shown in Listing 16–34, it’s probably best to use hook_form_FORM_ID_alter(), as shown in Listing 16–35.

Listing 16–34. Implementation of hook_form_alter() to target all or multiple forms
  1. <?php
  2. /**
  3.  * Implements hook_form_alter().
  4.  */
  5. function mytheme_form_alter(&$form, &$form_state, $form_id) {
  6. // Changes made in here affect ALL forms.
  7. if (!empty($form['title']) && $form['title']['#type'] == 'textfield') {
  8. $form['title']['#size'] = 40;
  9. }
  10. }
Listing 16–35. Implementation of hook_form_FORM_ID_alter() to target a specific form
  1. <?php
  2. /**
  3.  * Implements hook_form_FORM_ID_alter().
  4.  */
  5. function mytheme_form_contact_site_form_alter(&$form, &$form_state) {
  6. // Add a #markup element containing your note and make it display at the top.
  7. $form['note']['#markup'] = t("We'd love hear from you. Expect to hear back from us in 1-2 business days.");
  8. $form['note']['#weight'] = -1;
  9.  
  10. // Change labels for the 'mail' and 'name' elements.
  11. $form['name']['#title'] = t('Name');
  12. $form['mail']['#title'] = t('E-mail');
  13.  
  14. // Hide the subject field and give it a standard subject for value.
  15. $form['subject']['#type'] = 'hidden';
  16. $form['subject']['#value'] = t('Contact Form Submission');
  17. }

You are reading content from two chapters on Theme Development from The Definitive Guide to Drupal 7, written by Jacine Luisi and published by Apress on July 19, 2011. All rights reserved.