CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS

What if we wanted a beep when a comment is added? Well, we could implement hook_comment_ insert() and catch the insert operation, but let’s stop and think for a minute. We’re essentially doing the same thing over and over. Wouldn’t it be nice to have a graphical user interface where we could associate the action of beeping with whatever hook and whatever operation we’d like? That’s what Drupal’s built-in trigger module does. It allows you to associate some action with a certain event. In the code, an event is defined as a unique hook-operation combination, such as “user hook, login operation” or “node hook, insert operation.” When each of these operations occurs, trigger.module lets you trigger an action.

To avoid confusion, let’s clarify our terms:

•Event: Used in the generic programming sense, this term is generally understood as a message sent from one component of a system to other components.

•Hook: This programming technique, used in Drupal, allows modules to “hook into” the flow of execution. There are unique hooks for each operation that is performed on the “hookable” object (e.g., hook_node_insert).

•Trigger: This refers to a specific combination of a hook and an operation with which one or more actions can be associated. For example, the action of beeping can be associated with the login operation of the user hook.

Understanding Actions

An action is something that Drupal does. Here are some examples:

•Promoting a node to the front page

•Changing a node from unpublished to published

•Deleting a user

•Sending an e-mail message

Each of these cases has a clearly defined task. Programmers will notice the similarity to PHP functions in the preceding list. For example, you could send e-mail by calling the drupal_mail() function in includes/mail.inc. Actions sound similar to functions, because actions are functions. They are functions that Drupal can introspect and loosely couple with events (more on that in a moment). Now, let’s examine the trigger module.

The Trigger User Interface

Click the Modules link in the menu at the top of the page, and on the Modules page, enable the trigger module. Then click the Structure link in the menu at the top of the page, and on the Structure page, click the Triggers link. You should see an interface similar to the one shown in Figure 3-1.

35

CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS

Figure 3-1. The trigger assignment interface

Notice the tabs across the top. Those correspond to Drupal hooks! In Figure 3-1, we are looking at the operations for the node hook. They’ve all been given nice names; for example, the delete operation of the node hook is labeled “Trigger: After deleting content.” So each of the hook’s operations is shown with the ability to assign an action, such as “Publish Content,” when that operation happens. Each action that is available is listed in the “Choose an action” drop-down.

■ Note Not all actions are available for all triggers, because some actions do not make sense in certain contexts. For example, you wouldn’t run the “Promote post to front page” action with the trigger “After deleting content.” Depending on your installation, some triggers may display “No actions available for this trigger.”

Some trigger names and their respective hooks and operations are shown in Table 3-2.

36

CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS

Table 3-2. How Hooks and Triggers Relate in Drupal 7

37

CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS

Your First Action

What do we need to do in order for our beep function to become a full-fledged action? There are two steps:

1.Inform Drupal which triggers the action should support.

2.Create your action function.

The first step is accomplished by implementing hook_action_info(). Here’s how it should look for our beep module:

/**

*Implemenation of hook_action_info(). */

function beep_action_info() { return array(

'beep_beep_action' => array( 'type' => 'system',

'label' => t('Beep annoyingly'), 'configurable' => FALSE,

'triggers' => array('node_view', 'node_insert', 'node_update', 'node_delete'),

),

);

}

The function name is beep_action_info(), because like other hook implementations, we use our module name (beep) plus the name of the hook (action_info). We’ll be returning an array with an entry for each action in our module. We are writing only one action, so we have only one entry, keyed by the name of the function that will perform the action: beep_beep_action(). It’s handy to know when a function is an action while reading through code, so we append _action to the name of our beep_beep() function to come up with beep_beep_action().

Let’s take a closer look at the keys in our array.

•type: This is the kind of action you are writing. Drupal uses this information to categorize actions in the drop-down select box of the trigger assignment user interface. Possible types include system, node, user, comment, and taxonomy. A good question to ask when determining what type of action you are writing is, “What object does this action work with?” (If the answer is unclear or “lots of different objects!” use the system type.)

•label: This is the friendly name of the action that will be shown in the drop-down select box of the trigger assignment user interface.

•configurable: This determines whether the action takes any parameters.

•triggers: In this array of hooks, each entry must enumerate the operations the action supports. Drupal uses this information to determine where it is appropriate to list possible actions in the trigger assignment user interface.

38