appendNotification

appendNotification( label , value , image , priority , buttons, eventCallback )
Return type: element
Create a new notification and display it. If another notification is already present with a higher priority, the new notification will be added behind it.
  • label - label to appear on the notification. This should be either a string, or, from Gecko 37 onwards, you can pass a DocumentFragment with rich content as well. Keep in mind that this is all XUL so using HTML elements for styling might still need additional CSS in order to work as you might expect.
  • value - value used to identify the notification
  • image - URL of image to appear on the notification. If "" then an icon appropriate for the priority level is used.
  • priority - notification priority; see Priority Levels.
  • buttons - array of button descriptions to appear on the notification.
  • eventCallback Optional - a JavaScript function to call to notify you of interesting things that happen with the notification box. See Notification box events.
Priority Levels (defined as properties of notificationbox) :
  • PRIORITY_INFO_LOW
  • PRIORITY_INFO_MEDIUM
  • PRIORITY_INFO_HIGH
  • PRIORITY_WARNING_LOW
  • PRIORITY_WARNING_MEDIUM
  • PRIORITY_WARNING_HIGH
  • PRIORITY_CRITICAL_LOW
  • PRIORITY_CRITICAL_MEDIUM
  • PRIORITY_CRITICAL_HIGH
  • PRIORITY_CRITICAL_BLOCK
Buttons :
The buttons argument is an array of button descriptions. Each description is an object with the following properties:
  • accessKey - the accesskey to appear on the button
  • callback - function to be called when the button is activated. This function is passed three arguments:
    • the <notification> the button is associated with
    • the button description as passed to appendNotification.
    • the element which was the target of the button press event.
    • If the return value from this function is not True, then the notification is closed. The notification is also not closed if an error is thrown.
  • label - the label to appear on the button
  • popup - the id of a popup for the button. If null, the button is not a button popup (e.g. a menu). The type property must also be set to "menu", or "menu-button".
  • isDefault - if True, this is the default button. There can be only one default button. If no button has this set, the first button in the array is the default.
  • type - a string. Valid values are "menu-button" and "menu" which must be set if the button is to provide a popup via the popup property.

Notification box events

Requires Gecko 9.0(Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6)

If you specify the eventCallback parameter, it should be a JavaScript function that gets called when interesting things happen related to the notification box. This function receives as its only parameter a string indicating what event occurred. At this time, there's just one event type: "removed". This indicates that the notification box has been removed from its window.

Example:

function testNotificationBoxWithButtons() {
    //Create some common variables if they do not exist.
    //  This should work from any Firefox context.
    //  Depending on the context in which the function is being run,
    //  this could be simplified.
    if (typeof window === "undefined") {
        //If there is no window defined, get the most recent.
        var window=Components.classes["@mozilla.org/appshell/window-mediator;1"]
                             .getService(Components.interfaces.nsIWindowMediator)
                             .getMostRecentWindow("navigator:browser");
    }
    if (typeof gBrowser === "undefined") {
        //If there is no gBrowser defined, get it
        var gBrowser = window.gBrowser;
    }

    function testNotificationButton1Callback(theNotification, buttonInfo, eventTarget) {
        window.alert("Button 1 pressed");
        //Prevent notification from closing:
        return true;
    };

    function testNotificationButton2Callback(theNotification, buttonInfo, eventTarget) {
        window.alert("Button 2 pressed");
        //Do not prevent notification from closing:
    };

    function testNotificationCallback(reason) {
        window.alert("Reason is: " + reason);
    };

    let notifyBox = gBrowser.getNotificationBox();
    let buttons = [];

    let button1 = {
        isDefault: false,
        accessKey: "1",
        label: "Button 1",
        callback: testNotificationButton1Callback,
        type: "", // If a popup, then must be: "menu-button" or "menu".
        popup: null
    };

    buttons.push(button1);

    let button2 = {
        isDefault: true,
        accessKey: "2",
        label: "Button 2",
        callback: testNotificationButton2Callback,
        type: "", // If a popup, then must be: "menu-button" or "menu".
        popup: null
    };

    buttons.push(button2);

    //appendNotification( label , value , image (URL) , priority , buttons, eventCallback )
    notifyBox.appendNotification("My Notification text", "Test notification unique ID",
                                 "chrome://browser/content/aboutRobots-icon.png",
                                 notifyBox.PRIORITY_INFO_HIGH, buttons,
                                 testNotificationCallback);
}