PopupNotifications.jsm

  • Revision slug: JavaScript_code_modules/PopupNotifications.jsm
  • Revision title: PopupNotifications.jsm
  • Revision id: 54992
  • Created:
  • Creator: saneyuki_s
  • Is current revision? No
  • Comment 62 words added, 25 words removed

Revision Content

{{ gecko_minversion_header("2.0") }}

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

popupnotification.png

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.

Note: This code module is imported by Firefox chrome windows, so you don't have to do it yourself in most extensions.

Method overview

boolean locationChange();
remove(notification);
Notification show(browser, id, message, anchorID, mainAction, secondaryActions, options);

Properties

Attribute Type Description
isPanelOpen Boolean Returns true if the notification panel is currently visible, false if it is not.

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.

Note: You shouldn't need to call this when using the PopupNotifications object in Firefox windows; Firefox code takes care of this automatically.
boolean locationChange();
Parameters

None.

Return value

true if the notification persisted across the change; otherwise false.

remove()

Removes the specified notification.

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 {{ XULElem("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 (i.e. any time the popup is closed due to user interaction).
popupIconURL {{ fx_minversion_inline("11") }}
A string. URL of the image to be displayed in the popup. Normally specified in CSS using list-style-image and the .popup-notification-icon[popupid=...] selector.

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

{{ languages( { "ja": "ja/JavaScript_code_modules/PopupNotifications.jsm" } ) }}

Revision Source

<p>{{ gecko_minversion_header("2.0") }}</p>
<p>The <code>PopupNotifications.jsm</code> JavaScript code module provides a popup notification box service. This service is used, for example, to display Geolocation related notifications.</p>
<p><img alt="popupnotification.png" class="internal default" src="/@api/deki/files/4905/=popupnotification.png"></p>
<p>To use this, you first need to import the code module into your JavaScript scope:</p>
<pre>Components.utils.import("resource://gre/modules/PopupNotifications.jsm");
</pre>
<p>Once you've imported the module, you can then use the <code>PopupNotifications</code> object it exports; this object provides methods for creating and displaying popup notification panels.</p>
<div class="note"><strong>Note:</strong> This code module is imported by Firefox chrome windows, so you don't have to do it yourself in most extensions.</div>
<h2>Method overview</h2>
<table class="standard-table"> <tbody> <tr> <td><code>boolean <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#locationChange()" title="en/JavaScript code modules/PopupNotifications.jsm#locationChange()">locationChange</a>();</code></td> </tr> <tr> <td><code><a href="/en/JavaScript_code_modules/PopupNotifications.jsm#remove()" title="en/JavaScript code modules/PopupNotifications.jsm#remove()">remove</a>(notification);</code></td> </tr> <tr> <td><code>Notification <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#show()" title="en/JavaScript code modules/PopupNotifications.jsm#show()">show</a>(browser, id, message, anchorID, mainAction, secondaryActions, options);</code></td> </tr> </tbody>
</table>
<h2>Properties</h2>
<table class="standard-table" style="width: auto;"> <tbody> <tr> <td class="header">Attribute</td> <td class="header">Type</td> <td class="header">Description</td> </tr> <tr> <td><code>isPanelOpen</code></td> <td><code>Boolean</code></td> <td>Returns <code>true</code> if the notification panel is currently visible, <code>false</code> if it is not.</td> </tr> </tbody>
</table>
<h2>Methods</h2>
<h3>locationChange()</h3>
<p>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.</p>
<div class="note"><strong>Note:</strong> You shouldn't need to call this when using the PopupNotifications object in Firefox windows; Firefox code takes care of this automatically.</div>
<pre>boolean locationChange();
</pre>
<h6>Parameters</h6>
<p>None.</p>
<h6>Return value</h6>
<p><code>true</code> if the notification persisted across the change; otherwise <code>false</code>.</p>
<h3>remove()</h3>
<p>Removes the specified notification.</p>
<pre>remove(
  Notification notification
);
</pre>
<h6>Parameters</h6>
<dl> <dt><code>notification</code></dt> <dd>The <code>Notification</code> object representing the notification to remove.</dd>
</dl>
<h3>show()</h3>
<p>Adds a new popup notification, displaying it to the user.</p>
<pre>Notification show(
  browser,
  id,
  message,
  anchorID,
  mainAction,
  secondaryActions,
  options
); 
</pre>
<h6>Parameters</h6>
<dl> <dt><code>browser</code></dt> <dd>The XUL {{ XULElem("browser") }} element with which the notification is associated. This must not be <code>null</code>; you can, however, simply specify <code>gBrowser.selectedBrowser</code> to associate it with the current tab.</dd> <dt><code>id</code></dt> <dd>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.</dd> <dt><code>message</code></dt> <dd>A string to display in the notification panel.</dd> <dt><code>anchorID</code></dt> <dd>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 <code>null</code>, 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 <code>notification-popup-box</code> element).</dd> <dt><code>mainAction</code></dt> <dd>A JavaScript object literal containing fields that define the button to draw in the notification panel. See <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#Notification_actions" title="en/JavaScript code modules/PopupNotifications.jsm#Notification actions">Notification actions</a> below for details.</dd> <dt><code>secondaryActions</code></dt> <dd>An array of notification action objects; these are used to populate the drop-down menu on the notification panel's button.</dd> <dt><code>options</code></dt> <dd>A JavaScript object containing optional properties for the notification. See <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#Notification_options" title="en/JavaScript code modules/PopupNotifications.jsm#Notification options">Notification options</a> below for details.</dd>
</dl>
<h6>Return value</h6>
<p>Returns the <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#The_Notification_object" title="en/JavaScript code modules/PopupNotifications.jsm#The Notification object"><code>Notification</code></a> object corresponding to the added notification.</p>
<h2>Notification actions</h2>
<p>Notification action objects describe the user interface for actions associated with the notification. The <strong>main action</strong> is used to describe the button presented in the notification panel, while <strong>secondary actions</strong> are displayed in the drop-down menu associated with the button.</p>
<p>A notification action object must contain the following properties:</p>
<dl> <dt><code>label</code></dt> <dd>A text label describing the action.</dd> <dt><code>accessKey</code></dt> <dd>A string indicating the keystroke that will trigger the action.</dd> <dt><code>callback</code></dt> <dd>A JavaScript function to be invoked when the action is selected by the user.</dd>
</dl>
<h2>Notification options</h2>
<p>The notification options object lets you further customize the notification panel. Any combination of the following properties may be provided:</p>
<dl> <dt><code>persistence</code></dt> <dd>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.</dd> <dt><code>timeout</code></dt> <dd>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 <code>Date.now()</code> plus an offset indicating the amount of time the notification should be kept open (for example, <code>Date.now() + 30000</code> for 30 seconds).</dd> <dt><code>persistWhileVisible</code></dt> <dd>A Boolean value indicating whether or not the notification should persist across location changes. If <code>true</code>, the notification will remain visible even if the browser navigates to a different location.</dd> <dt><code>dismissed</code></dt> <dd>A Boolean value indicating whether or not the notification should be added as a <strong>dismissed notification</strong>. 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.</dd> <dt><code>eventCallback</code></dt> <dd>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 <a href="/en/JavaScript_code_modules/PopupNotifications.jsm#Notification_events" title="en/JavaScript code modules/PopupNotifications.jsm#Notification events">Notification events</a> below.</dd> <dt><code>neverShow</code></dt> <dd>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).</dd> <dt><code>removeOnDismissal</code></dt> <dd>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).</dd> <dt><code>popupIconURL</code> {{ fx_minversion_inline("11") }}</dt> <dd>A string. URL of the image to be displayed in the popup. Normally specified in CSS using <code>list-style-image</code> and the <code>.popup-notification-icon[popupid=...]</code> selector.</dd>
</dl><h2>Notification events</h2>
<p>If you specify an event callback using the <code>options</code> parameter when calling <code>show()</code>, 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:</p>
<dl> <dt>"dismissed"</dt> <dd>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.</dd> <dt>"removed"</dt> <dd>The notification has been removed, either by the user taking action on the notification or by the browser being navigated to a new location.</dd> <dt>"shown"</dt> <dd>The notification has become visible. This can be fired multiple times as notifications are dismissed and redisplayed.</dd>
</dl>
<h2>The Notification object</h2>
<p>Each notification is represented by a <code>Notification</code> object. This object contains all the data necessary to present and manage the notification, and has one method. The <code>anchorElement</code> property returns the notification's anchor element. The <code>remove()</code>method removes the notification.</p>
<h2>See also</h2>
<ul> <li><a href="/en/Using_popup_notifications" title="en/Using popup notifications">Using popup notifications</a></li>
</ul>
{{ languages( { "ja": "ja/JavaScript_code_modules/PopupNotifications.jsm" } ) }}
Revert to this revision