Monday, October 5, 2009

Learn how to create a Firefox extension in 10 minutes

Note: This article explains the source code of  Simple Boss Key version 1.0.1, not the latest version.

Is it complicated to create a Firefox extension? No. After reading this little tutorial, you will see how easy it is. Here I am using the Firefox extension of Simple Boss Key I built as the example to show you how simple a Firefox extension could be.

The Simple Boss Key extension add a shortcut key F12 to the browser. You can download the extension from Mozilla Add-ons website.

The Firefox extension package file has a filename extension of .xpi. You can extract it with WinZip, WinRAR, or the zip command if you are using Linux. If you extract the Simple Boss Key extension, you would see there are only a handful files in the package. Some of them are necessary, the others are optional.

Essential files
  • install.rdf
  • chrome.manifest
  • chrome/content/simplebosskey.xul

Optional files
  • chrome/content/options.xul
  • chrome/skin/sbk.png
These two files help to make the extension more user-friendly. They can be neglected.

install.rdf

This file contains the information and description of the extension. You can start it from a template on Mozilla developer website.

<?xml version="1.0"?>
<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>simplebosskey@ttt-jl.blogspot.com</em:id>
        <em:name>Simple Boss Key</em:name>
        <em:version>1.0</em:version>
        <em:description>Press F12 to minimize your window.</em:description>
        <em:creator>James L.</em:creator>
        <!-- optional items -->
        <em:homepageURL>http://ttt-jl.blogspot.com/</em:homepageURL>
        <em:optionsURL>chrome://simplebosskey/content/options.xul</em:optionsURL>
        <em:iconURL>chrome://simplebosskey/skin/sbk.png</em:iconURL>
        <em:type>2</em:type> <!-- type=extension --> 

        <!-- Firefox -->
        <em:targetApplication>
            <Description>
                <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
                <em:minVersion>3.0</em:minVersion>
                <em:maxVersion>3.0.*</em:maxVersion>
            </Description>
        </em:targetApplication>
    </Description>

</RDF>

The file is pretty straightforward, you just need to fill in your own data to the fields I highlight.

chrome.manifest

This file tells where your code is.

content simplebosskey chrome/content/
skin simplebosskey classic chrome/skin/
overlay chrome://browser/content/browser.xul chrome://simplebosskey/content/simplebosskey.xul

The content line resolves the URI chrome://simplebosskey/content/, whose physical location will be chrome/content/. If you look again at the install.rdf file, you will know that chrome://simplebosskey/content/options.xul is pointed to file chrome/content/options.xul

The skin line resolves the URI chrome://simplebosskey/skin/, whose physical location will be chrome/skin/. So em:iconURL in the install.rdf file points to file chrome/skin/sbk.png.

The overlay line tells that the browser.xul file will be overlaid by chrome/content/simplebosskey.xul.

chrome/content/simplebosskey.xul

For more information of what XUL is, visit Mozilla developer website.

This file overlays browser.xul. In another word, it changes the default behavior of the browser. If you look inside the file:

<?xml version="1.0"?>

<overlay id="simplebosskey" 
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
   <keyset id="mainKeyset">

      <key id="sbkMinimizeWin"
           keycode="VK_F12"
           oncommand="gBrowser.selectedTab = gBrowser.tabContainer.childNodes[0]; setTimeout(function() { window.minimize(); }, 0);" />

   </keyset>
</overlay>

you can see it just does a little change to the shortcut key set. The rest of the browser's behavior remain unchanged.

The file defines a new behavior for key F12 whose keycode is VK_F12. The oncommand line defines what commads should be run when key F12 is pressed:

1. gBrowser.selectedTab = gBrowser.tabContainer.childNodes[0];
   Tell the browser to select/focus the first tab.

2. setTimeout(function() { window.minimize(); }, 0);
   Minimize the browser window. The function setTimeout() is used because we need to wait for the browser bringing the first tab to the front.

This file is the soul of the extension.

You can try different keycode to make your own shortcut key.

chrome/content/options.xul

This file implements the em:optionsURL of the install.rdf file. When the user click the Options button in the extension (from menu Tools->Add-ons->Extensions), em:optionsURL will be brought up. The options.xul file of our extension pops up a dialogue with some instructions of how to use the shortcut key.

<?xml version="1.0"?>

<?xml-stylesheet href="chrome://global/skin/global.css" type="text/css"?>

<dialog id="sbkOption" title="Instruction"
   xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
   buttons="accept">
    
    <dialogheader title="Simple Boss Key Instruction" />
    <description width="350" style="margin:10px">Press F12 to minimize the current browser window.</description>
    <description width="350" style="margin:10px">The first tab is focused so even somebody peeks at your taskbar, he may not know what you were browsing.</description>
    <seperator />
    <label style="font-size:1.2em; font-weight:bold">Tips</label>
    <description width="350" style="margin:10px">1. Open a work-related page on the first tab. When the window is minimized, the title of the first tab will be shown in the taskbar.</description>
    <description width="350" style="margin:10px">2. Work best with Tabbed browsing. In the browser's Options/Preferences dialogue, set "Tabs->New pages should be opened in:" to "a new tab".</description>

</dialog>

The <label> and <description> tags are called XUL controls.

You can use the XUL controls to create a verify complex options dialogue, like all the other fancy Firefox extensions. But my opinion is, life is already full of choices, that sometimes people would feel relieved if they were told there are no options. :)

chrome/skin/sbk.png

A small icon to make the extension look fancy.


Now, after we have all these files and directories created, just pack and compress them together with WinZip (or zip if on Linux). Then rename the zip file with a different filename extension xpi.

To install a Firefox extension locally, you can drag and drop it into Firefox Extensions dialogue (from menu Tools->Add-ons->Extensions). It is all done and you can now try your own Firefox extension!


If you think this article is helpful, please help to share the Simple Boss Key extension:

No comments:

Post a Comment