How to create Firefox extensions

Everyone has a good idea at one time or another to implement a new feature in a web browser. Well, with the goodness that is Mozilla Firefox, now you can do just that. You need to have a vague understanding of XUL and Javascript, but you certainly don’t need to be a master of either. When I started, I knew nothing about either one, really. I had seen some bookmarklets here and there, and tried to figure out just how they worked. Well, that’s how I made my first extension, BugMeNot.

Contents

1. Learn By Example


2. Hello, world!


3. Looking inside the XPI


4. Re-configuring your extension’s installation


5. Chrome is more than a shiny bumper


6. Skin that cat


7. Pack it up and try it out


8. An easier way to re-build


9. My Firefox got completely hosed up



10. Ensure server compatibility


11. Additonal help and information


12. Comments / Feedback

Learn by example

Everyone has a good idea at one time or another to implement a new feature in a web browser. Well, with the goodness that is Mozilla Firefox, now you can do just that. You need to have a vague understanding of XUL and Javascript, but you certainly don’t need to be a master of either. When I started, I knew nothing about either one, really. I had seen some bookmarklets here and there, and tried to figure out just how they worked. Well, that’s how I made my first extension, BugMeNot.

Basically, this tutorial will show you how to create your first extension from scratch. Since
every programmer always learns from the famous “Hello, world!” example, I figured that would be a good way to introduce you to developing extensions.

Xul Planet has a nice little tutorial which will show you the basics of creating a menu. Mozilla also has a very handy DOM Window Interface reference if you’d like to take a look through that. They’re both geared toward an audience that has a good feel for programming, though, so it’s not necessary to understand everything going on to follow this tutorial.

Hello, world!

Our extension will be a nice simple one that will pop up a window proclaiming “Hello, world!” after we select it either in a right-click menu, or under the Tools menu. Both of these places are very popular positions, and it’s relatively easy to stick something in there.

Let’s see what the end result looks like, so you know what to expect. First, here are the two ways to access our extension:

Right-clicking will get us this:

The tools menu looks like this:

The end result of our extension’s efforts:

What it looks like in the extension manager:

Clicking on the “About…” in the extension manager will get us this:

Looking inside the XPI

Here’s how the extension breaks down in a nutshell, using a pre-made Hello, world! extension as an example:

(You can download it here, just right-click and save, then you can follow along.)

helloworld.xpi is the packaged extension. XPI is just an file format that your browser will recognize as a browser extension. In reality, it’s just a zipped up file. So you can rename the XPI to ZIP or even JAR if you want, then open it up using an archive program, like 7-Zip or WinRAR. So, once that’s opened up, you’ll see:

• chrome


• install.js


• install.rdf

A folder and two files. install.js was all you used to need for the installation, but now that the extension manager has changed (since Firefox 0.9), the install.rdf is used instead. Now, the install.js is used purely for earlier versions of Firefox/bird, Mozilla, and Netscape. If you want to make this extension solely for 0.9+ versions of Firefox, then you can omit this file if you’d like. I tend to
keep it in because it only take a second to make, and assures a wide audience compatibility. Some extensions simply aren’t backwards-compatible, though, for example my ListZilla

extension, since it gathers all information from 0.9’s extensions manager. A nice simple “Hello, world!” prompt shouldn’t present any problems, though.

If you open up install.js, you’ll see that it’s very basic, in terms of what you need to modify to make your own install script:

// --- Editable items begin ---
extFullName: 'Hello, world!', // The name displayed to the user
extShortName: 'helloworld', // The leafname of the JAR file 
extVersion: '0.1',
extAuthor: 'Eric Hamiter',
extLocaleNames: null, // e.g. ['en-US', 'en-GB']
extSkinNames: null, // e.g. ['classic', 'modern']
extPostInstallMessage: 'Success! Please restart your browser to finish the 
installation.'
// Set to null for no post-install message
// --- Editable items end ---

So all the hard work is done for you. I’m not going post the rest of the code, but you’ll see
quite a lengthy amount of work that is fully automated.

Now if you open install.rdf. you’ll see this:

<?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>{9AA46F4F-4DC7-4c06-97AF-5035170633FE}</em:id>
        <em:name>Hello, world!</em:name>

        <em:version>0.1</em:version>
        <em:description>Displays an alert message via right-click
        or Tools menu.</em:description>
        <em:creator>Eric Hamiter</em:creator>
        <em:homepageURL>http://extensions.roachfiend.com</em:homepageURL>

        <em:iconURL>chrome://helloworld/skin/helloworld.png</em:iconURL>
        <em:aboutURL>chrome://helloworld/content/about.xul</em:aboutURL>
        <em:file>
            <Description about="urn:mozilla:extension:file:helloworld.jar">
                <em:package>content/helloworld/</em:package>

                <em:skin>skin/classic/helloworld/</em:skin>
            </Description>
        </em:file>

        <em:targetApplication>
            <Description>

                <em:id>{ec8030f7-c20a-464f-9b0e-13a3a9e97384}</em:id>
                <em:minVersion>0.7</em:minVersion>
                <em:maxVersion>9.9</em:maxVersion>
            </Description>

        </em:targetApplication>

    </Description>

</RDF>

Re-configuring your extension’s installation

Ok, whoa.. what is all this crap? The first thing you’ll see is the <em:id> tag. This is your very own generated id that will separate your extension from anyone else’s. There are a few ways to make it. You can either use
an online perl script to randomly generate one, or if you use Windows, you can use a program called guidgen,
brought to us by Microsoft. How deliciously ironic. Or am I misuing the term irony here? Whatever. So if you download that, then you’ll see this when you run it:

So choose 4. Registry Format, then hit New GUID a few times for good measure, then Copy. That’s it, now your new spiffy id is in your clipboard. Replace the old one with this, and you’re set.

Name, version, description, creator, and homepageURL are all self-explanatory. The iconURL and aboutURL are what shows up if someone right-clicks your extension and chooses “About Extension…”. You can leave these blank, it’s not mandatory, but it’s nice to have a little flash every now and then.

Underneath file, this is standard stuff. Just replace all instances of “helloworld” with your extension name. This is where the installation will try and find your files and folders. If you have any icons, you’ll include the skin folder. Again, it’s not mandatory.

Target application is what you’re gearing this for. The ec8030f7… is unique to Firefox, so leave that alone. The minversion and maxversion is what versions of Firefox it will be compatible with. There was a big stink about this recently, since the developers introduced 0.9.1, shortly after telling us to make sure and only put a maxVersion of 0.9. This does not compute. So I recently modified mine to go to 9.9, which will ensure compatibility through the next few versions of Firefox. This isn’t the type of thing that mozilla will support, since they can only recommend keeping the maxVersion to the current release, but it’s the best way to keep you sane, so you don’t have to update your extensions every few weeeks.

Chrome is more than a shiny bumper

Ok, now open up the chrome folder. In there you’ll find another archived file, helloworld.jar. Open it up and extract the files. You’ll now have content and skin folders. Let’s explore content first. In there, we have a

helloworld folder, and under that, these files:

• about.xul


• contents.rdf


• helloworldOverlay.js


• helloworldOverlay.xul

about.xul is the file you see when you click “About Hello, world!…” in the extensions menu. It’s pretty self-explanatory, and you’ll see that a nice man named Jed Brown wrote the template for it, so all the hard work has been done for you. Again. So just fill out the info, and that’s it.

helloworldOverlay.xul and helloworldOverlay.js are what make things happen. They’re the brains behind the outfit, so to speak. And you’ll be amazed at how simple they are. Here’s helloworldOverlay.xul:

<?xml version="1.0"?>

<overlay id="helloworldOverlay"
         xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">

<!-- This imports our javascript. -->

<script type="application/x-javascript" 
src="chrome://helloworld/content/helloworldOverlay.js">

</script>


<!-- This is for the right click menu. -->

<popup id="contentAreaContextMenu">
  <menuitem id="helloworld" label="Hello, world!" accesskey="H"
  insertafter="context-stop" oncommand="hello();"/>

</popup>


<!-- This is for the Tools menu. -->

<menupopup id="menu_ToolsPopup">
    <menuitem insertafter="devToolsSeparator" label="Hello, world!"
    accesskey="H" oncommand="hello();" />
</menupopup>


</overlay>

So all it says to do is to insert the javascript file, helloworldOverlay.js, and to create a context menu entry called Hello, world! accesskey=”H”
underlines the “H”, since it’s the first letter that wasn’t taken by any other options. insertafter=”context-stop” places the option directly underneath the Stop label. oncommand makes it launch the window with the
function hello, which is located in the javascript file we imported earlier. The second part of the overlay tells it we also want to place an option in the Tools menu. Same logic as the context menu, just a different place to stick it. Here’s what helloworldOverlay.js looks like:

// This is our javascript, which will pop up our message
// in an alert box.

function hello(){
    alert("Hello, world!");
}

Now for contents.rdf. This is the file that tells the browser where to store this overlay information. Here’s what it looks like:

<?xml version="1.0"?>

<RDF:RDF xmlns:RDF="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:chrome="http://www.mozilla.org/rdf/chrome#">

    <RDF:Seq RDF:about="urn:mozilla:package:root">

        <RDF:li RDF:resource="urn:mozilla:package:helloworld"/>
    </RDF:Seq>

    <RDF:Seq RDF:about="urn:mozilla:overlays">
        <RDF:li RDF:resource="chrome://browser/content/browser.xul"/>
        <RDF:li RDF:resource="chrome://navigator/content/navigator.xul"/>
    </RDF:Seq>

    <RDF:Seq RDF:about="chrome://browser/content/browser.xul">
        <RDF:li>chrome://helloworld/content/helloworldOverlay.xul</RDF:li>
    </RDF:Seq>

    <RDF:Seq about="chrome://navigator/content/navigator.xul">
        <RDF:li>chrome://helloworld/content/helloworldOverlay.xul</RDF:li>

    </RDF:Seq>

    <RDF:Description RDF:about="urn:mozilla:package:helloworld"
        chrome:displayName="Hello, world! 0.1"
        chrome:author="Eric Hamiter"
        chrome:authorURL="mailto:ehamiter@gmail.com"
        chrome:name="helloworld"
        chrome:extension="true"
        chrome:description="Displays an alert message via right-click
        or Tools menu.">
    </RDF:Description>

</RDF:RDF>

You’ll notice the address chrome://browser/content/browser.xul up there. This is mozilla’s internal frame of reference.

browser is the actual browser, and navigator works for non-Firefox builds, like Netscape or Mozilla. The only part you’d need to modify is the descriptions. The rest of it just implements the extension into the browsers.

Skin that cat

Now let’s backtrack to the skin folder. In it, we’ll find a few more folders: classic and helloworld. This is just the traditional layout, and if it ain’t broke, then hey, don’t fix it. In helloworld, we find three files: helloworld.png, helloworldb.png, and a contents.rdf file.

helloworld.png:

helloworldb.png:

These are called from about.xul mentioned previously,
for use in the extension menu and the about menu. contents.rdf simply maps out the paths to the skin files, so the only modification you need to change for your own extension is in the last line, which points to the folder helloworld.

Pack it up and try it out

So now that you see how the files work, and where they’re packaged, you can modify them to your whims, and try out new things. Once you modify them, just pack them up in reverse order. Using your archive program, you would navigate back up to the chrome folder, and add content and
skin into a zipped archive, then rename it to extension.jar. After that, navigate up another folder, and add chrome, install.rdf, and install.js into another zipped archive, then rename it to extension.xpi.

You’re ready to test it out in your browser now. Open up Firefox, and hit CTRL-O, or Open File. Load up your xpi file, and say yes to the installation. Restart Firefox, and hopefully you’ll see your new extension in the menu, and it does whatever you had hoped it would do.

An easier way to re-build

After a while, it gets tiresome to select your files, your folder, archive them, rename them, move them, delete them, rename them… you get my point. If you have 7-Zip installed, you can use the command line feature, so you can have this all fully automated. Here’s what you need to do:

Copy C:\Program Files\7-Zip\7z.exe to C:\WINDOWS\system32 (This will
put 7z.exe in your system’s path, which will make it accessible from the command prompt).

It’s a good practice to build your extensions somewhere far away from random scripts and clutter, so create a new folder somewhere and call it whatever your extension is named. Make sure it matches the internal .jar file that you previously referenced in your install.rdf file. You can always rename the final xpi to something more intricate afterward, but for packaging, it’s best to keep it simple.

Copy the following script and paste it in a text editor and save it as build.bat in your newly-made folder:

set x=%cd%
md build\chrome
cd chrome
7z a -tzip "%x%.jar" * -r -mx=0
move "%x%.jar" ..\build\chrome
cd ..
copy install.* build
cd build
7z a -tzip "%x%.xpi" * -r -mx=9
move "%x%.xpi" ..\
cd ..
rd build /s/q

Now, you can build or modify your extensions easily. Just use the new folder as your
base of creation, so that would contain the install files and chrome folder. Whenever you want to create your new file, just double-click build.bat, and your new extension will pop out in the same folder. Each time you use the build.bat script, it will
delete your old file and create a new one.

My Firefox just got completely hosed up

Worst case scenario: upon restarting Firefox, it hangs with a “Firefox is still installing an
extension, this may take a minute…”. This means you borked it up somehow. Don’t panic! A super easy way of uninstalling it without hosing the rest of your shit up is as follows:

Start » Program Files » Mozilla Firefox » Mozilla Firefox (Safe Mode)

Then go to Tools » Extensions » [right-click on your extension] » Uninstall

Restart Firefox, and it’ll be gone. Then modify your files and try again.

Ensure server compatibility

If it works, and you want to put it on your web server, but find out that it won’t install directly, and your browser is treating it as “Save File As..” then you need to modify your .htaccess file. You can learn more about it here, but
for brevity’s sake, you need your server to run on Apache for it to work. If you have no problem modifying the file, here’s the information you need to add:

Add this to your .htaccess file:

AddType application/x-xpinstall xpi

And you should be set.

Additional help and information

If you want to take a look at any other files I’ve created, they’re on my main
extensions page, and I’ll list them directly here for convenience as well:

• Allow Right-Click


• Alt-Text for Links


• Always Remember Password



• BugMeNot
• Ext2Abc


• Google Images Re-Linker


• Goon Menu


• ListZilla
• Teleflip


• Word Count

If you’d like to put a certain snippet of Javascript on every page,
Allow Right-Click or Always Remember Password is the way to go. Alt-Text for Links uses javascript to control tooltips. If you’d like to create your own links menu, then Goon Menu is good to learn from. BugMeNot uses complex regular expressions, ListZilla deals with
setting options and using the extension manager, and WordCount is a good way to learn how to take a bookmarklet and use it as an extension.

The Mozillazine extensions forum is a great place to learn more about creating extensions. They’re under heavy loads from time to time, so they might be down when you read this, but try back again if they are, because they have a lot of useful information there.

Loads of other useful extensions can also be found at Mozilla Update, and there’s another place called My Extensions Mirror that has forums as well as tons of extensions.

Well, that’s it. Hopefully this has been helpful to at least a few ambitious people, as well as a look into what goes into making one for the non-technical types. So get off your ass and make something useful!