CloudServices/Sync/FxSync/Developer/Notifications

Back to Labs/Weave.

Weave's Notification System

Weave's notification system consists of a JavaScript module that keeps track of notifications for the user, an icon in the statusbar that appears next to the Weave status button when notifications are available, and a modified notificationbox inside a panel that pops up to display current notifications when the user clicks the icon.

To add or remove a notification, import the JavaScript module, then use its add and remove methods:

Cu.import("resource://weave/notifications.js");
Notifications.add(myNotification);
Notifications.remove(myNotification);

Alternately, if you've imported the service module (as does the sync.xul overlay), you can access the module through the Weave object:

Cu.import("resource://weave/service.js");
Weave.Notifications.add(myNotification);
Weave.Notifications.remove(myNotification);

Notifications are simple objects with title, description, iconURL, priority, and buttons properties. You can create one with the Notification constructor or as a literal object:

// These objects are equivalent.
let someNotification = new Notification("Something Happened",
                                        "We wish to inform you of something.",
                                        "",
                                        Notifications.PRIORITY_INFO,
                                        someButtons);
let someOtherNotification = { title:       "Something Happened",
                              description: "We wish to inform you of something.",
                              iconURL:     "",
                              priority:    Notifications.PRIORITY_INFO,
                              buttons:     [button1, button2] };

Only the title and description arguments are required. Priority constants are properties of the Notifications object. The default priority is PRIORITY_INFO. Other options are PRIORITY_WARNING and PRIORITY_ERROR. If you don't specify an icon URL, the system will assign one based on the priority.

The buttons argument specifies buttons to appear underneath the description in the notification. Buttons are objects with label, accessKey, and callback properties. You can create one with the NotificationButton constructor or a literal object:

// These objects are equivalent.
let someButton = new NotificationButton("ok whatever",
                                        "o",
                                        function() { ... });
let someOtherButton = { label:     "ok whatever",
                        accessKey: "o",
                        callback:  function() { ... } };

The callback argument takes a JavaScript function that will be called when the user presses the button. It takes two arguments, a reference to the DOM notification node responsible for displaying the notification, and a reference to the NotificationButton object. Return false from the callback to close the notification, true to leave it open.

Notifications tells observers when notifications are added or removed. To observe those notifications, use the observer service to register as an observer of the weave:notification:added and weave:notification:removed notifications via the Observers module.

The Notifications module also has a replace method that replaces one notification with another:

Notifications.replace(oneNotification, anotherNotification);

Unlike the add and remove methods, the replace method does not notify observers about the change.

If you need to display more than a simple title, description, and set of buttons, you can create a custom notification. Custom notifications are more complicated, as you have to create an XBL binding to define the appearance and subclass the Notification object to represent the notification. See the TabsNotification XBL binding in notification.xml and the TabsNotification object in notifications.js for an example of a custom notification.