notifications_lite.module in Notifications 6.3

Same filename and directory in other branches

Simple notifications API

This is a very simple API for other modules to produce notifications with a minimal set up.

This module doesn't have direct dependencies because it uses any available module to send out the notifications. It tries in this order:

1. Notifications (queues messages for delivery) 2. Messaging (just sends messages right away with the user's default method) 3. Drupal standard mail

File

notifications_lite/notifications_lite.module

View source

<?php

/**
 * @file
 *   Simple notifications API
 * 
 * This is a very simple API for other modules to produce notifications with a minimal set up.
 * 
 * @see notifications_lite_send()
 * 
 * This module doesn't have direct dependencies because it uses any available module to send
 * out the notifications. It tries in this order:
 * 
 * 1. Notifications (queues messages for delivery)
 * 2. Messaging (just sends messages right away with the user's default method)
 * 3. Drupal standard mail
 * 
 */

/**
 * Sends out a notification for a user
 * 
 * This is all it takes for a module to send out some notification for a user.
 * 
 * However, a real event is produced so other modules may want to provide secondary subscriptions
 * and notifications for these simple events
 * 
 * @param $uid
 *   User id or user account for destination
 * @param $subject
 *   Notification subject
 * @param $body
 *   Optional notification body
 * @param $action
 *   Optional action name, so other modules can define specific message parts for their actions
 * @param $params
 *   Optional array of additional parameters to be stored with the event. For example, one could store the sender
 *   of a message, as otherwise this information might not be easily retrievable during message sending on cron.
 *   Only available when the full notification system is used and not just the messaging module.
 *   
 */
function notifications_lite_send($uid, $subject, $body = '', $action = 'default', $params = array()) {

  // Determine user account and build message array
  if (is_object($uid)) {
    $account = $uid;
  }
  elseif (function_exists('messaging_load_user')) {
    $account = messaging_load_user($uid);
  }
  else {
    $account = user_load(array(
      'uid' => $uid,
    ));
  }
  $language = user_preferred_language($account);
  $message = notifications_lite_build($subject, $body, $action, $language, $params);
  $accounts = array(
    $account,
  );

  // Send using the first available option
  if (module_exists('notifications')) {

    // So we have the full Notifications system enabled
    return notifications_lite_notifications_post($accounts, $message, $params);
  }
  elseif (module_exists('messaging')) {

    // We just have the Messaging system, that's something
    return notifications_lite_messaging_post($accounts, $message, $params);
  }
  else {

    // We don't have anything else so we use Drupal's mail
    return notifications_lite_drupal_post($accounts, $message, $params);
  }
}

/**
 * Post message using notifications
 * 
 * @param unknown_type $accounts
 * @param unknown_type $message
 * @param unknown_type $params
 * @return int
 *   Number of messages sent
 */
function notifications_lite_notifications_post($accounts, $message, $params) {
  $event = notifications_lite_event($message, $params, count($accounts));
  foreach ($accounts as $account) {
    $result = notifications_lite_queue($account, $event);
  }

  // Notify other modules, try inmediate sending
  notifications_module_invoke('event queued', $event);
  notifications_send_immediate($event->eid);
  return count($result);
}

/**
 * Post message using Messaging
 * 
 * @param unknown_type $accounts
 * @param unknown_type $message
 * @param unknown_type $params
 * @return int
 *   Number of messages sent
 */
function notifications_lite_messaging_post($accounts, $data, $params) {
  $message = array(
    'type' => 'notifications-lite',
    'subject' => $data['subject'],
    'body' => $data['body'],
    'language' => $data['language']->language,
    'params' => $data['params'],
  );
  foreach ($accounts as $account) {
    $result[] = messaging_message_send_user($account, $message);
  }
  return count($result);
}

/**
 * Post message using Drupal mail
 * 
 * @param unknown_type $accounts
 * @param unknown_type $message
 * @param unknown_type $params
 * @return int
 *   Number of messages sent
 */
function notifications_lite_drupal_post($accounts, $message, $params) {
  foreach ($accounts as $account) {
    $language = user_preferred_language($account);
    $result[] = drupal_mail('notifications_lite', $message['mailkey'], $account->mail, $language, $message);
  }
  return count($result);
}

/**
 * Build message array from parameters
 * 
 * Special params are
 *  - language = language object
 *  - action = notifications lite action
 */
function notifications_lite_build($subject, $body = '', $action = 'default', $language = NULL, $params = array()) {
  return array(
    'type' => 'notifications-lite',
    'mailkey' => 'notifications-lite-' . $action,
    'subject' => $subject,
    'body' => empty($body) ? $subject : $body,
    'language' => $language ? $language : language_default(),
    'action' => $action,
    'params' => $params,
  );
}

/**
 * Build notifications event
 */
function notifications_lite_event($message, $params, $counter = 1) {

  // Build and store simple event
  $event = array(
    'module' => 'notifications',
    'uid' => 0,
    'oid' => 0,
    'type' => 'lite',
    'action' => $message['action'],
    'params' => $params + array(
      'subject' => $message['subject'],
      'body' => $message['body'],
    ),
    'queue' => FALSE,
    // Do not send to notifications queue, save some queries
    'counter' => $counter,
    // As many as destinations
    'language' => $message['language']->language,
  );
  return notifications_event($event);
}

/**
 * Queue notifications event for user/s
 *
 * This just insert a row into notifications_queue table for this event, so it will be processed on cron
 * The message information (subject, body) will be in the event itself, as serialized parameters
 * 
 * @param $accounts
 *   User account or array of user accounts
 * @param $event
 *   Event to be queued
 */
function notifications_lite_queue($account, $event) {
  $queue = array(
    'uid' => $account->uid,
    'module' => 'notifications',
    'eid' => $event->eid,
    'send_interval' => notifications_user_setting('send_interval', $account),
    'send_method' => notifications_user_setting('send_method', $account),
    'cron' => 1,
    'created' => time(),
    // No subscription, no conditions
    'sid' => 0,
    'conditions' => 0,
  );
  return drupal_write_record('notifications_queue', $queue);
}

/**
 * Implementation of hook_mail()
 */
function notifications_lite_mail($key, &$message, $params) {
  $message['subject'] = $params['subject'];
  $message['body'] = $params['body'];
}

/**
 * Implementation of hook_notifications()
 * 
 * It handles event texts to rebuild the message from stored event parameters
 */
function notifications_lite_notifications($op, &$arg0, $arg1 = NULL, $arg2 = NULL) {
  switch ($op) {
    case 'event load':

      // $arg0 is event
      $event =& $arg0;
      if ($event->type == 'lite') {
        if (!empty($event->params['subject'])) {
          $event->text['subject'] = $event->params['subject'];
          $event->text['digest'] = $event->params['subject'];
        }
        if (!empty($event->params['body'])) {
          $event->text['main'] = $event->params['body'];
          $event->text['digest'] .= ': ' . $event->params['body'];
        }
      }
      break;
    case 'event types':

      // We just define event type 'lite', action 'default'
      $types[] = array(
        'type' => 'lite',
        'action' => 'default',
        'name' => t('Message for [user]'),
        'digest' => NULL,
        // This means grouping by: event type, event action
        'description' => t('Notifications lite message'),
      );
      return $types;
  }
}

/**
 * Implementation of hook_messaging_template()
 */
function notifications_lite_messaging_template($op, $type = NULL, $langcode = NULL) {
  switch ($op) {
    case 'templates':

      // Generic notifications lite event (message)
      $info['notifications-event-lite'] = array(
        'module' => 'notifications_lite',
        'type' => 'notifications',
        'title' => t('Simple notifications', array(), $langcode),
        'help' => t('The subject and main body will be provided by the event itself', array(), $langcode),
        'description' => t('Simple notifications triggered by other modules using the Notifications Lite API module.', array(), $langcode),
        'fallback' => 'notifications-event',
      );
      $info['notifications-digest-lite'] = array(
        'module' => 'notifications_lite',
        'type' => 'notifications',
        'title' => t('Group of simple notifications', array(), $langcode),
        'description' => t('Simple notifications digested with short format.', array(), $langcode),
        'help' => t('Every line of the digest will be a separate message.', array(), $langcode),
        'fallback' => 'notifications-digest',
      );
      return $info;
    case 'keys':
      switch ($type) {
        case 'notifications-event-lite':

          // The other parts for these messages will be given by the event itself
          return array(
            'header' => t('Header', array(), $langcode),
            'footer' => t('Footer', array(), $langcode),
          );
          break;
      }
      break;
    case 'defaults':

      // Event notifications
      switch ($type) {
        case 'notifications-event-lite':
          return array(
            'header' => t("Greetings, [user].", array(), $langcode),
            'footer' => array(
              t('This is an automatic message from [site-name]', array(), $langcode),
              t('To manage your subscriptions, browse to [subscriptions-manage]', array(), $langcode),
            ),
          );
        case 'notifications-digest-lite':
          return array(
            'title' => t('Generic messages', array(), $langcode),
            'closing' => '...',
          );
      }
      break;
  }
}

Functions

Name	Description
notifications_lite_build	Build message array from parameters
notifications_lite_drupal_post	Post message using Drupal mail
notifications_lite_event	Build notifications event
notifications_lite_mail	Implementation of hook_mail()
notifications_lite_messaging_post	Post message using Messaging
notifications_lite_messaging_template	Implementation of hook_messaging_template()
notifications_lite_notifications	Implementation of hook_notifications()
notifications_lite_notifications_post	Post message using notifications
notifications_lite_queue	Queue notifications event for user/s
notifications_lite_send	Sends out a notification for a user

You are here

notifications_lite.module in Notifications 6.3

See also

File

Functions

API Navigation