This article is in need of a technical review.

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

After a call of toggleSidebar() you can't access sidebar's content (including objects and functions declared there) immediately because the toggling is asynchronous and takes some time. Instead you should set up some kind of listener.

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

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;

 

Set the sidebar in the right side of the browser

In case you need to change the location of the sidebar to the right side of the browser, use the following CSS code in overlay.css:

Note: Doesn't work correctly in firefox 3.6. It will change all text in the sidebar from rtl to ltr

@namespace url(http://www.mozilla.org/keymaster/gat...re.is.only.xul);
hbox#browser { 
    direction: rtl !important;
     }         
hbox#browser > vbox {
    direction: ltr !important; 
    }

See Also

Document Tags and Contributors

Last updated by: PikadudeNo1,
Hide Sidebar