Messaging 2.0

Enhanced messaging configuration
Project state	implemented, awaiting revision
Tracker issue	MDL-27171
Discussion	http://moodle.org/mod/forum/discuss.php?d=172825
Assignee	Ruslan Kabalin

Moodle 2.0

The page is under construction RIGHT NOW.

This document is an extended version of Messaging_2.0 that contains the documentation on the improved messaging system configuration. This page is supposed to replace Messaging_2.0 once the feature is reviewed and merged into master.

Enhanced messaging system

The messaging system in 2.0 has been revamped significantly:

it is now event-driven;
it allows users to control exactly what messages they receive and how;
it allows administrator to override user settings and set defaults.

Messaging behaviour is controlled by the combination of administrator settings, that define which message outputs are enabled, which outputs can, cannot and should be used for which messages, and user settings that defines which messages user will receive (given that the admin permitted user to control them). The system works graciously when things are not fully configured. For example, jabber notifications can only be send if a Jabber server has been configured, and user has specified his jabber ID in messaging configuration.

Messaging system is enabled by default and controlled via Site Administration > Advanced features > Enable messaging system

Configuration for administrator

There is a dedicated menu item where administrator may configure messaging settings, it is located in Site Administration > Plugins -> Message outputs menu. The menu contains the items for managing messaging outputs, defining default outputs and items for configuring particular outputs like email or jabber.

Manage message outputs

This page summarises which messaging outputs (or processors) you have in the system. You may enable or disable a particular output and proceed to message output system configuration screen. The outputs that are not configured are highlighted and cannot be used in the system (they are not listed in messaging preferences configuration screens). Disabled outputs cannot be used in the system either.

Default message outputs

Default message outputs page is a grid of message outputs (processors) across the top row and message types (providers) across the left column. The intersection cell of particular output and type contains default preferences for chosen messaging type and output.

The default preferences menu for each item is identical and allow administrator to choose permission and default setting when user is logged-in and logged-off. The possible preferences are:

Disallowed - the message of chosen type will never be delivered through the chosen output, user is not allowed to change the personal preference for this combination of message type and output.
Permitted - the message of chosen type is allowed to be delivered through the chosen output, default preferences can be set by administrator using the checkboxes below, user can control this preference on the messaging preferences page (and change the suggested defaults the most preferable way).
Forced - the message of chosen type will be delivered through the chosen output, user is not allowed to change the personal preference for this combination of message type and output.

Configuration for user

Visit your own profile page (you need moodle/user:editownmessageprofile permission). Note that the types of messages listed in the "Configure destinations for incoming messages" box is determined by the contents of the message_providers table.

How it works

Providers (input)

We have Events called "message_send" that look like this:

$eventdata = new object(); $eventdata->component = 'mod_forum'; // the component sending the message. Along with name this must exist in the table message_providers $eventdata->name = 'posts'; // type of message from that module (as module defines it). Along with component this must exist in the table message_providers $eventdata->userfrom = $userfrom; // user object $eventdata->userto = $userto; // user object $eventdata->subject = $postsubject; // very short one-line subject $eventdata->fullmessage = $posttext; // raw text $eventdata->fullmessageformat = FORMAT_PLAIN; // text format $eventdata->fullmessagehtml = $posthtml; // html rendered version $eventdata->smallmessage = ; // useful for plugins like sms or twitter

events_trigger('message_send', $eventdata);

The name of each provider is a string with a name like messageprovider:$name from the component lang file (in this case, forum.php is derived automatically from mod/forum):

$string['messageprovider:posts'] = 'Subscribed forum posts'; $string['messageprovider:digests'] = 'Subscribed forum digests';

More providers can be added throughout Moodle as necessary, it's quite easy. See the Events API for info.

Processors (output)

In /message/output there are full Moodle plugins for each type of output.

Currently we have support for email, jabber and web-based popups. Could add twitter and SMS quite easily.

Each plugin simply extends a class called "message_output" in /message/output/lib.php with methods such as:

function send_message($message) {

  // Given a message object and user info, this actually sends it.

}
function config_form($preferences) {

  // This defines the little form fragment on the config page

}
function process_form($form, &$preferences) {

  // This processes the data from the config form fragment

}
function load_data(&$preferences, $userid) {

  // This loads up prefs for this plugin

}

It should also provide a messageprocessor_xxxxx.php language file (where xxxxx is the name) and inside is an xxxxx string with the name of the processor, like this:

$string['jabber'] = 'Jabber message';

Finally, there should be a lib.php file containing an install routine to install itself as a message processor:

function jabber_install(){

   global $DB;

   $result = true;

   $provider = new object();
   $provider->name  = 'jabber';
   if (!$DB->insert_record('message_processors', $provider)) {
       $result = false;
   }
   return $result;

}

And a version.php file: $plugin->version = 2008090900; $plugin->requires = 2008091500;

Documentation