What is a hook?

In Drupal terms, a hook is the way modules communicate with Drupal core elements, as well as with other modules. Using hooks can add extra functionality or change how existing modules work - without changing the existing code. Hooks can be used to add new pages, create database definitions, as well as manage and show content. As Drupal developers, they're powerful allies to have at our disposal.

A hook has two parts - a definition and an implementation. The implementation contains the code you want to run and is contained in your module. The definition is provided by another module (or core) and specifies which arguments are passed to the implementation.

How to find available hooks

Some examples of hooks are:

hook_form_alter

Changes how a form works before it is rendered.

hook_help

Provides online help for the module.

hook_menu

Defines an accessable url with a menu item, as well as a callback to the page display code.

These are all hooks provided by core (provided by Drupal as default). Other core hooks are listed on the Drupal API hooks page. External modules also have the power to define hooks - ctools, views and rules are examples of modules which do this.

Thoughtfully coded modules will have an .api.php, which documents the available hooks for that module. It explains the available hooks, its parameters and what is needed to be returned. An example usage is also shown.

Implementing a hook

The easiest way to implement a hook is to copy the example from the .api.php file into your module, then rename the function by replacing the starting 'HOOK' with the name of your module. For example, if your module is named 'mymodule' and you're using a form_alter, hook_form_alter becomes mymodule_form_alter.

Then write the desired functionality, returning output how the hook requires. Hook return values might be set in passed parameters rather than a return statement in the function.

A couple of examples

We'll add some functionality to a module called mymodule.

First the module is created. mymodule.info contains the following:

name = My Module
description = Tutorial module 
core = 7.x package = Tutorial

And mymodule.module is an empty php file.

• See Enhanced Views and rules in Drupal 7 for details on where to put these files.

Online help

The first thing we'll add is some online help. So we go to the api page for hook_help() and copy the definition into the module file, remebering to change the intial hook to our module name, and creating an empty code block. A comment block is also added.

/*  Implements hook_help().  */
function mymodule_help($path, $arg) { 

}

Now we need to add the definition. For hook_help, the path is passed. This is used to add help to various pages depending on the module. To create a general help screen, we need to check for admin/help followed by the module name. We'll use a switch statement to do that.

switch ($path) {
  case 'admin/help#mymodule': break;
}

Next, in the switch statement, replace the break with a return statement with the text to display on the help screen. You could load the text from a file or create it some other way (possibly using another hook defined by your module), but we'll just return a short string.

      return "This is my help text";

The complete function should look like this:

/* Implements hook_help(). */
function mymodule_help($path, $arg) {
  switch ($path) {
    case 'admin/help#mymodule': return "This is my help text";
  }
}

Now, after enabling the module, you should get a help button on the module screen. Clicking that shows the text returned by the implemented hook. Also, if you navigate to admin/help, the module should show up in the list of help topics. So, for 6 lines of code and 3 lines of commenting, a help page has been created as well as two ways to access the page!

Changing a Form

A common thing to do is to change an existing form to better fit a specific process.To do this we need to alter a form, so we go to hook_form_alter.

As a demonstration, we will change the login form, but any form can be chage in the same way.

Copying the definition as before gives us a new function:

/* Implements hook_form_alter(). */
function mymodule_form_alter(&$form, &$form_state, $form_id) {

}

We need to check $form_id for the correct form. As with hook_help, a switch statement will be used.

switch($form_id) {
  case 'user_login': // the login page
  case 'user_login_block': // the login block
  break;   
}

hook_form_alter required that the changes are to be set to the passed in $form variable. For our example, a change to the 'Username' title will be changed.

$form['name']['#title'] = t('Account name');

• The Devel module was installed and dpm() used to get the correct item to change (permissions were also set so anonymous users can see the output).

The complete function now looks like this:

/* Implements hook_form_alter(). */
function mymodule_form_alter(&$form, &$form_state, $form_id) {
  switch($form_id) {
    case 'user_login': // the login page
    case 'user_login_block': // the login block
    $form['name']['#title'] = t('Account name');
      break;   
  }
}

Now, with just a few lines of code, the output has been changed. Any of the Form API items can be changed, and extra form elements can be added.

Don't forget that modules can also define modules, which means a lot of functionality can be changed with relatively little code!

You can download a .zip of the complete files we've created in this tutorial using the link below. Also, feel free to tweet us @CurveAgency if you have any questions about the above.

We'll see you again in a short while for part two: Creating your own hooks!