Download from Wow! eBook <www.wowebook.com>
CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
The actions execution engine determines whether to go through the process of retrieving stored parameters for an action based on whether the action ID is numeric. If it is not numeric, the action is simply executed and the database is not consulted. This is a very quick determination; Drupal uses the same approach in index.php to distinguish content from menu constants.
Calling an Action Directly with actions_do()
The trigger module is only one way to call actions. You might want to write a separate module that calls actions and prepare the parameters yourself. If so, using actions_do() is the recommended way to call actions. The function signature follows:
actions_do($action_ids, $object = NULL, $context = NULL, $a1 = NULL, $a2 = NULL)
Let’s examine each of these parameters.
•$action_ids: The action(s) to execute, either a single action ID or an array of action IDs
•$object: The object that the action will act upon: a node, user, or comment, if any
•$context: Associative array containing information the action may wish to use, including configured parameters for advanced actions
•$a1 and $a2: Optional additional parameters that, if passed to actions_do(), will be passed along to the action
Here’s how we would call our simple “Beep” action using actions_do():
$object = NULL; // $object is a required parameter but unused in this case actions_do('beep_beep_action', $object);
And here is how we would call the “Beep multiple times” advanced action:
$object = NULL; actions_do(2, $object);
Or, we could call it and bypass the retrieval of stored parameters like this:
$object = NULL; $context['beeps'] = 5;
actions_do('beep_multiple_beep_action', $object, $context);
50
CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
■ Note Hardcore PHP developers may be wondering, “Why use actions at all? Why not just call the function directly or just implement a hook? Why bother with stashing parameters in the context, only to retrieve them again instead of using traditional PHP parameters?” The answer is that by writing actions with a very generic function signature, code reuse can be delegated to the site administrator. The site administrator, who may not know PHP, does not have to call on a PHP developer to set up the functionality to send an e-mail when a new node is added. The site administrator simply wires up the “Send e-mail” action to the trigger that fires when a new node is saved and never has to call anyone.
Defining Your Own Triggers with hook_trigger_info()
How does Drupal know which triggers are available for display on the triggers user interface? In typical fashion, it lets modules define hooks declaring which triggers the modules implement. For example, here’s the implementation of hook_trigger_info() from Triggers module itself, which defines all of the standard triggers that are available after installing the Drupal 7 core.
/**
*Implements hook_trigger_info().
*Defines all the triggers that this module implements triggers for.
*/
function trigger_trigger_info() { return array(
'node' => array( 'node_presave' => array(
'label' => t('When either saving new content or updating existing content'),
),
'node_insert' => array(
'label' => t('After saving new content'),
),
'node_update' => array(
'label' => t('After saving updated content'),
),
'node_delete' => array(
'label' => t('After deleting content'),
),
'node_view' => array(
'label' => t('When content is viewed by an authenticated user'),
),
),
'comment' => array( 'comment_presave' => array(
'label' => t('When either saving a new comment or updating an existing comment'),
),
51
CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
'comment_insert' => array(
'label' => t('After saving a new comment'),
),
'comment_update' => array(
'label' => t('After saving an updated comment'),
),
'comment_delete' => array(
'label' => t('After deleting a comment'),
),
'comment_view' => array(
'label' => t('When a comment is being viewed by an authenticated user'),
),
),
'taxonomy' => array( 'taxonomy_term_insert' => array(
'label' => t('After saving a new term to the database'),
),
'taxonomy_term_update' => array(
'label' => t('After saving an updated term to the database'),
),
'taxonomy_term_delete' => array( 'label' => t('After deleting a term'),
),
),
'system' => array( 'cron' => array(
'label' => t('When cron runs'),
),
),
'user' => array( 'user_presave' => array(
'label' => t('When either creating a new user account or updating an existing'),
),
'user_insert' => array(
'label' => t('After creating a new user account'),
),
'user_update' => array(
'label' => t('After updating a user account'),
),
'user_delete' => array(
'label' => t('After a user has been deleted'),
),
'user_login' => array(
'label' => t('After a user has logged in'),
),
'user_logout' => array(
'label' => t('After a user has logged out'),
),
52
CHAPTER 3 ■ HOOKS, ACTIONS, AND TRIGGERS
'user_view' => array(
'label' => t("When a user's profile is being viewed"),
),
),
);
}
As you can see in the structure of the function, each category of trigger (e.g., node, comment, system, and user) returns an array of options that appear on the triggers configuration page. Within each of the category arrays, you can define the trigger and the label that will appear on the triggers configuration page, such as the following, where node_insert is the name of the trigger and the value associated with the label element is what appears on the Trigger configuration page.
'node_insert' => array(
'label' => t('After saving new content'),
)
If we updated our annotations module from Chapter 2 to include hooks, those hooks might look like the following:
/**
* Implementation of hook_trigger_info(). */
function annotate_trigger_info() { return array(
'annotate' => array( 'annotate_insert' => array(
'label' => t('After saving new annotations'),
),
'annotate_update' => array(
'label' => t('After saving updated annotations'),
),
'annotate_delete' => array(
'label' => t('After deleting annotations'),
),
'annotate_view' => array(
'label' => t('When annotation is viewed by an authenticated user'),
),
),
);
}
After clearing its cache, Drupal would pick up the new implementation of hook_trigger_info() and modify the triggers page to include a separate tab for the new Annotations hook, as shown in Figure 3-7. Of course, the module itself would still be responsible for firing the hooks using module_invoke() or module_invoke_all() and for firing the actions. In this example, the module would need to call module_invoke_all (‘annotate_insert’, ‘annotate_update’, ‘annotate_delete’, ‘annotate_view’). It would then need to implement hook_annotate_insert, hook_annotate_update, hook_annotate_delete, or hook_annotate_view, and fire the actions with actions_do().
53