You are here

Home » API reference » Messaging 6.3

messaging_template.module in Messaging 6.3

Same filename and directory in other branches
  1. 6.4 messaging_template/messaging_template.module
  2. 7 messaging_template/messaging_template.module

Template system for Messaging Framework

By Development Seed, http://wwww.developmentseed.org

Modules using templates can support a pluggable templating system

A templating system must provide templates for the following search keys

  • 'group', Main message part key, can have different parts. I.e. 'notifications-event'
  • '

It should also provide a text replacing function that may use tokens, variables...

See also

messaging_template_text_replace()

File

messaging_template/messaging_template.module
View source 
<?php

/**
 * @file
 * Template system for Messaging Framework
 * 
 * By Development Seed, http://wwww.developmentseed.org
 * 
 * Modules using templates can support a pluggable templating system
 * 
 * A templating system must provide templates for the following search keys
 * - 'group', Main message part key, can have different parts. I.e. 'notifications-event'
 * - '
 * It should also provide a text replacing function that may use tokens, variables...
 * 
 * @see messaging_template_text_replace()
 */
define('MESSAGING_TEMPLATE_FALLBACK', 0);
define('MESSAGING_TEMPLATE_OVERRIDE', 1);
define('MESSAGING_TEMPLATE_DEFAULT', 2);

/**
 * Implementation of hook_autoload_info().
 */
function messaging_template_autoload_info() {
  return array(
    'Messaging_Template' => array(
      'file' => 'messaging_template.inc',
    ),
    'Messaging_Template_Engine' => array(
      'file' => 'messaging_template.inc',
    ),
  );
}

/**
 * Implementation of hook_help().
 */
function messaging_template_help($path, $arg) {
  if ($arg[0] == 'admin' || $path == 'admin/help#messaging_template') {
    module_load_include('admin.inc', 'messaging_template');
    return messaging_template_admin_help($path, $arg);
  }
}

/**
 * Implementation of hook_menu()
 */
function messaging_template_menu() {
  $items['admin/messaging/template'] = array(
    'title' => 'Message templates',
    'description' => 'Configuration of message templates',
    'page callback' => 'messaging_template_admin_overview',
    'access arguments' => array(
      'administer messaging',
    ),
    'file' => 'messaging_template.admin.inc',
  );
  $items['admin/messaging/template/overview'] = array(
    'title' => 'Active',
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['admin/messaging/template/settings'] = array(
    'title' => 'Options',
    'description' => 'Enable templates',
    'page callback' => 'drupal_get_form',
    'page arguments' => array(
      'messaging_template_admin_settings',
    ),
    'access arguments' => array(
      'administer messaging',
    ),
    'file' => 'messaging_template.admin.inc',
    'type' => MENU_LOCAL_TASK,
  );
  $items['admin/messaging/template/edit'] = array(
    'title' => 'Message templates',
    'page callback' => 'messaging_template_admin_edit',
    'type' => MENU_CALLBACK,
    'access arguments' => array(
      'administer messaging',
    ),
    'file' => 'messaging_template.admin.inc',
  );
  return $items;
}

/**
 * Implementation of hook_theme()
 */
function messaging_template_theme() {
  return array(
    'messaging_template_admin_templates' => array(
      'arguments' => array(
        'element' => NULL,
      ),
      'file' => 'messaging_template.admin.inc',
    ),
    'messaging_template_admin_type' => array(
      'arguments' => array(
        'type' => NULL,
      ),
      'file' => 'messaging_template.admin.inc',
    ),
    'messaging_template_text_part' => array(
      'arguments' => array(
        'elements' => NULL,
      ),
      'file' => 'messaging_template.admin.inc',
    ),
  );
}

/**
 * Returns information about message template groups, always in default language
 * 
 * Was: messaging_message_group()
 * 
 * @param $name
 *   Optional message group. Returns all groups if null.
 * @param $key
 *   Optional message key inside the group. Returns all keys if null.
 * @return array()
 *   Depending on parameters, may be all message groups and keys or only a specific one.
 */
function messaging_template_info($name = NULL, $key = NULL) {
  static $info;
  if (!isset($info)) {
    $info = array();
    $result = db_query('SELECT * FROM {messaging_template}');
    while ($data = db_fetch_array($result)) {
      $info[$data['name']] = $data;
    }

    // Add module info and create when missing
    $module_info = messaging_template_invoke_all('templates');
    foreach ($module_info as $type => $data) {
      if (isset($info[$type])) {
        $info[$type] = array_merge($data, $info[$type]);
      }
      else {
        $data['name'] = $type;
        $data['enabled'] = empty($data['disabled']);
        drupal_write_record('messaging_template', $data);
        $info[$type] = $data;
      }
    }
  }
  return _messaging_info($info, $name, $key);
}

/**
 * Get next enabled template fallback
 */
function messaging_template_fallback($name) {
  if ($fallback = messaging_template_info($name, 'fallback')) {
    if (messaging_template_info($fallback, 'enabled')) {
      return $fallback;
    }
    else {
      return messaging_template_fallback($fallback);
    }
  }
}

/**
 * Get template keys for a group
 * 
 * If a group has no keys, goes through the fallback system (using default fallbacks)
 */
function messaging_template_get_keys($name, $language = NULL) {
  $keys = messaging_template_invoke_all('keys', $name, $language);
  if (!$keys && ($fallback = messaging_template_fallback($name))) {
    return messaging_template_get_keys($fallback, $language);
  }
  else {
    return $keys;
  }
}

/**
 * Do token replacement.
 * Was messaging_text_replace()
 * 
 * Uses token_logic if enabled, standard token replacement otherwise
 */
function messaging_template_text_replace($text, $objects, $language = NULL) {

  // If empty text, nothing to replace
  if (is_string($text) && !trim($text)) {
    return '';
  }

  // Add some token types
  $objects['global'] = NULL;

  // Use token_logic if available, ttp://code.developmentseed.org/token_logic
  // Otherwise use standard contrib token module, http://drupal.org/project/token
  if (module_exists('token_logic')) {
    return token_logic_replace_multiple($text, $objects);
  }
  else {
    return token_replace_multiple($text, $objects);
  }
}

/**
 * Get message template parts from database as objects
 * 
 * @param $type
 *   Template type
 * @param $method
 *   Optional method, to get them only for this method
 * @param $language
 *   Optional language, instead of default
 */
function messaging_template_get_parts($name, $method = NULL, $language = NULL) {
  $language = $language ? $language : language_default();
  if ($method) {
    $templates[$method] = array();
    $result = db_query("SELECT * FROM {messaging_template_text} WHERE name = '%s' AND  method = '%s' AND language = '%s'", $name, $method, $language->language);
  }
  else {
    $templates = array();
    $result = db_query("SELECT * FROM {messaging_template_text} WHERE name = '%s' AND language = '%s'", $name, $language->language);
  }
  while ($part = db_fetch_object($result)) {
    $templates[$part->method][$part->msgkey] = $part;
  }
  return $method ? $templates[$method] : $templates;
}

/**
 * Get text part with full data, handling fallbacks
 * 
 * @return
 *   Full text part object, FALSE if not found
 */
function messaging_template_get_template($name, $method, $key, $language, $default = TRUE, $fallback = TRUE) {
  static $cache;
  if (!isset($cache[$language->language][$name][$method])) {
    $cache[$language->language][$name][$method] = messaging_template_get_parts($name, $method, $language);
  }
  $template = FALSE;
  if (!isset($cache[$language->language][$name][$method][$key])) {
    if ($default) {

      // Go for the default method or the default from modules
      if ($method_default = messaging_template_method_default($method)) {
        $template = messaging_template_get_template($name, $method_default, $key, $language, $default, $fallback);
      }
      elseif ($defaults = messaging_template_get_defaults($name, $method, $language)) {
        $template = isset($defaults[$key]) ? $defaults[$key] : FALSE;
      }
    }
  }
  else {
    $template = $cache[$language->language][$name][$method][$key];
  }

  // Still go for the fallback if no template or template is 'fallback'
  if ((!$template || $template->options == MESSAGING_STATUS_FALLBACK) && $fallback && ($name_fallback = messaging_template_fallback($name))) {
    return messaging_template_get_template($name_fallback, $method, $key, $language, $default, $fallback);
  }
  else {
    return $template;
  }
}

/**
 * Get method fallback
 */
function messaging_template_method_default($method) {
  return $method == 'default' ? FALSE : 'default';
}

/**
 * Get default text defined by modules
 * 
 * @param $type
 *   Template type
 * @param $language
 *   Optional key to retrieve default for
 * @param $fallback
 *   Whether to get all defaults recursing through fallbacks
 */
function messaging_template_get_defaults($name, $language = NULL, $fallback = FALSE) {
  static $cache;
  if (!isset($cache[$language->language][$name])) {
    $cache[$language->language][$name] = array();
    foreach (messaging_template_invoke_all('defaults', $name, $language) as $key => $value) {

      // Some value may be an array of text lines, implode before storing
      $cache[$language->language][$name][$key] = (object) array(
        'template' => is_array($value) ? implode("\n", $value) : $value,
        'options' => MESSAGING_TEMPLATE_DEFAULT,
        'type' => $name,
      );
    }
  }

  // If fallback, merge recursively all defaults for this template's fallbacks
  if ($fallback && ($name_fallback = messaging_template_fallback($name))) {
    return $cache[$language->language][$name] + messaging_template_get_defaults($name_fallback, $language, TRUE);
  }
  else {
    return $cache[$language->language][$name];
  }
}

/**
 * Invoke messaging_template hook on all modules
 * 
 * The language will default to default language
 */
function messaging_template_invoke_all($op, $type = NULL, $language = NULL) {
  $language = $language ? $language : language_default();
  $result = module_invoke_all('messaging_template', $op, $type, $language->language);
  return $result;
}

/**
 * Implementation of hook_messaging_template();
 * 
 * Provide a basic template, usefull as a fallback and for tests
 * 
 * @param $op
 *   Operation, type of information to retrieve
 * @param $type
 *   Template type
 */
function messaging_template_messaging_template($op, $type = NULL, $langcode = NULL) {
  switch ($op) {
    case 'types':
      $info['messaging'] = array(
        'title' => t('Messaging template', array(), $langcode),
        'description' => t('Fallback for all templates.', array(), $langcode),
      );
      return $info;
    case 'templates':

      // Generic notifications event
      $info['messaging-template'] = array(
        'module' => 'messaging_template',
        'type' => 'messaging',
        'title' => t('Messaging template', array(), $langcode),
        'description' => t('Fallback for all message templates.', array(), $langcode),
      );
      return $info;
    case 'keys':
      if ($type == 'messaging-template') {
        return array(
          'subject' => t('Subject', array(), $langcode),
          'header' => t('Header', array(), $langcode),
          'main' => t('Content', array(), $langcode),
          'footer' => t('Footer', array(), $langcode),
        );
      }
      break;
    case 'defaults':

      // Event notifications
      if ($type == 'messaging-template') {
        return array(
          'subject' => t('Message for [user] from [site-name]', array(), $langcode),
          'header' => t("Greetings [user],", array(), $langcode),
          'main' => t("This is a test message from [site-name]", array(), $langcode),
          'footer' => array(
            t('This is an automatic message from [site-name] [site-url]', array(), $langcode),
          ),
        );
      }
      break;
    case 'tokens':
      break;
  }
}

Functions

Namesort descending Description
messaging_template_autoload_info Implementation of hook_autoload_info().
messaging_template_fallback Get next enabled template fallback
messaging_template_get_defaults Get default text defined by modules
messaging_template_get_keys Get template keys for a group
messaging_template_get_parts Get message template parts from database as objects
messaging_template_get_template Get text part with full data, handling fallbacks
messaging_template_help Implementation of hook_help().
messaging_template_info Returns information about message template groups, always in default language
messaging_template_invoke_all Invoke messaging_template hook on all modules
messaging_template_menu Implementation of hook_menu()
messaging_template_messaging_template Implementation of hook_messaging_template();
messaging_template_method_default Get method fallback
messaging_template_text_replace Do token replacement. Was messaging_text_replace()
messaging_template_theme Implementation of hook_theme()

Constants

Namesort descending Description
MESSAGING_TEMPLATE_DEFAULT
MESSAGING_TEMPLATE_FALLBACK @file Template system for Messaging Framework
MESSAGING_TEMPLATE_OVERRIDE