Creating a Firefox sidebar extension

This article describes how to create a registered sidebar for Firefox 2 or greater. See the references section for information on creating extension in earlier browsers.

Introduction

This article is a quick start for the creation of a new sidebar for Firefox. What we will do is create a sidebar and register it so it will be available in the menu. The goal is creating an empty sidebar that can be used as start for new sidebar applications.

Creating a sidebar requires some GUI creation and registration in the destination application. First a simple XUL page is created. Then the registration files are made and finally the sidebar is packed into an installable XPI file.

Pre-requisites

This article is a quick start, it won't explain all elements of XUL, packaging and XPI's. It's preferable you have some basic knowledge of how XUL works and how Firefox handles extensions. See Building an Extension for more detailed information about structuring, packaging, and deploying extensions.

Packages

Extensions to Firefox are installed with packages ("Bundles"). An extension package usually contains a "content" provider, which contains the XUL code and application logic. Optionally locales and skins can be included. Most additions are provided with a default tree structure, although not required it is recommended to use this structure. Here the package for the sidebar is created, the files included are listed below.

emptysidebar
\- chrome
   |- content
   |- locale
   | \- en-US
   \- skin

Create all folders, except for skin. It is not used for this tutorial.

The locale holds the locale, only the en-US locale is created. It is listed in Example 2. The locale includes the name and shortcut keys for the sidebar.

<!ENTITY emptysidebar.title "EmptySidebar">
<!ENTITY openEmptySidebar.commandkey "E">
<!ENTITY openEmptySidebar.modifierskey "shift accel">

The content folder includes our sidebar, the emptysidebar.xul is shown in Example 3. It creates a page holding one label. Other elements can be included, please read the XUL tutorials for more information.

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin/" type="text/css" ?>
<?xml-stylesheet href="chrome://browser/skin/browser.css" type="text/css" ?>
<!DOCTYPE page SYSTEM "chrome://emptysidebar/locale/emptysidebar.dtd">

<page id="sbEmptySidebar" title="&emptysidebar.title;"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" >
  <vbox flex="1">
    <label id="atest" value="&emptysidebar.title;" />
  </vbox>
</page>

New extensions can be registered in the menus or popups, Firefox uses overlays for extending menus. This is an separate XUL file that specifies the location of menu items. The sidebar here is added to the View | Sidebar menu. The overlay file is listed in Example 4.

<?xml version="1.0"?>

<!DOCTYPE overlay SYSTEM "chrome://emptysidebar/locale/emptysidebar.dtd">
<overlay id="emptySidebarOverlay"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

  <menupopup id="viewSidebarMenu">
    <menuitem key="key_openEmptySidebar" observes="viewEmptySidebar"  />
  </menupopup>

  <keyset id="mainKeyset">
    <key id="key_openEmptySidebar" command="viewEmptySidebar"
         key="&openEmptySidebar.commandkey;"
         modifiers="&openEmptySidebar.modifierskey;" />
  </keyset>

  <broadcasterset id="mainBroadcasterSet">
    <broadcaster id="viewEmptySidebar"
                 label="&emptysidebar.title;"
                 autoCheck="false"
                 type="checkbox"
                 group="sidebar"
                 sidebarurl="chrome://emptysidebar/content/emptysidebar.xul"
                 sidebartitle="&emptysidebar.title;"
                 oncommand="toggleSidebar('viewEmptySidebar');" />
  </broadcasterset>
</overlay>

The overlay file consists of three entries, the menu definition, shortcut keys and the broadcaster.

The broadcaster serves two purposes. The first is it indirectly provides the arguments for the toggleSidebar function. The second is it provides attributes to the menuitem, some of which are changed automatically when toggleSidebar is called. See Code_snippets/Sidebar for more information.

If the sidebar is not going to have a command-key, one can remove the openEmptySidebar.commandkey and openEmptySidebar.modifierskey keys from the dtd, remove the <keyset> from the firefoxOverlay.xul file. One must then set the key attribute of the menuitem to "".

The extension needs to provide some special manifest files that control how it is installed and where its chrome resources are stored. The first is install.rdf, the install manifest. See Install Manifests for a complete listing of the required and optional properties. The install manifest is listed in Example 5.

<?xml version="1.0" encoding="UTF-8"?>

<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
 xmlns:em="http://www.mozilla.org/2004/em-rdf#">
  <Description about="urn:mozilla:install-manifest">
    <em:id>emptysidebar@yourdomain.com</em:id>
    <em:name>EmptySidebar Extension</em:name>
    <em:version>1.0</em:version>
    <em:creator>Your Name</em:creator>
    <em:description>Example extension for creation and registration of a sidebar.</em:description>
    <em:targetApplication>
      <Description>
        <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id> <!-- firefox -->
        <em:minVersion>1.5</em:minVersion>
        <em:maxVersion>2.0.0.*</em:maxVersion>
      </Description>
    </em:targetApplication>
  </Description>
</RDF>

The other manifest file is chrome.manifest, the chrome manifest file. The chrome manifest creates a lookup for all the resource types used by the extension. The manifest also tells Firefox that the extension has an overlay that needs to be merged into the browser. For more information on chrome manifests and the properties they support, see the Chrome Manifest reference. The manifest used in this extension is listed in Example 6.

content	emptysidebar	chrome/content/
locale	emptysidebar	en-US	chrome/locale/
skin	emptysidebar	classic/1.0	chrome/skin/
overlay	chrome://browser/content/browser.xul	chrome://emptysidebar/content/firefoxOverlay.xul

Test

While you're developing your sidebar, you will need to test it frequently from Firefox. There is a simple way to do this. First, we need to tell Firefox about your extension.

1. Open your Profile Folder
2. Open the extensions folder (create it if it doesn't exist)
3. Create a new text file, and put the path to your extension folder inside, e.g. C:\extensions\myExtension or ~/extensions/myExtension. Save the file with the id of your extension as its name, e.g. emptysidebar@yourdomain.com

Now you're ready to test your extension! Restart Firefox and the sidebar is included in the menu.

You can now go back and make changes to the XUL file, close and restart Firefox and they should appear.

Deployment

Now that we have a sidebar it is time to make it available to the world. Installation requires the creation of an XPI file which is identified as extension in Firefox. The XPI is a ZIP file containing the content, locale and manifest files.

The content, locale and skin folders are packed into emptysidebar.jar, which should be created in the chrome folder. On unix systems:

~/src/emptysidebar$ cd chrome
~/src/emptysidebar/chrome$ zip -r emptysidebar.jar content/ locale/

On Windows systems, use a ZIP tool to create emptysidebar.zip and then rename to emptysidebar.jar.

Since we are packaging the extension with a JAR file, we need to update the chrome.manifest file to take to JAR file into consideration:

content emptysidebar	jar:chrome/emptysidebar.jar!/content/
locale  emptysidebar	en-US	jar:chrome/emptysidebar.jar!/locale/
skin    emptysidebar	classic/1.0	jar:chrome/emptysidebar.jar!/skin/
overlay chrome://browser/content/browser.xul	chrome://emptysidebar/content/firefoxOverlay.xul

Finally, create the XPI file. This is a ZIP file containing the JAR file in the chrome folder and the manifest files. On unix systems:

~/src/emptysidebar/chrome$ cd ..
~/src/emptysidebar$ zip emptysidebar.xpi install.rdf chrome.manifest chrome/emptysidebar.jar

Open Firefox and browse to the folder containing emptysidebar.xpi. Click on the file and the Extension installation window pops up. After a restart of Firefox, the sidebar is installed.

You can download the empty sidebar project to use as a basis for your own sidebars.

Resources

• Code snippets:Sidebar
• Building an Extension
• Creating Applications with Mozilla
• Packaging Firefox/Thunderbird Extensions
• Creating a Firefox 1 Sidebar