Messaging custom components

Note: This page is a work-in-progress. Feedback and suggested improvements are welcome. Please join the discussion on moodle.org or use the page comments.

Intro

Since Moodle 2.0 it has been possible to have custom components send notifications and process a user's received messages via the Moodle messaging system. There are two types of components you may wish to implement.

• message providers - These create new messages and send them via the messaging system.
• message processors - These are optionally used by message recipients and receive and process messages sent to that user.

Instructions on how to build a message provider or message processor as well as sample code of each are below.

Message provider

Any component may be a messages provider. The messages produced by a message provider is defined in the /db/messages.php file of a component. Below is the quiz's messages.php as an example. defined('MOODLE_INTERNAL') || die(); $messageproviders = array (

   // Notify teacher that a student has submitted a quiz attempt
   'submission' => array (
       'capability'  => 'mod/quiz:emailnotifysubmission'
   ),
   // Confirm a student's quiz attempt
   'confirmation' => array (
       'capability'  => 'mod/quiz:emailconfirmsubmission'
   )

);

The quiz can send two kinds of messages, quiz "submission" and "confirmation" notifications. Each message type is only available to users with the appropriate capability. Users who have this capability will have this message listed in their messaging preferences. You can omit the capability section if your message should be visible for all users. For example forum post notifications are available to all users.

$messageproviders = array (

   // Ordinary single forum posts
   'posts' => array (
   )

);

Once your messages.php is complete you need to increase the version number of your component in its version.php. That will cause Moodle to check messages.php looking for new or changed message definitions.

Here is example code showing you how to actually send a message.

       $eventdata = new stdClass();
       $eventdata->component         = 'mod_quiz'; //your component name
       $eventdata->name              = 'submission'; //this is the message name from messages.php
       $eventdata->userfrom          = $USER;
       $eventdata->userto            = $touser;
       $eventdata->subject           = $subject;
       $eventdata->fullmessage       = $message;
       $eventdata->fullmessageformat = FORMAT_PLAIN;
       $eventdata->fullmessagehtml   = ;
       $eventdata->smallmessage      = ;
       $eventdata->notification      = 1;
       message_send($eventdata);

Message processor

A sample custom message processor is available from github.

Your message processor lives at /message/output/mymessageprocessor. The directory structure of a message processor is below.

/message/output/mymessageprocessor

                                 /message_output_mymessageprocessor.php
                                 /version.php
                                 /lib.php (optional)
                                 /lang/
                                      /en/ (en for English)
                                         /message_mymessageprocessor.php
                                 /db/
                                    /install.php
                                    /upgrade.php

It should contain a class that extends message_output. message_output can be found in /message/output/lib.php In the above example the class is called message_output_mymessageprocessor and is defined in message_output_mymessageprocessor.php.

Set the version number for your message processor. This is a number formatted like 201106210.00 Reading this from the left this is 2011, june 21st with several extra digits to allow for multiple versions to be produced on the same day. That sometimes happen with core Moodle components but these numbers will usually be zeros. Your version number appears once in mymessageprocessor/version.php and twice in mymessageprocessor/db/upgrade.php

You will see this in mymessageprocessor/version.php $plugin->requires = 2011060200.00; This is the Moodle version that your processor requires. Go to Moodle's own version.php in the top level directory of your Moodle install, copy Moodle's version number and copy it over the value currently in $plugin->requires. This means that any Moodle installation using your message processor must be at least the same Moodle version as you are currently using.

When you log in as administrator and you should be prompted to upgrade. The upgrade process will install your new message processor. The upgrade code can be found in /message/output/mymessageprocessor/db/upgrade.php. At a minimum it should insert a row into the message_processors table.