Notifications/New formatter system

This page contains developer documentation about the new formatter system introduced in Gerrit change 232632.

Each notification type needs to implement the EchoEventPresentationModel class. That implementation will have access to the EchoEvent and Language it should be formatted in. The goal is to require each notification type to expose a model, and leave it up to each formatter (Flyout, Email, etc.) to put it in the right format for display.

canRender() - Whether the model is able to represent the notification (default: true). Implementations might return false here if the page the notification was on was deleted for example. If this returns false, no other methods will be called.
getHeaderMessageKey() - Returns the message key for the header (default: "notification-header-{$this->type}"). The default should work for most notification types, only cases where the text depends upon other values (like mentions being able to detect the section) should this be overridden.
getHeaderMessage() - Returns a Message object for the header. The default implementation adds the formatted username and gender username of the event's agent as parameters to the message, and then returns it. Subclasses should call the parent implementation, and then add extra parameters. For example:

public function getHeaderMessage() {
    $msg = parent::getHeaderMessage();
    $msg->params( ... );
    return $msg;
}

getBodyMessage() - Returns a Message object for the body or false if the notification has no body. The default implementation returns false.
getCompactHeaderMessageKey() - Returns the message key for the compact header (default: "notification-compact-header-{$this->type}").
getCompactHeaderMessage() - Returns a Message object for the header. The default implementation falls back to using getHeaderMessage. The compact header is shown when a notification is part of an expandable bundle. It should be shorter than the header and complement what getHeaderMessage returns when it is bundled.
getSubjectMessageKey() - Returns the message key for the email subject (default: "notification-subject-{$this->type}").
getSubjectMessage() - Returns a Message object for the email subject. The default implementation falls back to using getHeaderMessage. This is the subject line for single-notification emails.
getPrimaryLink() - Should return an array with the following format:

array(
    'url' => url,
    'label' => link text
)

The URL may be a relative one, and the link text should not be escaped yet.

getSecondaryLinks() - (Optional) Should return an array of arbitrary length in the following format:

array(
    'url' => url,
    'label' => link text,
    'description' => description,
    'icon' => icon url or false,
    'prioritized' => whether the link should appear in the notification area or if it can be hidden inside a menu
)

Like before, the URL may be relative, and the link text should not be escaped yet. An arbitrary number of secondary links can be provided.

Notifications/New formatter system

See also