Note:

If you want to create a new page for developers, you should create it on the Moodle Developer Resource site.

Messaging 2.0: Difference between revisions

From MoodleDocs
No edit summary
Line 65: Line 65:


In order to configure messaging settings in the site administration menu admin requires <tt>moodle/site:config</tt> permission. User is able to configure personal messaging preferences if <tt>moodle/user:editownmessageprofile</tt> is granted.
In order to configure messaging settings in the site administration menu admin requires <tt>moodle/site:config</tt> permission. User is able to configure personal messaging preferences if <tt>moodle/user:editownmessageprofile</tt> is granted.
===Message types (providers)===
Any plugin can declare any number of message types which can be used on [[Messaging_2.0_improvements#Default_message_outputs|Default message preferences]] and [[Messaging_2.0_improvements#Configuration_for_user|user messaging preferences]] pages. When the particular message type is being [[Messaging_2.0_improvements#Message_dispatching|dispatched]], the delivery method will be chosen based on messaging permissions and preferences defined by admin and user.
====Adding new message type====
====Adding new message type for the core====


===Message outputs (processors)===
===Message outputs (processors)===

Revision as of 15:31, 27 May 2011

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.

Manage message outputs.jpg

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.

Default message outputs.jpg

The default preferences menu for each item is identical and allow administrator to choose permission and default setting when user is logged-in and offline. 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.

Outputs configuration

As it was mentioned earlier, the Message outputs menu contains the configuration for outputs that have system configuration settings. Unless output is configured, it cannot be used in the system.

Note: Former settings Admin > Server > Email and Admin -> Server -> Jabber have been moved to Site Administration > Plugins -> Message outputs. Settings upportname, supportemail and supportpage that were on Email settings page were moved to Site Administration > Server -> Support contact.

Configuration for user

Users may configure the messaging preferences in their profile settings My Profile settings > Messaging. The message preferences are configured in "Configure destinations for incoming messages" box that contain a grid of enabled and configured message outputs and message types user has capabilities to access. If particular combination of message type and output is permitted by administrator, user may change the preferences by ticking off the corresponding boxes.

User message preferences.jpg

Some message outputs may require user configuration (e.g. jabber needs ID to be specified), in which case user will not able to set the preferences for the output unless it is configured on the user level. Message output settings are listed at the bottom of messaging preferences page.

User message preferences settings.jpg

Under the bonnet

Capabilities

In order to configure messaging settings in the site administration menu admin requires moodle/site:config permission. User is able to configure personal messaging preferences if moodle/user:editownmessageprofile is granted.

Message types (providers)

Any plugin can declare any number of message types which can be used on Default message preferences and user messaging preferences pages. When the particular message type is being dispatched, the delivery method will be chosen based on messaging permissions and preferences defined by admin and user.

Adding new message type

Adding new message type for the core

Message outputs (processors)

Each message output is presented as a plugin (see /message/output). The outputs for email, jabber and web-based popups already exist. A new plugin for different messaging delivery method (e.g. twitter or SMS) can be added quite easily.

The typical message output plugin directory looks like:

message/output/jabber/
├── db
│   ├── install.php
│   └── upgrade.php
├── lang
│   └── en
│       └── message_jabber.php
├── lib.php
├── message_output_jabber.php
├── settings.php
└── version.php

message_output class

The plugin should contain message_output_name.php file (e.g. /message/output/jabber/message_output_jabber.php) with message_output_name class (where name is the actual plugin name) that extends an abstract class called message_output in /message/output/lib.php with the methods:

class message_output_name extends message_output {

   function send_message($message) {
      // Given a message object and user info, this actually
      // sends it. This function is called by send_message
      // function in lib/messagelib.php
   }
   function config_form($preferences) {
      // This defines the config form fragment used on user
      // messaging preferences interface (message/edit.php)
   }
   function process_form($form, &$preferences) {
      // This processes the data from the config form fragment
      // (used in message/edit.php)
   }
   function load_data(&$preferences, $userid) {
      // This loads up user config for this plugin set via
      // config form fragment (used in message/edit.php)
   }
   function is_system_configured() {
      // This is an optional method that is supposed to return
      // true if output is configured on the system level
      // for example jabber server settings for jabber plugin.
   }
   function is_system_configured() {
      // This is an optional method that is supposed to return
      // true if output is configured on the user level
      // for example user's jabber ID for jabber plugin.
   }

}

Settings file

If messaging output plugin requires system configuration, it should provide settings.php file with configuration settings. The link to configuration page will be displayed as a part of admin menu tree (in Site Administration > Plugins -> Message outputs) and in the Manage message outputs page. See Admin_settings for more details.

Lanuage file

The plugin should have a message_name.php file (where name is the actual plugin name) in the correct language directory structure with at least one pluginname string with the name of the processor, e.g.:

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

Installation and Upgrade

Like in any other moodle plugin, the message processor plugin should have install and upgrade routines defined in install.php and upgrade.php respectively. At the very list the plugin should register itself in message_processors table which will make it listed on messaging configuration pages. The example content of install.php file for jabber messaging processor is:

function xmldb_message_jabber_install(){

   global $DB;
   $result = true;
   $provider = new stdClass();
   $provider->name  = 'jabber';
   $DB->insert_record('message_processors', $provider);
   return $result;

}

Also the plugin should contain the version.php file. e.g.: $plugin->version = 2008090900; $plugin->requires = 2008091500;

Message dispatching

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.

See also