Notifications/Developer guide

The Notifications tool (formerly code-named Echo), gives MediaWiki users quick updates about actions that affect them. These notifications can help users become more aware of events that relate to them and take quick action if they want to.

This document is intended for MediaWiki extension developers and describes how to extend a MediaWiki extension to use the Notifications system. Currently, the following MediaWiki extensions are using the Echo extension to send notifications:


 * Thanks, to send thanks notifications to users for specific revisions.
 * GettingStarted, to invite new users to start editing articles.
 * PageTriage, to send notifications that indicate whether a page is reviewed and approved, reviewed with issues, or reviewed and nominated for deletion.

For more information about the Notification system, please see the project home page.

Implementing notifications: Step-by-step
1. Do you need notifications?

Although any extension can use the Notification system to send messages, please do not do so unless necessary. Make sure that your notification will not spam users, or overlap with another notification (e.g., sent a message to auser if she is mentioned on her talk page, and another message to alert her that she has a new talk message). Notifications should not duplicate each other, and one should bow out if there is an overlap.

2. Choose or create a notification category

Each notification must be assigned to a category, which defines the notification preferences (e.g., opt-in or opt-out; inline or email notification). The notification can be assigned to an existing category, or to a custom category. See for more information.

3. Define the notification

Each notification is defined with an array of keys and values. Please see for more information.

4. Choose or create a notification formatter-class

The formatter-class is the engine that defines how to turn an event into a string that the end-user reads. The value is specified in the notification definition and should be set to the name of a php class (either predefined or customized). See section for more information.

5. Hook the notification into Echo

Once the notification is defined, it can be hooked into echo with the BeforeCreateEchoEvent and EchoGetDefaultNotifiedUsers  hooks. Please see for more information.

6. Set up a trigger for the notification

To trigger the notification, use the EchoEvent::create function call, either as part of the extension code (if the extension creates an interface) or in a hook to an existing part of the MediaWiki software. For more information, please see.

7. Monitor the notification

Once the notification has been implemented, monitor its behavior to ensure that it is not spamming users. If it seems to be generating an excessive number of notifications, you might want to rate-limit the event that is generating the notification or ensure that the notification is opt-in only.

Notification categories
Every notification must be assigned to a category, which defines the notification preferences (e.g., opt-in or opt-out; inline or email notification). The notification category can also be used to specify user groups that are eligible to receive the notification, the priority of the notification, and a help tip. Note that multiple notifications can be assigned to a single category.

The assigned category can be one that is predefined by the Echo extension, or a customized category see. Predefined categories include:

Category Description system Notifications about events that are not triggered by another Wikipedia user (e.g., a user-rights change, account creation, or email registration), are included in the system category. Note that events in the system category cannot be turned off via notification preferences. other Do not use this category! If no category has been assigned to a notification, the ‘other’ category is assigned by default. The other category has no associated preferences, cannot be dismissed, and is not useful in analytics.

Creating a new category
Each category definition consists of an array of keys and values. The following is an example of category definition used by the Thanks extension:

$notificationCategories['edit-thank'] = array(           'priority' => 3,            'tooltip' => 'echo-pref-tooltip-edit-thank',        );

Note that all category parameters are optional:

Notification category parameters
Parameter Required? Value priority no The priority determines the precedence of the notification in batch lists, email delivery and lists [what lists? The flyout menu? something else?]. The value is an integer between 1 and 10. The default is 10, the lowest priority. Usually, there is no need to set this parameter. no-dismiss no If set, the no-dismiss parameter specifies that a notification cannot be turned off with a user’s notification preferences. We strongly recommend that notifications can be dismissed. The value is an array of output formats or an array containing ‘all’ (e.g., 'no-dismiss' => array( 'all' ) or 'no-dismiss' => array( 'web' ). The following output formats are used: web, email. Is that right? Are there more? tooltip no The tooltip defines the format of the help message that appears when users mouse-over the question mark- icon that appears beside the notification category in the user interface. The value is an I18n string key. usergroups no The usergroups parameter specifies a particular user group (e.g., admins) who are eligible to receive the notifications in the category. If unspecified, all groups are eligible.

Defining a notification
Each notification consists of a title, payload, and timestamp:

Title: The title is a simple string that conveys a piece of information to a user. It may include links, or may have no data or link associated.

Payload: The payload contains secondary data that augments the notification, e.g., an edit summary or a snippet of content such as the first ten words of a contribution.

Timestamp: The timestamp reflects the time the notification was generated. The timestamp may also contain a link to a secondary call to action.

The notification appears in the flyout menu beside the user name as well as on the user’s Notification page and, if email notification preference is set to on, as an email message. Note that the notification can be customized for each of these instances via the notification parameters.

Each notification definition consists of an array of keys and values. The following is an example of the Thanks notification definition. Note that the notification and the category have the same name (‘edit-thank’), as the Thanks notification is the only notification for this category:

$notifications['edit-thank'] = array(           'category' => 'edit-thank',            'group' => 'positive',            'formatter-class' => 'EchoThanksFormatter',            'title-message' => 'notification-thanks',            'title-params' => array( 'agent', 'difflink', 'title' ),            'flyout-message' => 'notification-thanks-flyout',            'flyout-params' => array( 'agent', 'difflink', 'title' ),            'payload' => array( 'summary' ),            'email-subject-message' => 'notification-thanks-email-subject',            'email-subject-params' => array( 'agent' ),            'email-body-message' => 'notification-thanks-email-body',            'email-body-params' => array( 'agent', 'title', 'difflink', 'email-footer' ),            'email-body-batch-message' => 'notification-thanks-email-batch-body',            'email-body-batch-params' => array( 'agent', 'title' ),            'icon' => 'gratitude', );

Notification parameters
Parameter Required? Value category yes The notification category defines the preferences for the notification (e.g., opt-in or opt-out, inline or email notification). The Echo extension has several predefined categories, or you may define a new category. See for more information. group no The group parameter is used for analytical purposes and does not affect the behavior of the notification. It’s value may be set to: ‘positive’ for an encouraging notification (e.g., welcome or thanks message) ‘negative’ for negative feedback (e.g., edit reverted) ‘neutral’ neither good nor bad (e.g., page linked, user rights changed) The default is neutral.

WHAT ABOUT INTERACTIVE as group value?

formatter-class yes The formatter-class is the engine that defines how to turn an event into a string that the end-user reads. The value should be set to the name of a php class (either predefined or customized). See [#formatter-class section] for more information. title-message yes The title-message defines the main message (a.k.a., title) of the notification. The value is an i18n key. title-params yes? The title-params parameter defines an array of data used in the notification title. (e.g.,    'title-params' => array( 'agent', 'difflink', 'title' ). Predefined title parameters include: agent (the user responsible for triggering the notification, e.g., the user who sent thanks) difflink (the link to edit view) title  (title of article)

subject-anchor?? number? flyout-message no The flyout-parameter is an optional parameter that defines the format of the notification when it appears in the flyout menu. If set, the value of this parameter will override the format specified by the title-message parameter. Ideally, the flyout-message should contain one call to action and no more than two. The flyout-message itself is a single link to the call to action. The value is an i18n key. flyout-params no The flyout-params parameter defines array of data that gets plugged into the flyout-notification message. Predefined parameters include: agent (the user responsible for triggering the notification, e.g., the user who sent thanks) difflink (the link to edit view) title (title of article)

payload yes? The payload parameter describes the kind of data in the payload section of the notification (e.g., ‘summary’ is an edit summary). The value should be set to the name of a payload type (either predefined or customized). See [#payload section] for more information. email-subject-message yes The email-subject-message parameter defines the format of the subject line used when the notification is sent by email. email-subject-params yes The email-subject-params define array of data that gets plugged into the email-subject-message. Predefined parameters include: agent (the user responsible for triggering the notification, e.g., the user who sent thanks) difflink (the link to edit view) title (title of article)

email-body-message yes The email-body-message defines the format of the portion of the notification that appears in the email body. The value is an value is I18n key. email-body-params yes The email-body-params define array of data that gets plugged into the email body. Predefined parameters include: agent (the user responsible for triggering the notification, e.g., the user who sent thanks) difflink (the link to edit view) title (title of article) email-footer ?

email-body-batch-message no The email-body-batch-message defines the format of the notification when it appears in a batch email. The value is an i18n key.

Is that right? email-body-batch-params no The email-body-batch-params define array of data that gets plugged into the body of the notification when it appears in a batch email. Predefined parameters include: agent (the user responsible for triggering the notification, e.g., the user who sent thanks) title (title of article)

icon no The icon parameter defines the icon used with the notification. The value is a path to the icon image. The icon may be a pre-existing one defined in Echo or a custom one. See [#icons] for more information. bundle no The bundle parameter controls the bundling behavior. If set, related notifications are grouped together. The value is ???

bundle-message no include this? I just noticed them, wasn’t sure, figured I’d ask. bundle-params no include this? I just noticed them, wasn’t sure, figured I’d ask.

Icons
Predefined icons

The following icons are defined by the Echo extension and may be used by additional notifications. You may create a customized icon.

Is there anything more we should say about usage for each of these? Icon Name/Usage Generic.png Deletion.png Talk.png CrossReferenced.png Featured.png Reviewed.png ReviewedWithTags.png Revert.png Gratitude.png

From: https://github.com/wikimedia/mediawiki-extensions-Echo/blob/master/modules/icons/Generic.png

Creating a new icon
Any rules about icon image itself? size/color/etc. Anything more to say? Maybe don’t need this section

Payloads
Predefined payloads [need list of predefined payloads]

Payload Description tk tk tk tk

Creating a new payload What to say here? Maybe don’t need this section.

Notification formatter-classes

The formatter-class is the engine that defines how to turn an event into a string that the end-user reads. The value should be set to the name of a php class (either predefined or customized). Predefined formatter-classes [need predefined formatter-classes]

Built in formatters: list existing formatting classes/what they handle/ and some examples. > BasicFormatter.php (extends existing formatters;; most examples)

Formatter-class Description tk tk tk tk

Creating a new formatter-class

New formatter-classes can be developed as part of your extension and referred to via the notification’s ‘formatter-class’ parameter.

New classes extend the EchoBasicFormatter and each must have a processParam function, which handles each key and sends it off to the function that handles it. Note that the processParam function must include an ‘else’ statement to capture cases not handled by the function’s ‘if’ statements. Unhandled cases should be directed up to the parent class.

The following example is from the Thanks extension:

class EchoThanksFormatter extends EchoBasicFormatter {

/**    * @param $event EchoEvent * @param $param * @param $message Message * @param $user User */   protected function processParam( $event, $param, $message, $user ) { if ( $param === 'difflink' ) { $eventData = $event->getExtra; if ( !isset( $eventData['revid'] ) ) { $message->params( '' ); return; }           $this->setTitleLink(                $event,                $message,                array( 'class' => 'mw-echo-diff', 'linkText' => wfMessage( 'notification-thanks-diff-link' )->text, 'param' => array(                       'oldid' => $eventData['revid'],                        'diff' => 'prev',                    ) )           );        } else { parent::processParam( $event, $param, $message, $user ); }   } }

Hook the notification into the Echo extension
To hook your notification to the Echo extension, use the following two hooks:

Hook Description BeforeCreateEchoEvent Used to pass Echo your definition for the notification category and the notification definition itself. EchoGetDefaultNotifiedUsers Used to define who gets the notifications (e.g., the user who created the edit)

Example from Thanks: Should we include this example? Or is this not very useful? Something more generic?

public static function onBeforeCreateEchoEvent( &$notifications, &$notificationCategories, &$icons ) { $notificationCategories['edit-thank'] = array(           'priority' => 3,            'tooltip' => 'echo-pref-tooltip-edit-thank',        );

$notifications['edit-thank'] = array(           'category' => 'edit-thank',            'group' => 'positive',            'formatter-class' => 'EchoThanksFormatter',            'title-message' => 'notification-thanks',            'title-params' => array( 'agent', 'difflink', 'title' ),            'flyout-message' => 'notification-thanks-flyout',            'flyout-params' => array( 'agent', 'difflink', 'title' ),            'payload' => array( 'summary' ),            'email-subject-message' => 'notification-thanks-email-subject',            'email-subject-params' => array( 'agent' ),            'email-body-message' => 'notification-thanks-email-body',            'email-body-params' => array( 'agent', 'title', 'difflink', 'email-footer' ),            'email-body-batch-message' => 'notification-thanks-email-batch-body',            'email-body-batch-params' => array( 'agent', 'title' ), 'icon' => 'gratitude', );

return true; }

>EchoGetDefaultNotifiedUsers example from Thanks: Should we include this example? Or is this not very useful?

public static function onEchoGetDefaultNotifiedUsers( $event, &$users ) { switch ( $event->getType ) { case 'edit-thank': $extra = $event->getExtra; if ( !$extra || !isset( $extra['thanked-user-id'] ) ) { break; }               $recipientId = $extra['thanked-user-id']; $recipient = User::newFromId( $recipientId ); $users[$recipientId] = $recipient; break; }       return true; }

Create the notification via the Echo extension
To trigger the notification, use the EchoEvent::create function call, either as part of the extension code (if the extension creates an interface) or in a hook to an existing part of the MediaWiki software.

The EchoEvent::create function assigns data passing in to notification to NOT SURE HOW TO DESCRIBE WHAT THIS DOES

The following example is used by the Thanks extension:

EchoEvent::create( array( 'type' => 'edit-thank', 'title' => $title, 'extra' => array(                       'revid' => $rev->getId,                        'thanked-user-id' => $recipient,                        'source' => $source,                    ), 'agent' => $agent, ) );

All create function calls must have a ‘type’ parameter; the rest of the parameters are optional and depend on the notification.

Predefined Create parameters
Create Parameter Required? Value type yes The type of notification. ??? variant no An alternate notification (e.g., a version to be sent to an admin user group) agent no The user who triggered the notification title no Title of page extra no Anything else! The ‘extra’ parameter supports any additional data required (e.g., the revision id of a page)

Opt-in is best
In general, notifications should be opt-in unless they are a critical component of site building and it’s imperative that everyone get them. If the $DefaultUserOptions are set to ‘true’, users must opt out if they do not wish to receive the notification. If the If the $DefaultUserOptions are set to ‘false’, users must opt in to receive the notification.

Rate-limit notification-generating events
To control the number of notifications sent, you can rate-limit the event that generates the notification (e.g., limit a user to 10 or fewer thanks events per minute)