This module exports a single constructor function Panel which constructs a new panel.

A panel is a dialog. Its content is specified as HTML and you can execute scripts in it, so the appearance and behaviour of the panel is limited only by what you can do using HTML, CSS and JavaScript.

The screenshot below shows a panel whose content is built from the list of currently open tabs:

Panels are useful for presenting temporary interfaces to users in a way that is easier for users to ignore and dismiss than a modal dialog, since panels are hidden the moment users interact with parts of the application interface outside them.

A panel's content is loaded as soon as it is created, before the panel is shown, and the content remains loaded when a panel is hidden, so it is possible to keep a panel around in the background, updating its content as appropriate in preparation for the next time it is shown.

Your add-on can receive notifications when a panel is shown or hidden by listening to its show and hide events.

Panel Content

The panel's content is specified as HTML, which is loaded from the URL supplied in the contentURL option to the panel's constructor.

You can load remote HTML into the panel:

var panel = require("panel").Panel({
  width: 180,
  height: 180,
  contentURL: "https://en.wikipedia.org/w/index.php?title=Jetpack&useformat=mobile"
});

panel.show();

You can also load HTML that's been packaged with your add-on, and this is most probably how you will create dialogs. To do this, save the HTML in your add-on's data directory and load it using the data.url() method exported by the self module, like this:

var panel = require("panel").Panel({
  contentURL: require("self").data.url("myFile.html")
});

panel.show();

Updating Panel Content

You can update the panel's content simply by setting the panel's contentURL property.

Here's an add-on that adds two widgets to the add-on bar, one which shows Google's mobile site and one which shows Bing's mobile site. The widgets share a panel object, and switch between the two sites by updating the panel's contentURL property:

var panel = require("panel").Panel({
  contentURL: "about:blank",
  onHide: function () {
    panel.contentURL = "about:blank";
  }
});

require("widget").Widget({
  id: "bing",
  label: "Bing",
  contentURL: "http://www.bing.com/favicon.ico",
  panel: panel,
  onClick: function() {
    panel.contentURL = "http://m.bing.com/";
  }
});

require("widget").Widget({
  id: "google",
  label: "Google",
  contentURL: "http://www.google.com/favicon.ico",
  panel: panel,
  onClick: function() {
    panel.contentURL = "http://www.google.com/xhtml";
  }
});

Scripting Panel Content

You can't directly access your panel's content from your main add-on code. To access the panel's content, you need to load a script into the panel. In the SDK these scripts are called "content scripts" because they're explicitly used for interacting with web content.

While content scripts can access the content they're attached to, they can't use the SDK's APIs. So implementing a complete solution usually means you have to send messages between the content script and the main add-on code.

• You can specify one or more content scripts to load into a panel using the contentScript or contentScriptFile options to the Panel() constructor.

• You can communicate with the script using either the postMessage() API or (preferably, usually) the port API.

For example, here's an add-on whose content script intercepts mouse clicks on links inside the panel, and sends the target URL to the main add-on code. The content script sends messages using self.port.emit() and the add-on script receives them using panel.port.on().

var myScript = "window.addEventListener('click', function(event) {" +
               "  var t = event.target;" +
               "  if (t.nodeName == 'A')" +
               "    self.port.emit('click-link', t.toString());" +
               "}, false);"

var panel = require("panel").Panel({
  contentURL: "http://www.bbc.co.uk/mobile/index.html",
  contentScript: myScript
});

panel.port.on("click-link", function(url) {
  console.log(url);
});

panel.show();

This example uses contentScript to supply the script as a string. It's usually better practice to use contentScriptFile, which is a URL pointing to a script file saved under your add-on's data directory.

Getting User Input

The following add-on adds a widget which displays a panel when clicked. The panel just contains a <textarea> element: when the user presses the return key, the contents of the <textarea> is sent to the main add-on code.

The add-on consists of three files:

• main.js: the main add-on code, that creates the widget and panel
• get-text.js: the content script that interacts with the panel content
• text-entry.html: the panel content itself, specified as HTML

"main.js" is saved in your add-on's lib directory, and the other two files go in your add-on's data directory:

my-addon/
         data/
              get-text.js
              text-entry.html
         lib/
             main.js

The "main.js" looks like this:

var data = require("self").data;

// Create a panel whose content is defined in "text-entry.html".
// Attach a content script called "get-text.js".
var text_entry = require("panel").Panel({
  width: 212,
  height: 200,
  contentURL: data.url("text-entry.html"),
  contentScriptFile: data.url("get-text.js")
});

// Send the content script a message called "show" when
// the panel is shown.
text_entry.on("show", function() {
  text_entry.port.emit("show");
});

// Listen for messages called "text-entered" coming from
// the content script. The message payload is the text the user
// entered.
// In this implementation we'll just log the text to the console.
text_entry.port.on("text-entered", function (text) {
  console.log(text);
  text_entry.hide();
});

// Create a widget, and attach the panel to it, so the panel is
// shown when the user clicks the widget.
require("widget").Widget({
  label: "Text entry",
  id: "text-entry",
  contentURL: "http://www.mozilla.org/favicon.ico",
  panel: text_entry
});

The content script "get-text.js" looks like this:

self.port.on("show", function (arg) {
  var textArea = document.getElementById('edit-box');
  textArea.focus();
  // When the user hits return, send a message to main.js.
  // The message payload is the contents of the edit box.
  textArea.onkeyup = function(event) {
    if (event.keyCode == 13) {
      // Remove the newline.
      text = textArea.value.replace(/(\r\n|\n|\r)/gm,"");
      self.port.emit("text-entered", text);
      textArea.value = '';
    }
  };
});

Finally, the "text-entry.html" file defines the <textarea> element:

<html>

<head>
  <style type="text/css" media="all">
    textarea {
      margin: 10px;
    }
  </style>
</head>

<body>
  <textarea rows="10" cols="20" id="edit-box"></textarea>
</body>

</html>

To learn much more about content scripts, see the Working with Content Scripts guide.

var data = require("self").data;

// Create a panel whose content is defined in "text-entry.html".
var text_entry = require("panel").Panel({
  width: 212,
  height: 200,
  contentURL: data.url("text-entry.html"),
});

// Send the page script a message called "show" when
// the panel is shown.
text_entry.on("show", function() {
  text_entry.port.emit("show");
});

// Listen for messages called "text-entered" coming from
// the page script. The message payload is the text the user
// entered.
// In this implementation we'll just log the text to the console.
text_entry.port.on("text-entered", function (text) {
  console.log(text);
  text_entry.hide();
});

// Create a widget, and attach the panel to it, so the panel is
// shown when the user clicks the widget.
require("widget").Widget({
  label: "Text entry",
  id: "text-entry",
  contentURL: "http://www.mozilla.org/favicon.ico",
  panel: text_entry
});

addon.port.on("show", function (arg) {
  var textArea = document.getElementById('edit-box');
  textArea.focus();
  // When the user hits return, send a message to main.js.
  // The message payload is the contents of the edit box.
  textArea.onkeyup = function(event) {
    if (event.keyCode == 13) {
      // Remove the newline.
      text = textArea.value.replace(/(\r\n|\n|\r)/gm,"");
      addon.port.emit("text-entered", text);
      textArea.value = '';
    }
  };
});

<html>

<head>
  <style type="text/css" media="all">
    textarea {
      margin: 10px;
    }
  </style>
  <script src="get-text.js"></script>
</head>

<body>
  <textarea rows="10" cols="20" id="edit-box"></textarea>
</body>

</html>

Styling Trusted Panel Content

When the panel's content is specified using an HTML file in your data directory, you can style it using CSS, either embedding the CSS directly in the file or referencing a CSS file stored under data.

The panel's default style is different for each operating system:

This helps to ensure that the panel's style is consistent with the dialogs displayed by Firefox and other applications, but means you need to take care when applying your own styles. For example, if you set the panel's background-color property to white and do not set the color property, then the panel's text will be invisible on OS X although it looks fine on Ubuntu.