»
Thought
«

Drupal Actions and Triggers A Quick Code Example of How to Create a Trigger

Submitted by zzolo on 2009, March 23 - 12:17am

Actions and Triggers are awesome, and they made it into core with Drupal 6. The combination of the modules creates an event and responder system for Drupal. On a basic level, Triggers are like events in (for instance, creating a comment). Actions are then the responding procedure that Drupal takes based on that Trigger.

Actions

Creating actions is explained well in this article, Writing an Action for Drupal 6, and if you have the Pro Drupal Development: 2nd Edition book, there is a good chapter about creating actions.

Triggers

Triggers, on the other hand, have little documentation on how to create new ones. There are many built in triggers that provide a lot of events to attach actions to. But, when creating any critical modules, it is important to be able to set events so that logging and notifying can happen at the right points.

So, here is some example code for creating your own trigger.

Example

Permissions

This hook is not necessary to implement. But as I think it is good practice to implement specific permissions, I am including it. There is also a bug/problem with the trigger module, which restricts access control to triggers based on module name. Which I volunteered to patch and have not followed through with; my apologies. Nonetheless, we can work around this with hook_menu_alter().

  1. /**
  2.  * Implementation of hook_perm().
  3.  */
  4. function example_perm() {
  5.   return array('administer our modules triggers');
  6. }
Menu Alter

We want the permissions for administering our trigger to be unique, so we implement this hook.

  1. /**
  2.  * Implementation of hook_menu_alter
  3.  */
  4. function example_menu_alter(&$items) {
  5.   // By default, the trigger system uses the module name 
  6.   // (i.e. example) as the access for the trigger
  7.   // configuration menu item.  we want to change that.
  8.   $items['admin/build/trigger/example']['access arguments'] = array('administer our modules triggers');
  9. }
Hook Info

This hook tells the trigger module about our triggers.

  1. /**
  2.  * Implementation of hook_hook_info
  3.  */
  4. function example_hook_info() {
  5.   // Define triggers
  6.   $items = array(
  7.     'example' => array(
  8.       'example' => array(
  9.         'our_new_trigger' => array(
  10.           'runs when' => t('When we put in our trigger, thats when it will run.'),
  11.         ),
  12.       ),
  13.     ),
  14.   );
  15.   return $items;
  16. }
Attaching Actions

The next step is to define which actions will be able to be run with our triggers. We will add two actions that are already provided: the Message and Email actions. We don't want to step on any other trigger toes. If we are not careful, we will make it so that actions will only be allowed on our trigger. So, we implement some basic conditional logic.

  1. /**
  2.  * Implementation of hook_action_info_alter
  3.  */
  4. function example_action_info_alter(&$info) {
  5.   // We want to add this modules's triggers to the email action
  6.   if (isset($info['system_send_email_action']['hooks']['example'])) {
  7.     array_merge($info['system_send_email_action']['hooks']['example'], array('our_new_trigger'));
  8.   } else {
  9.     $info['system_send_email_action']['hooks']['example'] = array('our_new_trigger');
  10.   }
  11.  
  12.   // We want to add this modules's triggers to the message action
  13.   if (isset($info['system_message_action']['hooks']['example'])) {
  14.     array_merge($info['system_message_action']['hooks']['example'], array('our_new_trigger'));
  15.   } else {
  16.     $info['system_message_action']['hooks']['example'] = array('our_new_trigger');
  17.   }
  18. }
Invoke Wrapper

This is unnecessary, but helps a lot. We want to make sure that all modules know whats going on when we call our trigger, so we create this wrapper function.

  1. /**
  2.  * Invoke trigger
  3.  *
  4.  * This function is a wrapper/helper for triggers/hooks
  5.  *
  6.  * @param $hook
  7.  *   string describing hook
  8.  * @param $op
  9.  *   string describing operation
  10.  * @return
  11.  *   boolean, true or false if successful
  12.  */
  13. function example_invoke_hook($hook = 'example', $op = null, $object = null) {
  14.   // Perform hook invoke
  15.   // Given the complexity of your module, you might already have hooks and might need to change this
  16.   module_invoke_all($hook, $op);
  17.   // Call trigger/actions
  18.   $aids = _trigger_get_hook_aids($hook, $op);
  19.   $context = array('hook' => $hook, 'op' => $op);
  20.   actions_do(array_keys($aids), $object, $context);
  21.   return true;
  22. }
Calling Our Trigger

This is just a sample function where we call our new trigger.

  1. /**
  2.  * Some function
  3.  */
  4. function example_function($params = array()) {
  5.   // ...
  6.   // We are doing stuff, and then BAM! trigger
  7.   example_invoke_hook('example', 'our_new_trigger');
  8. }
Topics: 
drupaldrupal-planetactionstriggers

Comments

Submitted by fago (not verified) on 2009, March 23 - 6:45am

As an alternative you can add support for the rules module: http://drupal.org/project/rules
There adding new events (which you can trigger on) is much easier, see http://drupal.org/node/298549.

Submitted by Jim (not verified) on 2009, March 23 - 7:53am

Added to DrupalSightings.com

Submitted by Masked User (not verified) on 2010, February 18 - 1:27pm

You do not state what file to put your code in and where to put that file. Please add this to your tutorial. Thanks

Submitted by zzolo on 2010, February 19 - 2:39am

How to create a Drupal module is not in the scope of this article, but check this tutorial out:
http://drupal.org/node/206753