Notifications/Developer guide

Notifications, as enabled by the Echo Extension, give 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
  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. Notifications should not duplicate each other, and one should bow out if there is an overlap. 

 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; on-wiki or email notification). The notification can be assigned to an existing category or to a new category. See for more information. </li>

 Define the notification</dt> Each notification is defined with an array of keys and values. Please see for more information.</dd> </dl></li>

 Choose or create a notification formatter class</dt> The formatter class is the engine that defines how to turn an event into a message that the end-user reads. It is specified in the notification definition and should be set to the name of a PHP class (either one predefined in Echo or a custom class in your extension). See the section for more information.</dd> </dl></li>

 Hook the notification into Echo</dt> Once the notification is defined, it can be hooked into Echo with the BeforeCreateEchoEvent and EchoGetDefaultNotifiedUsers hooks. Please see for more information.</dd> </dl></li>

 Set up a trigger for the notification</dt> 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 .</dd> </dl></li>

<li><dl> <dt>Monitor the notification</dt> <dd>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.</dd> </dl></li> </ol>

Notification categories
Every notification must be assigned to a category, which defines the notification preferences (e.g., opt-in or opt-out; on-wiki 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. Predefined categories include:

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

You'll also need to set the title of the category in your i18n file - the message key must be of the form "echo-category-title-<category-key>":

Notification category parameters
Note that all category parameters are optional.

Defining a notification
Each notification consists of, at minimum, a title and a timestamp. In addition, a notification may also include a payload and primary and secondary action links.

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.

Timestamp: The timestamp reflects the time the notification was generated.

Primary action link: A link designated as the main action that the user should take in response to a notification. In the flyout interface (the overlay revealed when you click the red notifications badge), the entire notification is clickable and the destination the user is sent to when clicking the notification is defined as the primary link.

Secondary action link: An additional link that may be needed for a notification. Most notifications will not have a secondary link and the use of secondary links is discouraged (to keep the interface simple).

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

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.

TODO: Explain more about customizing for different views

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(    'primary-link' => array( 'message' => 'notification-link-text-respond-to-user', 'destination' => 'agent' ),     'secondary-link' => array( 'message' => 'notification-link-text-view-edit', 'destination' => 'diff' ),     'category' => 'edit-thank',     'group' => 'positive',     'formatter-class' => 'EchoThanksFormatter',     'title-message' => 'notification-thanks',     'title-params' => array( 'agent', 'difflink', 'title' ),     'flyout-message' => 'notification-thanks-flyout2',     'flyout-params' => array( 'agent', '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' => 'thanks', );

Notification parameters
* Will become optional soon

Predefined icons
The following icons are defined by the Echo extension and may be used by additional notifications.

From: https://github.com/wikimedia/mediawiki-extensions-Echo/tree/master/modules/icons

Creating a new icon
Notification icons should be 30x30 pixel monochrome graphics that use the following color scheme:
 * Black for negative actions
 * Green for positive actions
 * Blue for neutral actions

Payloads
A payload adds more descriptive detail to a notification, it is usually located below the notification title in flyout/archive page/email.

Creating/Overwriting a payload
class MyCoolExtensionEchoFormatter extends EchoBasicFormatter { protected function formatPayload( $payload, $event, $user ) { switch ( $payload ) { case 'summary': // generate the $summary return $summary; break; default: return parent::formatPayload( $payload, $event, $user ); break; }    } }

Notification formatter classes
The formatter class is the engine that defines how to turn an event into a message that the end-user reads. The value should be set to the name of a PHP class (either predefined or customized).

Predefined formatter classes
Formatter class provides an abstraction to format and display notification message for all distribution types: flyout, archive page, email and any other future distribution types. A notification only needs to define the messages and parameter tokens for each distribution type, all the formatting work will be handled automatically by the formatter class. There are three pre-defined concrete formatter classes: EchoBasicFormatter, EchoEditFormatter and EchoCommentFormatter, the basic formmater defines common and general parameter tokens for flytout, archive, and email while edit and comment formatter have more specific tokens for edit and comment related actions

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 should extend one of the predefined formatter classes and should have a processParam function, which defines how to handles the message parameters unique to your notification. 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 ); }   } }

Batched email notification
A user can request to receive notification summary in email once in a day or a week. For the summary section in the notification, the message defined in 'email-body-batch-message' is used. For a bundled message, the message defined in 'email-body-batch-bundle-message' is used

Individual email notification
A typical individual email notification consists of four major components: intro, summary, call-to-action and footer


 * intro: the message defined in either 'email-body-batch-message' or 'email-body-batch-bundle-message' for the notification
 * summary: by default, it's the revision snippet if there is any. A notification could provide it to event 'extra' param with 'section-text' key.  A notification could also overwrite getRevisionSnippet method to provide some other custom summary.
 * call-to-action: the message defined in 'primary-link' and 'secondary-link' if any
 * footer: the message defined in either 'echo-email-footer-default-html' or 'echo-email-footer-default'

HTML email also contains an icon component

Bundled notification
Notification can be triggered anywhere from the code. We definitely do not want to spam the user with notifications. In this case, we may want to enable notification bundling. For example, page-link notification is triggered when a page is linked from another page, a popular page may trigger a lot of unwanted notifications. Bundling will help resolving the problem

Define bundling rule
public static function onEchoGetBundleRules( $event, &$bundleString ) { switch ( $event->getType ) { case 'edit-user-talk': $bundleString = 'edit-user-talk'; if ( $event->getTitle ) { $bundleString .= '-'. $event->getTitle->getNamespace. '-' . $event->getTitle->getDBkey; }             break; } }

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

BeforeCreateEchoEvent - Used to pass Echo your definition for the notification category and the notification itself (as well as any custom icons).

Example from Thanks:

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 - Used to define who gets the notifications (for example, the user who performed the edit)

Example from Thanks:

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 defines what data gets passed in to the notification.

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.

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.

TODO: explain how to use $wgDefaultUserOptions to set opt-in or opt-out

Rate-limit notification-generating events
To prevent users from getting spammed by your notification, you can rate-limit the event that generates the notification (e.g., limit a user to 10 or fewer thanks events per minute).

Monitoring
Echo uses EventLogging to track data about notifications. Some graphs of notification data can currently be found at:
 * http://ee-dashboard.wmflabs.org/dashboards/features/#notifications-graphs-tab
 * http://toolserver.org/~dartar/en/echo/
 * http://toolserver.org/~dartar/mw/echo/