nsIAlertsService

By default a message is displayed in a small window that slides up from the bottom of the screen, holds there for a few seconds, then slides down. The specific appearance varies from platform to platform.

Implemented by: @mozilla.org/alerts-service;1 as a service:

var alertsService = Components.classes["@mozilla.org/alerts-service;1"]
                    .getService(Components.interfaces.nsIAlertsService);

Method overview

Methods

showAlertNotification()

Displays a notification window.

void showAlertNotification(
  in AString imageUrl,
  in AString title,
  in AString text,
  in boolean textClickable, Optional
  in AString cookie, Optional
  in nsIObserver alertListener, Optional
  in AString name, Optional 
  in AString dir, Optional 
  in AString lang, Optional 
  in AString data, Optional 
  in nsIPrincipal principal, Optional 
  in boolean inPrivateBrowsing, Optional 
);

Parameters

imageUrl

A URL identifying the image to display in the notification alert.

title

The title for the alert.

text

The text to display in the alert, explaining the alert condition. The text must not be too long, otherwise it might be truncated to a platform-specific length. If the text is too long, try to use line returns in the text to have it split and displayed over multiple lines.

textClickable Optional

If true, if the user clicks on it, the listener is notified; when hovered the notification background becomes lighter and the cursor turns to a pointer. Prior to Gecko 32 the
text was made to look like a link.

cookie Optional

A blind cookie the alert passes back to the consumer during alert listener callbacks.

alertListener Optional

An object to receive callbacks from the alert; may be null if you don't care about callbacks. It must implement an observe() method that accepts three parameters:

• subject: always null.
• topic: "alertfinished" when the alert disappears, "alertclickcallback" if the user clicks the text or "alertshow" (since Gecko 22) when the alert is shown.
• data: The value of the cookie parameter passed into the showAlertNotification method.

name Optional

A name for the notification; this is not displayed in the alert. However, certain notification systems (such as Growl on Mac OS X) allow the user to disable alerts by name. This name is used in that configuration panel. On Android the name is hashed and used as a notification ID.

dir Optional

Bidi override for the title. Valid values are "auto", "ltr" or "rtl". Only available on supported platforms.

lang Optional

Language of title and text of the alert. Only available on supported platforms.

data Optional

The value of the cookie parameter passed to showAlertNotification.

principal Optional

The principal of the page that created the alert. Used for IPC security checks, and to determine whether the alert is actionable.

inPrivateBrowsing Optional

Controls the image loading behavior. If true, the image URL will be loaded in private browsing mode.

Exceptions thrown

NS_ERROR_NOT_AVAILABLE

Unable to display the notification; this may happen, for example, on Mac OS X if Growl is not installed.

Example

Simple usage

The following code was used to display the above notification.

var alertsService = Components.classes["@mozilla.org/alerts-service;1"].
                      getService(Components.interfaces.nsIAlertsService);
try {
  alertsService.showAlertNotification("chrome://mozapps/skin/downloads/downloadIcon.png", 
                                      "Alert title", "Alert text goes here.", 
                                      false, "", null, "");
} catch (e) {
  // This can fail on Mac OS X
}

Listening for callbacks

You can be notified when the notification window disappears or the user clicks on the message by passing an object implementing nsIObserver as the alertListener parameter:

var listener = {
  observe: function(subject, topic, data) {
    alert("subject=" + subject + ", topic=" + topic + ", data=" + data);
  }
}
var alertsService = Components.classes["@mozilla.org/alerts-service;1"].
                              getService(Components.interfaces.nsIAlertsService);
try {
  alertsService.showAlertNotification("",  "Alerts service test", "Click me", 
                                      true, "cookie", listener, "");
} catch (e) {
  // This can fail on Mac OS X
}

Example 2

This example shows how to use all the available observer topics:

var as = Cc['@mozilla.org/alerts-service;1'].getService(Ci.nsIAlertsService);

var notifListener = {
    observe: function(aSubject, aTopic, aData) {
        console.error('incoming notification observer:', aSubject, aTopic, aData);
        if (aTopic == 'alertclickcallback')    {
            console.error('user clicked trying to throw click');
            Services.prompt.alert(Services.wm.getMostRecentWindow('navigator:firefox'), 'focus firefox', 'will now focus fireox and then focus the tab');
        } else if (aTopic == 'alertshow') {
            console.log('just showed notification');
        } else if (aTopic == 'alertfinished') {
            console.log('just alertfinished')
        }
    }
};

as.showAlertNotification('chrome://branding/content/icon64.png', 'StackOverflow - New Messages', 'There are ## new messages. Click here to focus the tab', true, null, notifListener, 'StackOverflow Notifier');

closeAlert()

Closes alerts created by the service.

void closeAlert(
  in AString name, Optional
  in nsIPrincipal principal Optional
);

Parameters

name

The name of the notification to close. If no name is provided then only a notification created with no name (if any) will be closed.

principal

The title for the alert.

See also

• Alerts and Notifications
• Bug 782211 - Implement notification API spec
• ui.alertNotificationOrigin [en-US]
• Bug 1270819 - nsIAlertsService showAlertNotification sliding alert unnecessarily big / high