A Very Introduction to Drupal’s hook_form_alter()

This post provides some very basic example of a drupal module that works in both Drupal 6 and Drupal 7. The purpose is to:

• present an idea for how to write custom drupal modules
• use and find drupal hooks
• and how to take advantage of drupal’s Devel module

This tutorial assumes you know how to create and upload files to your server using FTP.

Step 1. Creating a module

First, let’s make a module that only exist in the module system. Follow these steps exactly.

1. Download and install the devel modules on your drupal site.
2. Create/Upload a new folder to your Drupal site at sites/all/modules/custom_example
3. Create/Upload two new files in that folder: the first named custom_example.info, and the second named custom_example.module
4. Take a moment to notice that the module’s folder name and file names are the same.

Now edit the custom_example.info file, and make its contents the following:

name = Custom Example
description = Just a simple example module
version = 0.1
core = 6.x
package = Alpha Custom Modules

Save/Upload that file.
Drupal 7 note: If you’re doing this is Drupal 7, change the ‘core’ number to 7.x

Next, edit the custom_example.module file and make its contents the following:

<?php

Thats it! Save/Upload that file and then visit your site’s module page.

On your site’s module page, you should now be able to see and enable the module. Do so.

Step 2. Using a hook

Hooks in Drupal are functions we can write that allow us to modify the website. Let’s create one in our new module.

The hook we are going to use is the all-fabulous hook_form_alter. That link will take you to the official Drupal api page where the hook is described.

Now edit the custom_example.module, and make its contents the following:

<?php
       
/*
 * Implementation of hook_form_alter()
 */
function custom_example_form_alter(&$form, &$form_state, $form_id){
   
}

Now here is the important part about using a hook.
Copy the hook function from Drupal’s API page, and replace the word hook with your module’s name. Your module is now “hook”ed into all of forms that appear on your Drupal website.

Step 3. Use the Devel module to figure out what to do next

Now that we’re hooked into all Drupal forms, let’s use a Devel module function to target a specific form, and figure out what the form looks like. The Devel module provides a helpful php function we’ll be using, dsm(). The dsm() function will display a message on the page that shows us value of any PHP variable we pass into it.

Edit the module file again to make its content the following:

<?php
       
/*
 * Implementation of hook_form_alter()
 */
function custom_example_form_alter(&$form, &$form_state, $form_id){
  dsm($form_id);
}

Using the dsm() function we are going to output the ID of every form a page loads. You can prove this by visiting a Page node creation form. Visit http://example.com/node/add/page on your website.

You should see a list of form ids at the top of the page.

Now let’s use one of those listed form_ids to target this form.

Edit the module file again to change its contents to the following:

<?php
       
/*
 * Implementation of hook_form_alter()
 */
function custom_example_form_alter(&$form, &$form_state, $form_id){
  // target a single form
  if($form_id == "page_node_form"){
    dsm($form);
  }
}

On saving the module and refreshing the page, this will provide you with a pretty output of the entire $form array.

Next, let’s modify the $form array to change the label for the form’s title field.

4. Modifying the form

Edit the module file again to make its content the following:

<?php
       
/*
 * Implementation of hook_form_alter()
 */
function custom_example_form_alter(&$form, &$form_state, $form_id){
  // target a single form
  if($form_id == "page_node_form"){
    $form['title']['#title'] = t('New Form Title');
  }
}

Save that module, refresh your the edit form, and you’ll see that the Title: label has been changed to New Form Title.

And there you have it. Your first module that uses hook_form_alter() and the devel module.

For more information on Drupal’s Form Api, check out the following references:

• Drupal 6 Form Api Reference
• Drupal 7 Form Api Reference