[Guide] How to make a Firefox extension

[Liger]

Post your extension in this thread if you make one using 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 versions 0.9 and greater 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-compatibile, 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 (don't include the version)

extShortName: 'helloworld', // The leafname of the JAR file (without the .jar part)

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.8</em:minVersion>

<em:maxVersion>1.5</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 tags describe what versions of Firefox the extension will be compatibile with. Although as of this writing there is no 1.5 version, and mozilla folk will frown upon you putting in something higher than the current version, this is the easiest way to keep your extensions working through current and future builds. The proper way to do this is to rewrite your extension's maxVersion every time, so you can choose which would be better for you to do.

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.

Important: If you decide to use WinRAR for packing your files, make sure you choose the "zip" format in the menu below your filename. The default is set to "rar", and Firefox won't recognize the final xpi file as compatibile if you use the "rar" setting.

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 **** 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 agaEnsure server compatibilityty

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 sAdditional help and informationon

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

* Goon Menu

* ListZilla

* Productivity and Networking Information Component (PaNIC)

* 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, while ListZilla deals with setting options and using the extension manager. PaNIC uses user-defined variables in XUL menus, and Teleflip executes third party executable files. Last but not least, 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!

Credit to Eric for the guide

Edited January 2, 2005 by Liger

[Fred Derf Veteran]

[Moved to Essential Guides]

[zedaxax]

merci - will study it

hope to make the ultimate extension

[Liger]

OK (Y)

[Andrew Lyle Global Moderator]

awesome... thanks man...

i will also have to read into this a little more. good for getting people to make better extensions

[burning_jonny]

This is great! Thanks for the link. I will definitely be reading up on this (Y)

[shuangyefei]

I will learn by heart,thanks for the guide.

[Nelsinho]

very interesting, thanks for the guide (Y)

[hadiz]

Very good guide, thanks.

[.:Daemon:.]

Jeez, that's a huge guide, i can't be bothered to read all that. :pinch:

But since i always wanted to make an extension.. i'll read it. :D

Nice guide, by the way.

[Advance]

Amazing guide, I might try it!

[Techno_Funky]

awesome guide man

:yes:

[supernova_00]

great guide man!

[Kilroy-was-here]

Awesome guide, very useful :)

[insanekiwi]

good guide (Y)

[galoosh33]

Wow amazing guide, it seems really cool! I will definetly try this later.

Do you create real extensions too? And how about one for IE/Maxthon?

Anyway GJ (Y)

[nvizible]

woah! nice guide dude... one of the most in-depth guides i've seen! however, its just a pity i use opera ^^

[Liger]

Wow amazing guide, it seems really cool! I will definetly try this later.

Do you create real extensions too? And how about one for IE/Maxthon?

Anyway GJ (Y)

585278611[/snapback]

Yes I make extensions but mostly for personal use :) Maybe I will release one.....

I have this one extension that creates a sort of tool bar or icon area where you can choose what it should display for example : you ip address or latest news via xml, email count etc. I havent named it yet :)

[nav1]

I can't see the download link for the files

[Liger]

I can't see the download link for the files

585339875[/snapback]

:huh:

[CrisCr0ss]

Can you please fix the images thanks

[Iman N.Karimi]

hey dude, thanks alot :)

[FMKaiba]

*bump*

i have an extension i am making. basically done. but i need the extension have RSS suppot

i am making an extenion that is a dropdown menu. i have it all working and fine. but does anyone know how to get it to use an RSS bookmark?

like a standard live bookmark. i know it can be done. hell, firefoxes ?go? dropdown can have those.

but does anyone know how to define them in an extention? (used as a news update for my site that broadcasts rss)

like when you mouse over it it does the menu to the side thats the firefox RSS showing all the news items

[chopyaedoff]

WTF did you bump a year old thread - this guide needs updating (for FF 1.5) and the images relinked.

[Unholy Moley!]

An excelent guide, but it needs updating and fixing of the images before I can give it a 5.