Code snippets:Sidebar

From MDC

This page provides several snippets demonstrating how to work with the Firefox sidebar.

See the Creating a Firefox sidebar tutorial for step-by-step instructions on creating a Firefox sidebar extension.

Contents 1 Opening and closing the sidebar 2 Accessing the sidebar from a browser.xul script 3 Accessing the browser.xul window from a sidebar script 4 Resizing the sidebar programmatically

[edit] Opening and closing the sidebar

Firefox provides a built-in toggleSidebar() function defined in browser.js. This means that the function is available in all browser windows. You can use this function to open or close the sidebar.

Here's the documentation for this function taken from the source:

/**
 * Opens or closes the sidebar identified by commandID.
 *
 * @param commandID a string identifying the sidebar to toggle; see the
 *                  note below. (Optional if a sidebar is already open.)
 * @param forceOpen boolean indicating whether the sidebar should be
 *                  opened regardless of it's current state (optional).
 * @note
 * We expect to find a xul:broadcaster element with the specified ID.
 * The following attributes on that element may be used and/or modified:
 *  - id           (required) the string to match commandID. The convention
 *                 is to use this naming scheme: 'view<sidebar-name>Sidebar'.
 *  - sidebarurl   (required) specifies the URL to load in this sidebar.
 *  - sidebartitle or label (in that order) specify the title to 
 *                 display on the sidebar.
 *  - checked      indicates whether the sidebar is currently displayed.
 *                 Note that toggleSidebar updates this attribute when
 *                 it changes the sidebar's visibility.
 *  - group        this attribute must be set to "sidebar".
 */
function toggleSidebar(commandID, forceOpen) {

Examples:

// toggle the bookmarks sidebar (close it if it's open or
// open it if it's currently closed)
toggleSidebar("viewBookmarksSidebar");

// open the history sidebar, whether it's closed or already open
toggleSidebar("viewHistorySidebar", true);

// close the sidebar, if we're sure one is currently open
toggleSidebar();

[edit] Accessing the sidebar from a browser.xul script

The sidebar content is always in a document separate from the main browser document (the sidebar is actually implemented as a XUL browser element). This means you can't directly access the sidebar content from a script referenced from a browser.xul overlay.

To access your sidebar's window or document objects, you need to use the contentWindow or contentDocument properties of document.getElementById("sidebar") respectively. For example the code below calls a function defined in the sidebar's context:

var sidebarWindow = document.getElementById("sidebar").contentWindow;
// Verify that our sidebar is open at this moment:
if (sidebarWindow.location.href ==
      "chrome://yourextension/content/whatever.xul") {
  // call "yourNotificationFunction" in the sidebar's context:
  sidebarWindow.yourNotificationFunction(anyArguments);
} 

[edit] Accessing the browser.xul window from a sidebar script

See Accessing the elements of the top-level document from a child window section of Working with windows in chrome code.

[edit] Resizing the sidebar programmatically

In case you need to change the width of the sidebar, use the following code:

function setSidebarWidth(newwidth) {
 var mainWindow = window.QueryInterface(Components.interfaces.nsIInterfaceRequestor)
 .getInterface(Components.interfaces.nsIWebNavigation)
 .QueryInterface(Components.interfaces.nsIDocShellTreeItem)
 .rootTreeItem
 .QueryInterface(Components.interfaces.nsIInterfaceRequestor)
 .getInterface(Components.interfaces.nsIDOMWindow);
 mainWindow.document.getElementById("sidebar-box").width=newwidth;
}

or

function setSidebarWidth(newwidth) {
  window.top.document.getElementById("sidebar-box").width=newwidth;
}

You can also disable the ability to resize it manually, using the mouse, by hiding the sidebar's splitter element. For this snippet to work, you have to declare mainWindow as in the previous code block then write:

mainWindow.document.getElementById("sidebar-splitter").hidden = true;

Be aware that if you change the splitter's hidden attribute, you need to reset it to a safe value when your sidebar is closed, or replaced by another sidebar. For example, use this in your sidebar's Unload event handler:

mainWindow.document.getElementById("sidebar-splitter").hidden =
  mainWindow.document.getElementById("sidebar-box").hidden;