modules/messaging/DEVELOPER.txt

API.txt - Drupal Module - Messaging
======================================

This is the developer's documentation for the Messaging Framework

Overview of message sending
---------------------------
The messaging module just plays a broker role between the message producing modules, the ones generating the messages, like
notifications and message processor modules, the ones actually sending messages to the user. 
This framework implements both 'push' and 'pull' models for message sending. 
* Push: One module will produce the message and it will be sent using a messaging api function.
  This is typically the model used for mail and SMS messages.
  @see messaging_message_send_user()    
* Pull: One module will peek the messages queued for a user and will fetch a full array of messages
  to be sent. This may be used for IM methods on which messages will be queued waiting for the user to be connected.
  @see messaging_pull_pending()
  
Though the pull method could have been implemented using the model with intermediate buffering, we wanted users to
get notifications in real time, as soon as they are produced when he's connected through IM not having to wait until
next cron run. Thus message providers supporting the pull method will need to implement a way for the messaging module
to look directly at their message queue.

For performance / scalabilty considerations, some modules producing or delivering messages may need queueing mechanisms.
However this module doesn't implement queueing, thus each module using this framework will need to handle its own message
queueing and cron processing.

Message composition
-------------------
This framework aims to provide message sending capabilities to modules independently of the delivery channel eventually
used. However, the message composition and formatting may depend on the method used for delivery:
- Some messaging methods like SMS may impose restrictions on the length of the message thus message texts may need to be
considerably shorter than for others like e-mail.
- The final formatting of the messages may depend also on the channel used so messages are passed as structured data till
the final sending. Though the messaging framework provides some utility functions for message rendering, it is the work of
each specific messaging method module to give final formatting to the message using these functions or not.
  - Example 1: the message body is an array with 'header', 'content' and 'footer' so for text e-mail messages
    a '--' may be inserted for separating the message footer.
  - Example 2: the message may need to be formatted using plain text or HTML

For this custom message composition the messaging framework provides a mechanism for configuring different message parts
for each sending method and it relies on 'tokens' module for token replacement and text substitution. The general method
for message composition for modules producing messages (push model) is:
1. Find out in advance which sending method the user has selected for each specific type of message.
  I.e. the notifications module allows setting the messaging delivery method for each independent subscription
  so notifications are queued for each sending method.
2. Fetch different message part templates depending on the sending method.
3. Run these templates through token replacement providing the right objects as parameters
4. Invoke the messaging module's sending API

@see messaging_message_part()
@see messaging_message_render()

For formatting and security issues, the Input Filters are applied to the message content before the final
message composition. The messaging framework allows to configure a different filter for each method.

@see messaging_message_send_user()
@see messaging_message_filter()

Developing plug-in modules
---------------------------
To develop a new messaging method plug-in for this framework you need:
- To provide method information through the hook_messaging()
- To implement a callback function for message sending

For a module that uses the messaging framework for message sending you need:
- To provide information about the message texts that will be used
- To provide information about the tokens used in these texts
- To call the API sending function for push delivery
- To implement the messaging hook for pull delivery


The messaging hook
--------------------
This is a generic hook that will be used by the messaging framework to gather information
about sending methods and messages.

hook_messaging($op, $arg1, $arg2, $arg3, $arg4)

Depending on $op, which is the operation to perform, these are the parameters and return values:

- 'send methods', Provides information about sending methods
  Returns an array of the form:
  $info['method name'] => array(
     'name' => String. User readable name. Example: t('Mail'),
     'send' => Callback function for message sending (push),
     'type' => Type of messaging method. Combination of MESSAGING_TYPE_PUSH, MESSAGING_TYPE_PULL   
   );

- 'message groups', Provides information about message formats
  Returns an array of the form:
      $info['group-name'] = array(
        'module' => Module low level name. Example: 'notifications,
        'name' => Group name. Example: t('Subscriptions event'),
        'tokens' => Array of token groups used for these messages. Example: array('global', 'subscription', 'user', 'comment'),
      );

- 'message keys', Available message keys for each group, these will be the message parts
  More parameters:
    $group = $arg1 = Group name
  Returns an array of arrays with the form:
    array(
    	'key1' => User readable name of these message part
    	'key2' => "
    	....
   );    
  Example, for event notifications
      return array(
        'subject' => t('Subject for event notifications'),
        'header' => t('Body header for event notifications'),
        'main' => t('Body for event notifications'),
        'footer' => t('Body footer for event notifications'),
      );

- 'messages', Provides default message parts
  More parameters:
    $group = $arg1 = Group name
  Returns an array with default values for each part of this message group.
  Each part may be a message text or an array of message paragraphs.
  Example:
    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]'),
    )

- 'pull', Implements message pulling from queued messages
  More parameters: 
  	$method = Sending method
  	$users = array of user ids
  	$limit = Limit for the number of messages, zero for no limit
  	$delete = Boolean. Whether to delete the retrieved messages or not. Defaults to TRUE.
  Returns an array of messages. Each message will be in turn an array with these elements
  - 'to', destination uid
  - 'from', originating uid
  - 'subject', message subject to be rendered
  - 'body', message body to be rendered
1	API.txt - Drupal Module - Messaging
2	======================================
3
4	This is the developer's documentation for the Messaging Framework
5
6	Overview of message sending
7	---------------------------
8	The messaging module just plays a broker role between the message producing modules, the ones generating the messages, like
9	notifications and message processor modules, the ones actually sending messages to the user.
10	This framework implements both 'push' and 'pull' models for message sending.
11	* Push: One module will produce the message and it will be sent using a messaging api function.
12	This is typically the model used for mail and SMS messages.
13	@see messaging_message_send_user()
14	* Pull: One module will peek the messages queued for a user and will fetch a full array of messages
15	to be sent. This may be used for IM methods on which messages will be queued waiting for the user to be connected.
16	@see messaging_pull_pending()
17
18	Though the pull method could have been implemented using the model with intermediate buffering, we wanted users to
19	get notifications in real time, as soon as they are produced when he's connected through IM not having to wait until
20	next cron run. Thus message providers supporting the pull method will need to implement a way for the messaging module
21	to look directly at their message queue.
22
23	For performance / scalabilty considerations, some modules producing or delivering messages may need queueing mechanisms.
24	However this module doesn't implement queueing, thus each module using this framework will need to handle its own message
25	queueing and cron processing.
26
27	Message composition
28	-------------------
29	This framework aims to provide message sending capabilities to modules independently of the delivery channel eventually
30	used. However, the message composition and formatting may depend on the method used for delivery:
31	- Some messaging methods like SMS may impose restrictions on the length of the message thus message texts may need to be
32	considerably shorter than for others like e-mail.
33	- The final formatting of the messages may depend also on the channel used so messages are passed as structured data till
34	the final sending. Though the messaging framework provides some utility functions for message rendering, it is the work of
35	each specific messaging method module to give final formatting to the message using these functions or not.
36	- Example 1: the message body is an array with 'header', 'content' and 'footer' so for text e-mail messages
37	a '--' may be inserted for separating the message footer.
38	- Example 2: the message may need to be formatted using plain text or HTML
39
40	For this custom message composition the messaging framework provides a mechanism for configuring different message parts
41	for each sending method and it relies on 'tokens' module for token replacement and text substitution. The general method
42	for message composition for modules producing messages (push model) is:
43	1. Find out in advance which sending method the user has selected for each specific type of message.
44	I.e. the notifications module allows setting the messaging delivery method for each independent subscription
45	so notifications are queued for each sending method.
46	2. Fetch different message part templates depending on the sending method.
47	3. Run these templates through token replacement providing the right objects as parameters
48	4. Invoke the messaging module's sending API
49
50	@see messaging_message_part()
51	@see messaging_message_render()
52
53	For formatting and security issues, the Input Filters are applied to the message content before the final
54	message composition. The messaging framework allows to configure a different filter for each method.
55
56	@see messaging_message_send_user()
57	@see messaging_message_filter()
58
59	Developing plug-in modules
60	---------------------------
61	To develop a new messaging method plug-in for this framework you need:
62	- To provide method information through the hook_messaging()
63	- To implement a callback function for message sending
64
65	For a module that uses the messaging framework for message sending you need:
66	- To provide information about the message texts that will be used
67	- To provide information about the tokens used in these texts
68	- To call the API sending function for push delivery
69	- To implement the messaging hook for pull delivery
70
71
72	The messaging hook
73	--------------------
74	This is a generic hook that will be used by the messaging framework to gather information
75	about sending methods and messages.
76
77	hook_messaging($op, $arg1, $arg2, $arg3, $arg4)
78
79	Depending on $op, which is the operation to perform, these are the parameters and return values:
80
81	- 'send methods', Provides information about sending methods
82	Returns an array of the form:
83	$info['method name'] => array(
84	'name' => String. User readable name. Example: t('Mail'),
85	'send' => Callback function for message sending (push),
86	'type' => Type of messaging method. Combination of MESSAGING_TYPE_PUSH, MESSAGING_TYPE_PULL
87	);
88
89	- 'message groups', Provides information about message formats
90	Returns an array of the form:
91	$info['group-name'] = array(
92	'module' => Module low level name. Example: 'notifications,
93	'name' => Group name. Example: t('Subscriptions event'),
94	'tokens' => Array of token groups used for these messages. Example: array('global', 'subscription', 'user', 'comment'),
95	);
96
97	- 'message keys', Available message keys for each group, these will be the message parts
98	More parameters:
99	$group = $arg1 = Group name
100	Returns an array of arrays with the form:
101	array(
102	'key1' => User readable name of these message part
103	'key2' => "
104	....
105	);
106	Example, for event notifications
107	return array(
108	'subject' => t('Subject for event notifications'),
109	'header' => t('Body header for event notifications'),
110	'main' => t('Body for event notifications'),
111	'footer' => t('Body footer for event notifications'),
112	);
113
114	- 'messages', Provides default message parts
115	More parameters:
116	$group = $arg1 = Group name
117	Returns an array with default values for each part of this message group.
118	Each part may be a message text or an array of message paragraphs.
119	Example:
120	array(
121	'subject' => t('Event notification for [user] from [site-name]'),
122	'header' => t("Greetings [user],"),
123	'main' => t("A item to which you are subscribed has been updated"),
124	'footer' => array(
125	t('This is an automatic message from [site-name]'),
126	t('To manage your subscriptions, browse to [subscriptions-manage]'),
127	t('You can unsubscribe at [unsubscribe-url]'),
128	)
129
130	- 'pull', Implements message pulling from queued messages
131	More parameters:
132	$method = Sending method
133	$users = array of user ids
134	$limit = Limit for the number of messages, zero for no limit
135	$delete = Boolean. Whether to delete the retrieved messages or not. Defaults to TRUE.
136	Returns an array of messages. Each message will be in turn an array with these elements
137	- 'to', destination uid
138	- 'from', originating uid
139	- 'subject', message subject to be rendered
140	- 'body', message body to be rendered