mozilla
Your Search Results

    doorhanger

    This article is in need of a technical review.

    The NativeWindow object is only available to privileged code running on Firefox for Android, and is intended for use by Firefox for Android add-ons.

    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

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

    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:

     

    Updated screenshot of doorhanger.

    var menuID;
    
    function offerCake(window) {
      let buttons = [
        {
          label: "Yes, please!",
          callback: function () {
            window.NativeWindow.toast.show("yum", "short");
          }
        },
        {
          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);  
    }
    

    Document Tags and Contributors

    Contributors to this page: Sheppy, wbamberg, MKaply, Liuche, justinpotts
    Last updated by: Liuche,
    Hide Sidebar