PopupNotifications.jsm

The PopupNotifications.jsm JavaScript code module provides a popup notification box service. This service is used, for example, to display Geolocation related notifications.

To use this, you first need to import the code module into your JavaScript scope:

Components.utils.import("resource://gre/modules/PopupNotifications.jsm");

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.

Method overview

Properties

Methods

locationChange()

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.

void locationChange();

Parameters

None.

getNotification()

Retrieve a Notification object associated with the browser/ID pair.

Notification getNotification(
 string id
 XULElement browser
);

Parameters

id

The Notification ID to search for.

browser

The XUL browser element whose notifications should be searched. If null, the currently selected browser's notifications will be searched.

Return value

The corresponding Notification object, or null if no such notification exists.

remove()

Removes the specified notification.

void remove(
  Notification notification
);

Parameters

notification

The Notification object representing the notification to remove.

show()

Adds a new popup notification, displaying it to the user.

Notification show(
  browser,
  id,
  message,
  anchorID,
  mainAction,
  secondaryActions,
  options
); 

Parameters

browser

The XUL browser element with which the notification is associated. This must not be null; you can, however, simply specify gBrowser.selectedBrowser to associate it with the current tab.

id

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.

message

A string to display in the notification panel.

anchorID

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 notification-popup-box element).

mainAction

A JavaScript object literal containing fields that define the button to draw in the notification panel. See Notification actions below for details.

secondaryActions

An array of notification action objects; these are used to populate the drop-down menu on the notification panel's button.

options

A JavaScript object containing optional properties for the notification. See Notification options below for details.

Return value

Returns the Notification object corresponding to the added notification.

Notification actions

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:

label

A text label describing the action.

accessKey

A string indicating the keystroke that will trigger the action.

callback

A JavaScript function to be invoked when the action is selected by the user.

Notification options

The notification options object lets you further customize the notification panel. Any combination of the following properties may be provided:

persistence

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.

timeout

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() + 30000 for 30 seconds).

persistWhileVisible

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.

dismissed

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.

eventCallback

A JavaScript function to be invoked when the notification changes state. The callback's first parameter is a string identifying the state change that occurred. See Notification events below.

neverShow

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).

removeOnDismissal

Notifications with this parameter set to true will be removed when they would have otherwise been dismissed (that is, any time the popup is closed due to user interaction).

popupIconURL

A string specifying the URL of the image to be displayed in the popup. This is normally specified in CSS using list-style-image and the .popup-notification-icon[popupid=...] selector.

learnMoreURL

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.

Notification events

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:

"dismissed"

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.

"removed"

The notification has been removed, either by the user taking action on the notification or by the browser being navigated to a new location.

"showing"

The notification is about to be shown. The callback code can modify the notification message/actions if necessary during this notification.

"shown"

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.

See also

• Using popup notifications