Drupal Alters and Overrides: hook_form_alter

One of the first rules most people coming into the world of Drupal learn, hopefully, is to not hack core. I certainly didn't know about this when I first started out and hacked to pieces a lovely Drupal 4.6 site which, amusingly enough, still exists today. Since then, though, I've become more accustomed to the various ways of altering and overriding things in both Drupal core and contrib "the Drupal way".

Because Drupal is built modular with a strong hook API system, it gives us a lot of power in terms of changing things through our own custom modules. You can read more about creating a custom module at http://drupal.org/developing/modules -- there is also a useful module with some good examples you can download from http://drupal.org/project/examples

I'm going to go through a few different ways you can alter and override content in my next series of blog posts. This first one will cover one of the most popular.

hook_form_alter

One of the most common hooks used to override or alter things in Drupal is hook_form_alter. Drupal is driven by forms-- administration settings forms, content creation forms, contact forms, menu forms, user registration forms, etc., that I don't think I've ever worked on a Drupal site where this hook wasn't used.

Let's say, for example, you've got yourself a View with some exposed filters. By default the submit button says "Apply", but you've been asked to change that to "Submit".

My custom module is called demo. If I take a look at the link above from api.drupal.org, it tells me the parameters my function should have:

hook_form_alter(&$form, &$form_state, $form_id)

This is how it would appear in my module:

function demo_form_alter(&$form, &$form_state, $form_id) {

}

I need to find the $form_id in order to make sure I'm altering only that specific form and not the others. I usually do this just by printing out $form_id. For Views exposed filters, they all have the same $form_id which is 'views_exposed_form'. In order to make sure I'm only targetting this specific exposed form, I also use the $form['#id'] value. You can get these values by doing a print_r($form) or dpm($form) in your module. My alter now looks like this:

/**
 * Implementation of hook_form_alter().
 */
function demo_form_alter(&$form, &$form_state, $form_id) {
  if ($form_id == 'views_exposed_form' && $form['#id'] == 'views-exposed-form-content-search-page-1') {
    $form['submit']['#value'] = t('Search');
  }
}

I can do all sorts of things with forms here. I can remove elements, rename them, add new ones. I can also add or override submit and validation functions. Here are a few examples:

/**
 * Implementation of hook_form_alter().
 */
function demo_form_alter(&$form, &$form_state, $form_id) {
  if ($form_id == 'views_exposed_form' && $form['#id'] == 'views-exposed-form-content-search-page-1') {
    // Rename the submit button
    $form['submit']['#value'] = t('Search');
  }
  if ($form_id == 'search_block_form') {
    // Add default "Search" text in the searchbox
    $form['search_block_form']['#default_value'] = t('Search');
  }
  if ($form_id == 'page_node_form') {
    // Remove the "Preview" option
    unset($form['buttons']['preview']);
    // Add my extra validation function
    $form['#validate'][] = 'demo_extra_validate';
  }
}