Using popup notifications

  • Revision slug: Using_popup_notifications
  • Revision title: Using popup notifications
  • Revision id: 71253
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment add icon css info; 115 words added

Revision Content

{{ gecko_minversion_header("2.0") }}

Popup notifications, such as the one shown below, are presented to notify the user of something that's important but may not need immediate attention. These non-modal notifications let the user make decisions when they have a moment to do so, instead of being forced to deal with them at possibly inconvenient times. For example, this popup notification is displayed when a web site requests geolocation information:

popupnotification.png

This lets the user decide whether or not to share their location when it's convenient to do so, instead of being compelled to do it at once.

A popup notification can include a text message, a button action, and zero or more additional actions provided in a drop-down menu accessed through the notification's button.

Creating a popup notification

Popup notifications can be created using the PopupNotifications.jsm JavaScript code module. This code module is imported by the browser, so you don't need to do it explicitly yourself.

Then you can create the popup notification at the appropriate time like this:

PopupNotifications.show(gBrowser.selectedBrowser, "sample-popup",
        "This is a sample popup notification.",
        null, /* anchor ID */
        {
          label: "Do Something",
          accessKey: "D",
          callback: function() {
            alert("Doing something awesome!");
          }
        },
        null  /* secondary action */
        );

In this case, we aren't providing any secondary actions; that is, actions provided to the user through the drop-down menu.

This notification looks like this:

samlple-noicon.png

That's not very pretty; where's the icon?

Adding an icon to your notification

Adding an icon to a notification is simple. You just need to provide the appropriate CSS. The PopupNotifications.jsm code module adds a popupid attribute to the notification object's icon element. You can use this to style the icon, like this:

.popup-notification-icon[popupid="sample-popup"] {
  list-style-image: url("chrome://popupnotifications/skin/mozlogo.png");
}

With this CSS in place, the result is the look we want:

sample.png

Adding secondary options

To provide options in the drop-down menu, add an array of notification actions to the call to the show() method, like this:

PopupNotifications.show(gBrowser.selectedBrowser, "sample-popup",
        "This is a sample popup notification.",
        null, /* anchor ID */
        {
          label: "Do Something",
          accessKey: "D",
          callback: function() {
            alert("Doing something awesome!");
          }
        },
        [
          {
            label: "First secondary option",
            accessKey: "1",
            callback: function() {
              alert("First secondary option selected.");
            }
          },
          {
            label: "Second secondary option",
            accessKey: "2",
            callback: function() {
              alert("Second secondary option selected.");
            }
          }
        ]
        );

When this notification is presented, and the user clicks on the menu button in the panel, the display looks like this:

sample-dropdown.png

Revision Source

<p>{{ gecko_minversion_header("2.0") }}</p>
<p>Popup notifications, such as the one shown below, are presented to notify the user of something that's important but may not need immediate attention. These non-modal notifications let the user make decisions when they have a moment to do so, instead of being forced to deal with them at possibly inconvenient times. For example, this popup notification is displayed when a web site requests geolocation information:</p>
<p><img alt="popupnotification.png" class="internal default" src="/@api/deki/files/4906/=popupnotification.png"></p>
<p>This lets the user decide whether or not to share their location when it's convenient to do so, instead of being compelled to do it at once.</p>
<p>A popup notification can include a text message, a button action, and zero or more additional actions provided in a drop-down menu accessed through the notification's button.</p>
<h2>Creating a popup notification</h2>
<p>Popup notifications can be created using the <a href="/en/JavaScript_code_modules/PopupNotifications.jsm" title="https://developer.mozilla.org/en/JavaScript_code_modules/PopupNotifications.jsm">PopupNotifications.jsm</a> JavaScript code module. This code module is imported by the browser, so you don't need to do it explicitly yourself.</p>
<p>Then you can create the popup notification at the appropriate time like this:</p>
<pre class="brush: js">PopupNotifications.show(gBrowser.selectedBrowser, "sample-popup",
        "This is a sample popup notification.",
        null, /* anchor ID */
        {
          label: "Do Something",
          accessKey: "D",
          callback: function() {
            alert("Doing something awesome!");
          }
        },
        null  /* secondary action */
        );
</pre>
<p>In this case, we aren't providing any secondary actions; that is, actions provided to the user through the drop-down menu.</p>
<p>This notification looks like this:</p>
<p><img alt="samlple-noicon.png" class="internal default" src="/@api/deki/files/4909/=samlple-noicon.png"></p>
<p>That's not very pretty; where's the icon?</p>
<h3>Adding an icon to your notification</h3>
<p>Adding an icon to a notification is simple. You just need to provide the appropriate CSS. The <code>PopupNotifications.jsm</code> code module adds a <code>popupid</code> attribute to the notification object's icon element. You can use this to style the icon, like this:</p>
<pre class="brush: css">.popup-notification-icon[popupid="sample-popup"] {
  list-style-image: url("chrome://popupnotifications/skin/mozlogo.png");
}
</pre>
<p>With this CSS in place, the result is the look we want:</p>
<p><img alt="sample.png" class="internal default" src="/@api/deki/files/4907/=sample.png"></p>
<h3>Adding secondary options</h3>
<p>To provide options in the drop-down menu, add an array of notification actions to the call to the <code>show()</code> method, like this:</p>
<pre class="brush: js">PopupNotifications.show(gBrowser.selectedBrowser, "sample-popup",
        "This is a sample popup notification.",
        null, /* anchor ID */
        {
          label: "Do Something",
          accessKey: "D",
          callback: function() {
            alert("Doing something awesome!");
          }
        },
        [
          {
            label: "First secondary option",
            accessKey: "1",
            callback: function() {
              alert("First secondary option selected.");
            }
          },
          {
            label: "Second secondary option",
            accessKey: "2",
            callback: function() {
              alert("Second secondary option selected.");
            }
          }
        ]
        );
</pre>
<p>When this notification is presented, and the user clicks on the menu button in the panel, the display looks like this:</p>
<p><img alt="sample-dropdown.png" class="internal default" src="/@api/deki/files/4908/=sample-dropdown.png"></p>
Revert to this revision