In part one of our Drupal hooks tutorial, we took you through how to use hooks. We also briefly mentioned that modules can create their own hooks so here we're going to take you through that process, too!

Defining a hook

First a hook is defined. This consists of the name of the hook, along with any parameters that are passed and what is returned. Drupal does not actually require this, but it's best practice to put them in an .api.php file for documentation.

Like all functions in Drupal, the hook's name needs to be unique. The design pattern used to create a hook is to use the defining module name in the hook followed by the actual hook name. This is why most hooks look like hook_MODULE_NAME_HOOK_NAME().

Implementing a hook

Once the hook has been defined, the defining module needs to call the hook in all of the modules that implement it. There are a few ways to do this, but the simplest is to use module_invoke_all(). This goes through all the modules that implement the hook and places the returned values in an array.

An example

I stated in Using Hooks that the help text can be created by another hook, so let's do that!

Defining

So first let's define the hook.

In mymodule.api.php we create an example hook implementation along with a comment block describing what the hook does:

<?php 
/**
 * Hook to add output to mymodule help screen.
 *  
 * @return string  
 */

function hook_mymodule_help() {   
  return 'Some text'; // The text to add to the help screen.
}

No parameters are to be passed, but they can be defined here if they are needed - just like in hook_help.

Invoking

The hook needs to be invoked, so I'll change the return value of mymodule_help so that additional text can be easily added.

$ret = "This is my help text";

return $ret;

Now we add the hook invocation. The parameter to add to module_invoke_all is the name of the hook, with the preceding 'hook_' removed.

$extra = module_invoke_all('mymodule_help');

And a lovely bit of theming to output the array as a list...

$ret .= theme_item_list(
  array('items' => $extra, 
        'title' => '', 
        'type' => 'ul', 
        'attributes' => array(),
       )
);

The complete function!

/**  
 * Implements hook_help().  
 */ 

function mymodule_help($path, $arg) {
  switch ($path) {
    case 'admin/help#mymodule': 
      $ret = "This is my help text";
      $extra = module_invoke_all('mymodule_help');
      $ret .= theme_item_list(
        array('items' => $extra, 
              'title' => '', 
              'type' => 'ul', 
              'attributes' => array(),
        )
      );
      return $ret;   
  }
}    

Of course, this will not change the output on the help screen as no modules implement the new hook.

Implementing

A moodule can implement a hook defined by itself, so that will be added as a test.

/**
 * Implements hook_mymodule_help().
 */ 

function mymodule_mymodule_help() {   return 'Additional text from mymodule'; }

Now there is an unordered list with one item on the help screen.

Another Module?

We'll create a new module (myothermodule) that only implements hook_mymodule_help().

As the code will be almost identical, I'll just list it with the differences highlighted.

myothermodule.info:

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

myothermodule.module:

<?php
/**  
 * Implements hook_mymodule_help().
 */ 

function myothermodule_mymodule_help(); {
  return 'Additional text from myotherrmodule'; }

In summary

We hope you've found this tutorial useful, and if you have any queries or questions on anything Drupal related then get in touch. We're always happy to help out.

Tweet us <a href="http://twitter.com/CurveAgency" title="Curve Agency Twitter profile">@CurveAgency</a> and we'll do our best to help you out.