To create add-ons for Firefox using the SDK, you'll first need to follow the instructions to install and activate the SDK. Installation is something you only need to do once: activation is something you need to do for each command prompt you open.
Once you've done that, you'll be looking at a command prompt.
If you're on Linux or Mac OS X, the prompt should start with the name of the SDK's root directory:
(addon-sdk)~/mozilla/addon-sdk >
If you're on Windows, the prompt should start with the full path to your SDK installation:
(C:\Users\mozilla\sdk\addon-sdk) C:\Users\Work\sdk\addon-sdk>
In the command prompt, create a new directory. The directory doesn't have to be under the SDK root: you can create it anywhere you like. Navigate to it, type cfx init, and hit enter:
mkdir my-addon
cd my-addon
cfx init
You'll see some output like this:
* lib directory created
* data directory created
* test directory created
* doc directory created
* README.md written
* package.json written
* test/test-main.js written
* lib/main.js written
* doc/main.md written
Your sample add-on is now ready for testing:
try "cfx test" and then "cfx run". Have fun!"
Now you can write the add-on's code, which goes in the "main.js" file in your lib directory. This file was created for you in the previous step. Open it and add the following code:
var widgets = require("sdk/widget");
var tabs = require("sdk/tabs");
var widget = widgets.Widget({
id: "mozilla-link",
label: "Mozilla website",
contentURL: "http://www.mozilla.org/favicon.ico",
onClick: function() {
tabs.open("http://www.mozilla.org/");
}
});
Save the file. Back at the command prompt, type:
cfx run
This is the SDK command to run a new instance of Firefox with your add-on installed. When Firefox launches, in the bottom-right corner of the browser you'll see an icon with the Mozilla logo. Click the icon, and a new tab will open with http://www.mozilla.org/ loaded into it.
That's all this add-on does. It uses two SDK modules: the widget module, which enables you to add buttons to the browser, and the tabs module, which enables you to perform basic operations with tabs. In this case, we've created a widget whose icon is the Mozilla favicon, and added a click handler that loads the Mozilla home page in a new tab.
Try editing this file. For example, we could change the icon displayed and the page that gets loaded:
var widgets = require("sdk/widget");
var tabs = require("sdk/tabs");
var widget = widgets.Widget({
id: "jquery-link",
label: "jQuery website",
contentURL: "http://www.jquery.com/favicon.ico",
onClick: function() {
tabs.open("http://www.jquery.com/");
}
});
At the command prompt, execute cfx run again. This time the icon is the jQuery favicon, and clicking it takes you to http://www.jquery.com.
When you've finished the add-on and are ready to distribute it, you'll need to package it as an XPI file. This is the installable file format for Firefox add-ons. You can distribute XPI files yourself or publish them to https://addons.mozilla.org so other users can download and install it.
To build an XPI, just execute the command cfx xpi from the add-on's directory:
cfx xpi
You should see a message like:
Exporting extension to my-addon.xpi.
To test that this worked, try installing the XPI file in your own Firefox installation.
You can do this by pressing the Ctrl+O key combination (Cmd+O on Mac) from within Firefox, or selecting the "Open" item from Firefox's "File" menu.
This will bring up a file selection dialog: navigate to the my-addon.xpi file, open it and follow the prompts to install the add-on.
In this tutorial we've built and packaged an add-on using three commands:
cfx initto initialize an empty add-on templatecfx runto run a new instance of Firefox with the add-on installed, so we can try it outcfx xpito package the add-on into an XPI file for distribution
These are the three main commands you'll use when developing SDK add-ons. There's comprehensive reference documentation covering all the commands you can use and all the options they take.
The add-on code itself uses two SDK modules, widget and tabs. There's reference documentation for all the high-level and low-level APIs in the SDK.
To get a feel for some of the things you can do with the SDK APIs, try working through some of the tutorials.
The SDK modules you use to implement your add-on are built into Firefox. When you run or package an add-on using cfx run or cfx xpi, the add-on will use the versions of the modules in the version of Firefox that hosts it.
As an add-on developer, this is usually what you want. But if you're developing the SDK modules themselves, of course, it isn't. In this case it's assumed that you have checked out the SDK from its GitHub repo and will have run source/activate from the root of your checkout.
Then when you invoke cfx run or cfx xpi, you pass the "-o" option:
cfx run -o
This instructs cfx to use the local copies of the SDK modules, not the ones in Firefox.
Because cfx run restarts the browser each time you invoke it, it can be a little cumbersome if you are making very frequent changes to an add-on. An alternative development model is to use the Extension Auto-Installer add-on: this listens for new XPI files on a specified port and installs them automatically. That way you can test new changes without needing to restart the browser:
- make a change to your add-on
- run cfx xpi
- post the add-on to the port specified
You could even automate this workflow with a simple script. For example:
while true ; do cfx xpi ; wget --post-file=codesy.xpi http://localhost:8888/ ; sleep 5 ; done
Note that the logging level defined for the console is different when you use this method, compared to the logging level used when an add-on is run using cfx run. This means that if you want to see output from console.log() messages, you'll have to tweak a setting. See the documentation on logging levels for the details on this.
Fabulous! https://bugzilla.mozilla.org/show_bug.cgi?id=967866