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 returnfalse
here if the page the notification was on was deleted for example. If this returnsfalse
, 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 aMessage
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 aMessage
object for the body orfalse
if the notification has no body. The default implementation returnsfalse
.getCompactHeaderMessageKey()
- Returns the message key for the compact header (default:"notification-compact-header-{$this->type}"
).getCompactHeaderMessage()
- Returns aMessage
object for the header. The default implementation falls back to usinggetHeaderMessage
. The compact header is shown when a notification is part of an expandable bundle. It should be shorter than the header and complement whatgetHeaderMessage
returns when it is bundled.getSubjectMessageKey()
- Returns the message key for the email subject (default:"notification-subject-{$this->type}"
).getSubjectMessage()
- Returns aMessage
object for the email subject. The default implementation falls back to usinggetHeaderMessage
. 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.