A Very Introduction to Drupal's hook_form_alter()

Disclaimer: This post is about a very basic example of a drupal module that works in both Drupal 6 and Drupal 7. The purpose is to present a general idea of how to write custom drupal modules, use and find drupal hooks, and to show 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.

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 in you drupal's sites/all/modules/ folder named 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.

2. Creating a hook

Hooks in Drupal are just ways of modifying the website page's results.
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 a drupal api page that describes the hook.

New let's 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's into all of Drupal's forms.

3. Using 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 php function we'll be using is dsm();, which sets a drupal message with the value of the given parameter.

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 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"){ dsm($form); } }

On saving the module and refreshing the page, this will provide you with a pretty output of the entire $form array.
Now 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 and refresh your page 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