Sidebar

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.

Opening and closing the sidebar

Firefox provides a built-in SidebarUI object function defined in browser-sidebar.js. This means that the function is available in all browser windows. You can use this function to show, hide, or toggle sidebars.

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

// show the history sidebar, whether it's hidden or already showing
SidebarUI.show("viewHistorySidebar");

// hide the sidebar, if one is showing
SidebarUI.hide();

Avoid opening the sidebar on startup. Users have been known to complain about this "feature", and if two or more extensions try to open their sidebars on startup, the user will see a flurry of sidebars opening and closing with which ever extension going last "winning".

Web panels sidebar

Content such as web pages can be safely loaded as sidebar in the "viewWebPanelsSidebar". Bookmarks with "Load this bookmark in sidebar" checked in the properties open in the "viewWebPanelsSidebar". A web page can use window.sidebar to create bookmark with that property. To open a page in the "viewWebPanelsSidebar" from chrome code (browser/addon/extension) such as from menuitem, it can call:
openWebPanel(aTitle, aURI);

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);
}

Testing which sidebar is open

The sidebar content may contain different panels (bookmarks, history, webpanel, etc.) and sometimes one wants to only act on the sidebar when it contains a specific panel. The good practice to determine which sidebar is open at a time is by testing in location property, which is a chrome URL:

var sidebarWindow = document.getElementById("sidebar").contentWindow;
if (sidebarWindow.location.href == "chrome://yourextension/content/whatever.xul") {
  // Act on the sidebar content
}

For example to test if the web panel from Firefox is open:

var sidebarWindow = document.getElementById("sidebar").contentWindow;
if (sidebarWindow.location.href == "chrome://browser/content/web-panels.xul") {
  // Act on the sidebar content only if it is the web panels
}

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.

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;
}

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;