Developer documentation
The Messaging framework is a really extensible framework for implementing new sending methods and for use from other modules.
The most up to date documentation will be as usual on the code itself and the messaging API and some of the plug-in modules will be extensively documented.
Message producers
These are the modules using the Messaging framework to actually send out messages to users. For these modules we need to implement the 'messaging' hook to define the different types of templates we are going to use.
Then, they only need to send messages using the Messaging API.
See 'notifications_messaging()' in Notifications for an example of how to define message templates and tokens.
For sending messages, there are a pair API functions.
<?php
/**
* Send message to user represented by account
*
* We are applying same output filter for everybody, depending on send method
*
* The final rendering of the message depends on send method too. I.e. a mail messaging
* method may want to insert '--' before the body footer.
*
* @ TODO Consider whether it makes sense to allow users decide on formatting
*
* @param $account
* User object to recieve message.
* @param $message
* Array of message parts that will be compiled depending on send method.
* Mandatory message parts, which may have nexted parts are:
* - 'type'
* - 'subject'
* - 'body'. The message body may have 'header', 'content', 'footer', 'etc'
* @param $method
* Optional send method. Defaults to the user account predefined method
*/
function messaging_message_send_user($account, $message, $method = NULL, $queue = 0) {
....
}
/**
* Send message to array of destinations. The message is rendered just once.
*
* The $message array may have the following elements
* 'subject' => Message subject, may be already rendered or not
* 'body' => Message content, may be already rendered or not
* 'params' => Optional message params, indexed by sending method group
* I.e. params for mail methods will be in $message['params']['mail']
* 'render' => Optional flag to mark the message subject and body as rendered
* 'sender' => Optional int to identify message sender, may be $user->uid
* 'sender_account' => Optional user account to use as message sender
* @param $destinations
* Array of destinations for sending.
* The element type depends on sending method so it can be a list of e-mail addresses, user accounts, etc
* @param $message
* Message array, not rendered
* @param $method
* Sending method. Unlike for messaging_message_send_user() for which the sending method may be user's default
* it is not an optional parameter for this function.
* @param $queue
* Optional flag, 0 for normal queueing, 1 to force queueing.
* We may want to force queueing for bulk messaging. Otherwise it will depend on the sending method
* wether to queue the messages (for pull methods) or not (push methods)
*/
function messaging_message_send($destinations, $message, $method, $queue = 0) {
....
}
?>Sending methods plug-ins
A messaging method plug-in module for new delivery methods should implement a minimal set of callback functions. It can handle the message delivery itself or it can be just a gateway module relying on other bigger messaging modules (Like Privatemsg module).
The reference implementation for a messaging method plug-in will be the Simple Mail module which is part of the package. That one will be extensively commented.
Contributed plug-ins will be welcomed or if implementing the messaging API from other module in a different package let us know so we can link it from the project main page.
To implement a sending method, we just need to implement the 'messaging' hook ($op = 'sending methods') which should provide all the information for message composition and a valid callback for actual message sending.
<?php
/**
* Implementation of hook_messaging()
*/
function messaging_mail_messaging($op) {
switch($op) {
case 'send methods':
$info['mail'] = array(
'name' => t('Mail'), // Name for display
'group' => 'mail', // Class of sending method
'destination' => 'mail', // Account property to use as destination
'send' => 'messaging_mail_send', // 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;
}
}
?>Then we just need to implement the sending function callback, which will be called by the Messaging module when needed.
<?php
/**
* Send mail message to user account
*
* This is a callback function that will be invoked from messaging delivery methods
*
* @see messaging_message_send()
* @see messaging_mail_params()
* @see drupal_mail()
*
* @param $destination
* Single email address
* @param $message
* Message array
* @param $params
* Optional parameters for this method type
*/
function messaging_mail_send($destination, $message, $params = array()) {
$params = messaging_mail_params($message, $params);
return drupal_mail($params['mailkey'], $destination, $message['subject'], $message['body'], $params['from'], $params['headers']);
}
?>