doorhanger

Summary

Returns a reference to the NativeWindow.doorhanger object, which can be used to display doorhanger notifications (also known as popup notifications) on Firefox for Android.

Doorhanger notifications provide a way to present decisions to users which is less intrusive than a modal dialog. You can display a doorhanger using NativeWindow.doorhanger.show(). On Firefox for Android a doorhanger displays a title and an array of buttons for the user choices: selecting a button calls the corresponding callback function. Doorhangers are attached to a specific tab, and you can control the doorhanger's persistence.

You can close a doorhanger explicitly using NativeWindow.doorhanger.hide().

Method Overview

Methods

hide()

Hides the doorhanger associated with the tabId and notificationId, if it exists.

void hide(
 in string notificationId,
 in int tabId,
)

Parameters

notificationId

The string which was supplied as the value argument to NativeWindow.doorhanger.show().

tabId

The ID of the tab to which the doorhanger is attached. This is the same value as the tabID argument to NativeWindow.doorhanger.show().

show()

Shows a doorhanger.

void show(
  in string message,
  in string notificationId,
  in object buttons,
  in int tabId,
  in object options,
  in string category
)

Parameters

message

Message to be displayed in the doorhanger body.

notificationId

Identifier for doorhanger type. Human-readable by convention.

buttons

This is an array of button objects, once for each choice to offer the user.

• label: a string to display on the button
• callback: a function that will be called when the button is selected
• positive: (optional) a boolean for whether the button is an affirmative button. The value is implicitly false if omitted. Firefox 41

Firefox 41 Doorhangers will handle at most one positive:true button and one (implicitly) positive:false one, for a maximum of two buttons. Any additional buttons will not be displayed.

tabId

The ID of the tab the doorhanger should be attached to. You can retrieve the tabID using the BrowserApp object: for example, window.BrowserApp.selectedTab.id returns the ID of the active tab.

options

Additional options for the doorhanger.

• timeout: a time in milliseconds. The notification will not automatically dismiss before this time.
• persistence: an integer. The notification will not automatically dismiss for this many page loads. If persistence is set to -1, the doorhanger will never automatically dismiss.

Example

In the example below, an add-on adds a new menu item labeled "Offer cake" which constructs and shows a new doorhanger when selected.

The doorhanger contains two buttons, which just show different toast messages when selected:

var menuID;

function offerCake(window) {
  let buttons = [
    {
      label: "Yes, please!",
      callback: function () {
        window.NativeWindow.toast.show("yum", "short");
      },
      positive: true
    },
    {
      label: "Not today",
      callback: function () {
        window.NativeWindow.toast.show("still hungry", "short");
      }
    }
  ];

  let message = "How about some cake?";
  let options = {
    persistence: 1
  };

  window.NativeWindow.doorhanger.show(message, "cake-request", buttons,
                                      window.BrowserApp.selectedTab.id,
                                      options);
}

function loadIntoWindow(window) {
  if (!window)
    return;
  menuID = window.NativeWindow.menu.add("Offer cake", null, function(){  
    offerCake(window);   
  });
}

function unloadFromWindow(window) {
  if (!window)
    return;
  window.NativeWindow.menu.remove(menuID);  
}