Once you've imported the module, you can then use the
PopupNotifications object it exports; this object provides methods for creating and displaying popup notification panels.
The consumer can call this method to let the popup notification module know that the current browser's location has changed. This lets the notification service update the active notifications as appropriate.
Retrieve a Notification object associated with the browser/ID pair.
NotificationgetNotification( string id XULElement browser );
NotificationID to search for.
- The XUL
<xul:browser>element whose notifications should be searched. If
null, the currently selected
<xul:browser>'s notifications will be searched.
Notification object, or
null if no such notification exists.
Removes the specified notification.
void remove( Notification notification );
Notificationobject representing the notification to remove.
Adds a new popup notification, displaying it to the user.
Notification show( browser, id, message, anchorID, mainAction, secondaryActions, options );
- The XUL
<xul:browser>element with which the notification is associated. This must not be
null; you can, however, simply specify
gBrowser.selectedBrowserto associate it with the current tab.
- A unique ID string for the type of notification being displayed. For example, Geolocation related notifications have the ID "geolocation". Only one notification for each ID can be visible at a time; if one with the specified ID already exists, it will be replaced with the newer notification.
- A string to display in the notification panel.
- The ID of the element that should serve as the anchor for the notification popup (that is, the element the arrow on the popup should point to). If you specify
null, the notification will be anchored to the PopupNotification object's icon box. This anchorID must point to an element contained inside the PopupNotification object's icon box (for Firefox windows, the global PopupNotifications object uses the
- An array of notification action objects; these are used to populate the drop-down menu on the notification panel's button.
Notification object corresponding to the added notification.
Notification action objects describe the user interface for actions associated with the notification. The main action is used to describe the button presented in the notification panel, while secondary actions are displayed in the drop-down menu associated with the button.
A notification action object must contain the following properties:
- A text label describing the action.
- A string indicating the keystroke that will trigger the action.
The notification options object lets you further customize the notification panel. Any combination of the following properties may be provided:
- An integer value indicating the number of page loads for which the notification will persist; once this many page loads have occurred, the notification may dismiss automatically.
- A timestamp (milliseconds since the epoch) indicating the earliest time after which the notification can be automatically dismissed. Notifications that specify a timeout value will not be automatically dismissed until this time. The user may manually dismiss the notification, however. For most use cases, the value of this parameter should be
Date.now()plus an offset indicating the amount of time the notification should be kept open (for example,
Date.now() + 30000for 30 seconds).
- A Boolean value indicating whether or not the notification should persist across location changes. If
true, the notification will remain visible even if the browser navigates to a different location.
- A Boolean value indicating whether or not the notification should be added as a dismissed notification. Dismissed notifications can be activated by clicking on their anchor. This lets you create a notification that will appear when the user clicks the anchor.
- Notifications with this parameter set to true will be removed when they would have otherwise been dismissed (i.e. any time the popup is closed due to user interaction).
- Notifications with this parameter set to
truewill be removed when they would have otherwise been dismissed (that is, any time the popup is closed due to user interaction).
- A string specifying the URL of the image to be displayed in the popup. This is normally specified in CSS using
- A string URL. Setting this property will make the prompt display a "Learn More" link that, when clicked, opens the URL in a new tab.
If you specify an event callback using the
options parameter when calling
show(), the callback function gets invoked when the state of the notification changes. The first parameter to the callback is a string identifying the state change, and may be one of the following:
- The notification has been dismissed by the user (for example, by clicking away or by switching tabs). This is different from "removed", in that the notification can be redisplayed.
- The notification has been removed, either by the user taking action on the notification or by the browser being navigated to a new location.
- The notification is about to be shown. The callback code can modify the notification message/actions if necessary during this notification.
- The notification has become visible. This can be fired multiple times as notifications are dismissed and redisplayed.
The Notification object
Each notification is represented by a
Notification object. This object contains all the data necessary to present and manage the notification, and has one method. The
anchorElement property returns the notification's anchor element. The
remove()method removes the notification.