|
|
| (17 intermediate revisions by 10 users not shown) |
| Line 1: |
Line 1: |
| ==What is this document?==
| | {{Template:Migrated|newDocId=/docs/apis/core/message/}} |
| | |
| This document describes how to make use of the Moodle Messaging API to send messages to Moodle users.
| |
| | |
| If you are after a general introduction on using the Moodle Messaging system go to [[:en:Messaging|messaging user documentation]].
| |
| | |
| If you are looking for details of how the Messaging system's internal structure was implemented, go to [[Messaging 2.0]].
| |
| | |
| If you are looking for instructions on the implementation of a custom message processor (a component that receives messages sent to a user), go to [[Messaging custom components]].
| |
| | |
| If you are looking for instructions on sending messages programatically within Moodle then read on...
| |
| | |
| ==Overview==
| |
| | |
| Moodle components have the ability to send messages to users via the Moodle messaging system. Any type of component, for example a plugin or block, can register as a message producer then send messages to users.
| |
| | |
| ==File locations==
| |
| | |
| The Message API code is contained within lib/messagelib.php and is automatically included for you during page setup.
| |
| | |
| ==Functions==
| |
| | |
| message_send() is the primary point of contact for the message API. Call it to send a message to a user. You can find a full description of the arguments that must be supplied at (link to phpdocs). There is also an example below.
| |
| | |
| ==Examples==
| |
| | |
| ===How to register as a message producer===
| |
| | |
| The messages produced by a message provider is defined in the /db/messages.php file of a component. Below is code from the quiz module's messages.php file, shown as an example.
| |
| <code php>
| |
| 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'
| |
| )
| |
| );
| |
| </code>
| |
| | |
| 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. Please note that the capability is checked at the system level context. 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.
| |
| | |
| <code php>
| |
| $messageproviders = array (
| |
| // Ordinary single forum posts
| |
| 'posts' => array (
| |
| )
| |
| );
| |
| </code>
| |
| | |
| When displaying your message types in a user's messaging preferences it will use a string from your component's language file called "messageprovider:messagename". For example here are the relevant strings from the quiz's language file.
| |
| <code php>
| |
| $string['messageprovider:confirmation'] = 'Confirmation of your own quiz submissions';
| |
| $string['messageprovider:submission'] = 'Notification of quiz submissions';
| |
| </code>
| |
| | |
| 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. Log in as an admin and go to /admin/index.php (the Notifications page) to start the upgrade process.
| |
| | |
| ===How to send a message===
| |
| | |
| Here is example code showing you how to actually send a message. The example shows the construction of a object with specific properties, which is then passed to the message_send() function that uses the information to send a message.
| |
| <code php>
| |
| $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; //this is only set to 0 for personal messages between users
| |
| message_send($eventdata);
| |
| </code>
| |
| | |
| ==See also==
| |
| * [[Core APIs]]
| |
| | |
| [[Category:API]]
| |
| [[Category:Tutorial]]
| |
| [[Category:Plugins]]
| |
