hook_messaging(): Defining Message Templates and Sending Types

This page explains how to implement hook_messaging(), which is the main integration point for most of what happens in the Messaging module -- in particular describing the kinds of messages your module provides, or to modifying messaging fields, or providing a new kind of messaging.

Start by copying this template into your module, replacing MODULENAME with your module's name. Each case is described in detail below. Parameters for each case are described inline.

/**
 * Implementation of hook_messaging().
 */
function MODULENAME_messaging($op, $arg1 = NULL, $arg2 = NULL) {
  switch ($op) {
    case 'message groups':
      $info = array();
      return $info;

    case 'message keys':
      $message_group = $arg1;
      break;

    case 'messages':
      $message_group = $arg1;
      break;

    case 'tokens':
      $message_group = $arg1;
      return array();

    case 'method update':
      $old_method = $arg1;
      $new_method = $arg2;
      break;

    case 'send methods':
      break;

    default:
      break;
  }
}

The first parameter, $op, is the "operation" that the Messaging module is performing when your hook_messaging() implementation gets called. As noted above, the other parameters depend on the value of $op. Each operation is described in detail below.

• 'message groups' - Tell the Messaging module the kinds of messages ('message templates') that your module provides. Return an $info array of message groups. The keys of $info are the names for the different message templates. The module will search for message templates in this order:
  1. $module-$type-[$event->type]-[$event->action]
  2. $module-$type-[$event->type]
  3. $module-$type

  In this arrangement, $module is the module that is literally passing the messages to Messaging -- so it is almost always "notifications." $type is either "event" or "digest," $event->type is your choice (usually "node") and $event->action is one of the actions specified in the "event type" case of hook_notifications(). You should structure your templates hierarchically this way so that templates fall back to a template that is less specific.

  Arguments:

  None

  Returns:

  $info - An array listing your module name, the human-readable name of the message types your module provides, and a human-readable description for each message type.
  

  Example:

    switch ($op) {
      case 'message groups':
        $help = t('The <em>Header</em> and <em>Footer</em> will be taken from Notification events.');
        $help_digest = $help . ' ' . t('The <em>Digest line</em> will be used when composing Short digests on which each event will be just a line.');
        $info = array();
        $info['notifications-event-node'] = array(
          'module' => 'notifications_content',
          'name' => t('Notifications for node events'),
          'description' => t('Defaults for all notifications related to node events.'),
          'help' => $help_digest,
          'fallback' => 'notifications-event',
        );
        $info['notifications-event-node-insert'] = array(
          'module' => 'notifications_content',
          'name' => t('Notifications for node creation'),
          'description' => t('Notifications produced when a new node is created.'),
          'help' => $help_digest,
          'fallback' => 'notifications-event-node',
        );
        $info['notifications-digest-node-nid'] = array(
          'module' => 'notifications-content',
          'name' => t('Groups digests per node'),
          'description' => t('Group of events digested for each node.'),
          'fallback' => 'notifications-digest',
        );
        return $info;
    }
  

• 'message keys' - Returns a mapping of template parts to their human-friendly names. The template being processed is designated in $arg1.
  

  Arguments:

  $arg0 - the message type, defined by a previous call to hook_messaging with $op = 'message groups'.

  Returns:

  $info - An array listing the parts and human-readable names for each part.
  

  Example:

    switch ($op) {
      case 'message keys':
        $type = $arg1;
        switch ($type) {
          case 'notifications-event-node':
          case 'notifications-event-node-insert':
          case 'notifications-event-node-update':
          case 'notifications-event-node-comment':
            // Some parts will be re-used from 'notifications-event' group
            // So we specify only subject and main message
            return array(
              'subject' => t('Subject'),
              'main' => t('Content'),
              'digest' => t('Digest line'),
            );
          case 'notifications-digest-node-nid':
          case 'notifications-digest-node-type':
            $parts['title'] = t('Group title');
            $parts['closing'] = t('Group footer');
            return $parts;
        }
        break;
    }
  

• 'messages' - Get default message templates for the given message type ($arg0). Your module returns default values for the text that will appear in the user's messages. Your module provides text values for each of the keys you previously specified when your hook_messaging() implementation was called with $op = 'message keys'. Note that 'messages' defines default values. Users may edit these templates on the 'Messaging templates' page.
  

  Arguments:

  $arg0 - the message type

  Returns:

  $texts - An array listing the parts and human-readable names for each part.
  

  Example:

    switch ($op) {
      case 'messages':
        $type = $arg0;
        // Event notifications
        if ($type == 'notifications-event') {
          return array(
            'subject' => t('Event notification for [user] from [site-name]'),
            'header' => t("Greetings [user],"),
            'main' => t("A item to which you are subscribed has been updated"),
            'footer' => array(
                t('This is an automatic message from [site-name]'),
                t('To manage your subscriptions, browse to [subscriptions-manage]'),
                t('You can unsubscribe at [unsubscribe-url]'),
            ),
          );
        }
        // Digested messages
        if ($type == 'notifications-digest') {
          return array(
            'subject' => t('[site-name] subscription update for [user]'),
            'header' => t("Greetings, [user].\n\nThese are your messages"),
            'main' => t("A [type] has been updated: [title]\n\n[event_list]"),
            'footer' => array(
              t('This is an automatic message from [site-name]'),
              t('To manage your subscriptions, browse to [subscriptions-manage]'),
            ),        
          );
        }
        break;
    }
  

• 'tokens' - Return the list of available token groups (vs. individual tokens) for the given message key ($arg0). You defined all the message keys your module implements in the hook_messaging('message groups') call. Return the array of token keys that will be available for the argument message template. The tokens themselves may be default tokens (provided by token module) or we can add new tokens implementing hook_token_list() and hook_token_value().
  

  Arguments:

  $arg0 - the message type, defined by a previous call to hook_messaging with $op = 'message groups'.

  Returns:

  $tokens - the array of tokens
  

  Example:

    switch ($op) {
      case 'tokens':
        $type = explode('-', $arg1); // get the parts of the template name as explained in the "messaging groups" case
        $tokens = array();
        // These are the token groups that will be used for this module's messages
        if ($type[0] == 'notifications') {
          $tokens = array('global', 'subscription', 'user');
          if ($type[1] == 'event') {
            $tokens[] = 'event';
          }
        }
        return $tokens;
    }
  

• 'method update' - A messaging method has been disabled ($arg0) and replaced by the new one ($arg1). Messaging methods that come with the messaging module: mail, phpmailer, SMS (if you have a gateway provider), and simple. If you module keeps track of information by messaging type, you can update that information here.
  

  Arguments:

  $arg0 - the original messaging method

  $arg1 - the replacement messaging method

  Returns:

  None

  Example:

    switch ($op) {
      case 'method update':
        // A messaging method has been disabled ($arg0) and replaced by the new one ($arg1)
        // Update subscriptions
        db_query("UPDATE {notifications} SET send_method = '%s' WHERE send_method = '%s'", $arg2, $arg1);
        // Purge notifications queue, we may lost some notifications but it's the safest option.
        db_query("DELETE FROM {notifications_queue} WHERE send_method = '%s'", $arg1);
        break;
    }
  

• 'send methods' - What methods of sending messages does your module implement?
  

  Arguments:

  None

  Returns:

  $info - an array describing the send method(s) your module provides.
  

  Example:

    switch($op) {
      case 'send methods':
        $info['mail'] = array(
          'title' => 'Drupal mail',
          'name' => t('Mail'), // Name for display
          'group' => 'mail', // Class of sending method
          'destination' => 'mail', // Account property to use as destination
          'send' => 'messaging_mail_send_msg', // Sending callback
          'type' => MESSAGING_TYPE_PUSH,  // Method type: push || pull
          'glue' => "\n", // Glue for message body lines
          'footer' => "\n--",  // Separator for message footer
          'description' => t('Send e-mails using the default Drupal mail library.'),
        );
        return $info;  
    }
  

That's it for hook_messaging(). If you got here from the Adding new notification events and subscription types tutorial, head back there to finish your plugin.

If you'd like to look at other hook_messaging() implementations, there are two in the Notifications package in notifications_content.module and notifications_tags.module, plus one provided by the Facebook-style Statuses module's Notifications Integration submodule in fbss_notifications.module. Additionally, for modules providing new message sending types (as opposed to just new message templates), check out messaging_mail_messaging() in messaging_mail.module. It's probably a good idea to do this just for a sanity check that this documentation is up-to-date.