home | career | drupal | java | mac | mysql | perl | php | scala | uml | unix

Drupal example source code file (trigger.module)

This example Drupal source code file (trigger.module) is included in the DevDaily.com "Drupal Source Code Warehouse" project. The intent of this project is to help you "Learn Drupal by Example".

PHP - Drupal tags/keywords

account, actions, array, comment, edit, function, hook, label, node, php, trigger, type, user

The trigger.module Drupal example source code

<?php
// $Id: trigger.module,v 1.66 2010/12/01 07:41:03 webchick Exp $

/**
 * @file
 * Enables functions to be stored and executed at a later time when
 * triggered by other modules or by one of Drupal's core API hooks.
 */

/**
 * Implements hook_help().
 */
function trigger_help($path, $arg) {
  // Generate help text for admin/structure/trigger/(module) tabs.
  $matches = array();
  if (preg_match('|^admin/structure/trigger/(.*)$|', $path, $matches)) {
    $explanation = '<p>' . t('Triggers are events on your site, such as new content being added or a user logging in. The Trigger module associates these triggers with actions (functional tasks), such as unpublishing content containing certain keywords or e-mailing an administrator. The <a href="@url">Actions settings page</a> contains a list of existing actions and provides the ability to create and configure advanced actions (actions requiring configuration, such as an e-mail address or a list of banned words).', array('@url' => url('admin/config/system/actions'))) . '</p>';

    $module = $matches[1];
    $trigger_info = _trigger_tab_information();
    if (!empty($trigger_info[$module])) {
      $explanation .= '<p>' . t('There is a tab on this page for each module that defines triggers. On this tab you can assign actions to run when triggers from the <a href="@module-help">@module-name module</a> happen.', array('@module-help' => url('admin/help/' . $module), '@module-name' => $trigger_info[$module])) . '</p>';
    }

    return $explanation;
  }

  if ($path == 'admin/help#trigger') {
    $output = '';
    $output .= '<h3>' . t('About') . '</h3>';
    $output .= '<p>' . t('The Trigger module provides the ability to cause <em>actions</em> to run when certain <em>triggers</em> take place on your site. Triggers are events, such as new content being added to your site or a user logging in, and actions are tasks, such as unpublishing content or e-mailing an administrator. For more information, see the online handbook entry for <a href="@trigger">Trigger module</a>.', array('@trigger' => 'http://drupal.org/handbook/modules/trigger/')) . '</p>';
    $output .= '<h3>' . t('Uses') . '</h3>';
    $output .= '<dl>';
    $output .= '<dt>' . t('Configuring triggers and actions') . '</dt>';
    $output .= '<dd>' . t('The combination of actions and triggers can perform many useful tasks, such as e-mailing an administrator if a user account is deleted, or automatically unpublishing comments that contain certain words. To set up a trigger/action combination, first visit the <a href="@actions-page">Actions configuration page</a>, where you can either verify that the action you want is already listed, or create a new <em>advanced</em> action. You will need to set up an advanced action if there are configuration options in your trigger/action combination, such as specifying an e-mail address or a list of banned words. After configuring or verifying your action, visit the <a href="@triggers-page">Triggers configuration page</a> and choose the appropriate tab (Comment, Taxonomy, etc.), where you can assign the action to run when the trigger event occurs.', array('@triggers-page' => url('admin/structure/trigger'), '@actions-page' => url('admin/config/system/actions'))) . '</dd>';
    $output .= '</dl>';
    return $output;
  }
}

/**
 * Implements hook_menu().
 */
function trigger_menu() {
  $items['admin/structure/trigger'] = array(
    'title' => 'Triggers',
    'description' => 'Configure when to execute actions.',
    'page callback' => 'trigger_assign',
    'access arguments' => array('administer actions'),
    'file' => 'trigger.admin.inc',
  );

  $trigger_info = _trigger_tab_information();
  foreach ($trigger_info as $module => $module_name) {
    $items["admin/structure/trigger/$module"] = array(
      'title' => $module_name,
      'page callback' => 'trigger_assign',
      'page arguments' => array($module),
      'access arguments' => array('administer actions'),
      'type' => MENU_LOCAL_TASK,
      'file' => 'trigger.admin.inc',
    );
  }

  $items['admin/structure/trigger/unassign'] = array(
    'title' => 'Unassign',
    'description' => 'Unassign an action from a trigger.',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('trigger_unassign'),
    'access arguments' => array('administer actions'),
    'file' => 'trigger.admin.inc',
  );

  return $items;
}

/**
 * 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'),
       ),
       '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_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'),
       ),
       'user_view' => array(
         'label' => t("When a user's profile is being viewed"),
       ),
     ),
   );
 }

/**
 * Gets the action IDs of actions to be executed for a hook.
 *
 * @param $hook
 *   The name of the hook being fired.
 * @return
 *   An array whose keys are action IDs that the user has associated with
 *   this trigger, and whose values are arrays containing the action type and
 *   label.
 */
function trigger_get_assigned_actions($hook) {
  return db_query("SELECT ta.aid, a.type, a.label FROM {trigger_assignments} ta LEFT JOIN {actions} a ON ta.aid = a.aid WHERE ta.hook = :hook ORDER BY ta.weight", array(
    ':hook' => $hook,
  ))->fetchAllAssoc( 'aid', PDO::FETCH_ASSOC);
}

/**
 * Implements hook_theme().
 */
function trigger_theme() {
  return array(
    'trigger_display' => array(
      'render element' => 'element',
      'file' => 'trigger.admin.inc',
    ),
  );
}

/**
 * Implements hook_forms().
 *
 * We re-use code by using the same assignment form definition for each hook.
 */
function trigger_forms() {
  $trigger_info = _trigger_get_all_info();
  $forms = array();
  foreach ($trigger_info as $module => $hooks) {
    foreach ($hooks as $hook => $description) {
      $forms['trigger_' . $hook . '_assign_form'] = array('callback' => 'trigger_assign_form');
    }
  }

  return $forms;
}

/**
 * Loads associated objects for node triggers.
 *
 * When an action is called in a context that does not match its type, the
 * object that the action expects must be retrieved. For example, when an action
 * that works on users is called during a node hook implementation, the user
 * object is not available since the node hook call doesn't pass it. So here we
 * load the object the action expects.
 *
 * @param $type
 *   The type of action that is about to be called.
 * @param $node
 *   The node that was passed via the node hook.
 *
 * @return
 *   The object expected by the action that is about to be called.
 */
function _trigger_normalize_node_context($type, $node) {
  // Note that comment-type actions are not supported in node contexts,
  // because we wouldn't know which comment to choose.
  switch ($type) {
    // An action that works on users is being called in a node context.
    // Load the user object of the node's author.
    case 'user':
      return user_load($node->uid);
  }
}

/**
 * Calls action functions for node triggers.
 *
 * @param $node
 *   Node object.
 * @param $op
 *   Operation to trigger.
 * @param $a3
 *   Additional argument to action function.
 * @param $a4
 *   Additional argument to action function.
 */
function _trigger_node($node, $hook, $a3 = NULL, $a4 = NULL) {
  // Keep objects for reuse so that changes actions make to objects can persist.
  static $objects;
  // Prevent recursion by tracking which operations have already been called.
  static $recursion;

  $aids = trigger_get_assigned_actions($hook);
  if (!$aids) {
    return;
  }

  if (isset($recursion[$hook])) {
    return;
  }
  $recursion[$hook] = TRUE;

  $context = array(
    'group' => 'node',
    'hook' => $hook,
  );

  // We need to get the expected object if the action's type is not 'node'.
  // We keep the object in $objects so we can reuse it if we have multiple actions
  // that make changes to an object.
  foreach ($aids as $aid => $info) {
    $type = $info['type'];
    if ($type != 'node') {
      if (!isset($objects[$type])) {
        $objects[$type] = _trigger_normalize_node_context($type, $node);
      }
      // Since we know about the node, we pass that info along to the action.
      $context['node'] = $node;
      $result = actions_do($aid, $objects[$type], $context, $a3, $a4);
    }
    else {
      actions_do($aid, $node, $context, $a3, $a4);
    }
  }

  unset($recursion[$hook]);
}

/**
 * Implements hook_node_view().
 */
function trigger_node_view($node, $view_mode) {
  _trigger_node($node, 'node_view', $view_mode);
}

/**
 * Implements hook_node_update().
 */
function trigger_node_update($node) {
  _trigger_node($node, 'node_update');
}

/**
 * Implements hook_node_presave().
 */
function trigger_node_presave($node) {
  _trigger_node($node, 'node_presave');
}

/**
 * Implements hook_node_insert().
 */
function trigger_node_insert($node) {
  _trigger_node($node, 'node_insert');
}

/**
 * Implements hook_node_delete().
 */
function trigger_node_delete($node) {
  _trigger_node($node, 'node_delete');
}

/**
 * Loads associated objects for comment triggers.
 *
 * When an action is called in a context that does not match its type, the
 * object that the action expects must be retrieved. For example, when an action
 * that works on nodes is called during the comment hook, the node object is not
 * available since the comment hook doesn't pass it. So here we load the object
 * the action expects.
 *
 * @param $type
 *   The type of action that is about to be called.
 * @param $comment
 *   The comment that was passed via the comment hook.
 *
 * @return
 *   The object expected by the action that is about to be called.
 */
function _trigger_normalize_comment_context($type, $comment) {
  switch ($type) {
    // An action that works with nodes is being called in a comment context.
    case 'node':
      return node_load(is_array($comment) ? $comment['nid'] : $comment->nid);

    // An action that works on users is being called in a comment context.
    case 'user':
      return user_load(is_array($comment) ? $comment['uid'] : $comment->uid);
  }
}

/**
 * Implements hook_comment_presave().
 */
function trigger_comment_presave($comment) {
  _trigger_comment($comment, 'comment_presave');
}

/**
 * Implements hook_comment_insert().
 */
function trigger_comment_insert($comment) {
  _trigger_comment($comment, 'comment_insert');
}

/**
 * Implements hook_comment_update().
 */
function trigger_comment_update($comment) {
  _trigger_comment($comment, 'comment_update');
}

/**
 * Implements hook_comment_delete().
 */
function trigger_comment_delete($comment) {
  _trigger_comment($comment, 'comment_delete');
}

/**
 * Implements hook_comment_view().
 */
function trigger_comment_view($comment) {
  _trigger_comment($comment, 'comment_view');
}

/**
 * Calls action functions for comment triggers.
 *
 * @param $a1
 *   Comment object or array of form values.
 * @param $op
 *   Operation to trigger.
 */
function _trigger_comment($a1, $hook) {
  // Keep objects for reuse so that changes actions make to objects can persist.
  static $objects;
  $aids = trigger_get_assigned_actions($hook);
  $context = array(
    'group' => 'comment',
    'hook' => $hook,
  );
  // We need to get the expected object if the action's type is not 'comment'.
  // We keep the object in $objects so we can reuse it if we have multiple
  // actions that make changes to an object.
  foreach ($aids as $aid => $info) {
    $type = $info['type'];
    if ($type != 'comment') {
      if (!isset($objects[$type])) {
        $objects[$type] = _trigger_normalize_comment_context($type, $a1);
      }
      // Since we know about the comment, we pass it along to the action
      // in case it wants to peek at it.
      $context['comment'] = (object) $a1;
      actions_do($aid, $objects[$type], $context);
    }
    else {
      actions_do($aid, $a1, $context);
    }
  }
}

/**
 * Implements hook_cron().
 */
function trigger_cron() {
  $aids = trigger_get_assigned_actions('cron');
  $context = array(
    'group' => 'cron',
    'hook' => 'cron',
  );
  // Cron does not act on any specific object.
  $object = NULL;
  actions_do(array_keys($aids), $object, $context);
}

/**
 * Loads associated objects for user triggers.
 *
 * When an action is called in a context that does not match its type, the
 * object that the action expects must be retrieved. For example, when an action
 * that works on nodes is called during the user hook, the node object is not
 * available since the user hook doesn't pass it. So here we load the object the
 * action expects.
 *
 * @param $type
 *   The type of action that is about to be called.
 * @param $account
 *   The account object that was passed via the user hook.
 * @return
 *   The object expected by the action that is about to be called.
 */
function _trigger_normalize_user_context($type, $account) {
  // Note that comment-type actions are not supported in user contexts,
  // because we wouldn't know which comment to choose.
  switch ($type) {
    // An action that works with nodes is being called in a user context.
    // If a single node is being viewed, return the node.
    case 'node':
      // If we are viewing an individual node, return the node.
      if (arg(0) == 'node' && is_numeric(arg(1)) && arg(2) == NULL) {
        return node_load(array('nid' => arg(1)));
      }
      break;
  }
}

/**
 * Implements hook_user_login().
 */
function trigger_user_login(&$edit, $account, $category) {
  _trigger_user('user_login', $edit, $account, $category);
}

/**
 * Implements hook_user_logout().
 */
function trigger_user_logout($account) {
  $edit = array();
  _trigger_user('user_logout', $edit, $account);
}

/**
 * Implements hook_user_insert().
 */
function trigger_user_insert(&$edit, $account, $category) {
  _trigger_user('user_insert', $edit, $account, $category);
}

/**
 * Implements hook_user_update().
 */
function trigger_user_update(&$edit, $account, $category) {
  _trigger_user('user_update', $edit, $account, $category);
}

/**
 * Implements hook_user_cancel().
 */
function trigger_user_cancel($edit, $account, $method) {
  switch ($method) {
    case 'user_cancel_reassign':
      _trigger_user('user_delete', $edit, $account, $method);
      break;
  }
}

/**
 * Implements hook_user_delete().
 */
function trigger_user_delete($account) {
  $edit = array();
  _trigger_user('user_delete', $edit, $account, NULL);
}

/**
 * Implements hook_user_view().
 */
function trigger_user_view($account) {
  $edit = NULL;
  _trigger_user('user_view', $edit, $account, NULL);
}

/**
 * Calls action functions for user triggers.
 */
function _trigger_user($hook, &$edit, $account, $category = NULL) {
  // Keep objects for reuse so that changes actions make to objects can persist.
  static $objects;
  $aids = trigger_get_assigned_actions($hook);
  $context = array(
    'group' => 'user',
    'hook' => $hook,
    'form_values' => &$edit,
  );
  foreach ($aids as $aid => $info) {
    $type = $info['type'];
    if ($type != 'user') {
      if (!isset($objects[$type])) {
        $objects[$type] = _trigger_normalize_user_context($type, $account);
      }
      $context['user'] = $account;
      actions_do($aid, $objects[$type], $context);
    }
    else {
      actions_do($aid, $account, $context, $category);
    }
  }
}

/**
 * Calls action functions for taxonomy triggers.
 *
 * @param $hook
 *   Hook to trigger actions for taxonomy_term_insert(),
 *   taxonomy_term_update(), and taxonomy_term_delete().
 * @param $array
 *   Item on which operation is being performed, either a term or
 *   form values.
 */
function _trigger_taxonomy($hook, $array) {
  $aids = trigger_get_assigned_actions($hook);
  $context = array(
    'group' => 'taxonomy',
    'hook' => $hook
  );
  actions_do(array_keys($aids), (object) $array, $context);
}

/**
 * Implements hook_taxonomy_term_insert().
 */
function trigger_taxonomy_term_insert($term) {
  _trigger_taxonomy('taxonomy_term_insert', (array) $term);
}

/**
 * Implements hook_taxonomy_term_update().
 */
function trigger_taxonomy_term_update($term) {
  _trigger_taxonomy('taxonomy_term_update', (array) $term);
}

/**
 * Implements hook_taxonomy_term_delete().
 */
function trigger_taxonomy_term_delete($term) {
  _trigger_taxonomy('taxonomy_term_delete', (array) $term);
}

/**
 * Implements hook_actions_delete().
 *
 * Removes all trigger entries for the given action, when an action is deleted.
 */
function trigger_actions_delete($aid) {
  db_delete('trigger_assignments')
    ->condition('aid', $aid)
    ->execute();
}

/**
 * Retrieves and caches information from hook_trigger_info() implementations.
 */
function _trigger_get_all_info() {
  $triggers = &drupal_static(__FUNCTION__);

  if (!isset($triggers)) {
    $triggers = module_invoke_all('trigger_info');
    drupal_alter('trigger_info', $triggers);
  }

  return $triggers;
}

/**
 * Gathers information about tabs on the triggers administration screen.
 *
 * @return
 *   Array of modules that have triggers, with the keys being the
 *   machine-readable name of the module, and the values being the
 *   human-readable name of the module.
 */
function _trigger_tab_information() {
  // Gather information about all triggers and modules.
  $trigger_info = _trigger_get_all_info();
  $modules = system_get_info('module');
  $modules = array_intersect_key($modules, $trigger_info);

  $return_info = array();
  foreach ($modules as $name => $info) {
    $return_info[$name] = $info['name'];
  }

  return $return_info;
}

Other Drupal examples (source code examples)

Here is a short list of links related to this Drupal trigger.module source code file:

new blog posts

"Drupal" is a registered trademark of Dries Buytaert.

my drupal tutorials and examples  

Copyright 1998-2016 Alvin Alexander, alvinalexander.com
All Rights Reserved.

Beginning in 2016, a portion of the proceeds from pages under the '/drupal-code-examples/' URI will be donated to charity.