getting-started-with-cfx.md

This tutorial assumes that you've read and followed the instructions in the installation guide, to install and activate the SDK.

Getting Started With cfx

To create add-ons using the SDK you'll have to get to know the cfx command-line tool. It's what you'll use for testing and packaging add-ons.

There's comprehensive reference documentation covering everything you can do using cfx, but in this tutorial we'll introduce the three commands you need to get going:

• cfx init : creates the skeleton structure for your add-on
• cfx run : runs an instance of Firefox with your add-on installed
• cfx xpi : build an installable XPI file to distribute your add-on

cfx init

You use cfx init to create the basic skeleton for your add-on.

Create a new directory, navigate to it in your command shell, and run cfx init:

mkdir my-addon
cd my-addon
cfx init

You don't have to create this directory under the SDK root: once you have activated from the SDK root, cfx will remember where the SDK is, and you will be able to use it from any directory.

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!"

cfx run

Use cfx run to run a new instance of Firefox with your add-on installed. This is the command you'll use to test out your add-on while developing it.

The main code for an add-on is always kept in a file called main.js in your add-on's lib directory. Open the main.js for this add-on, and add the following code:

var widgets = require("widget");
var tabs = require("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/");
  }
});

Now type:

cfx run

The first time you do this, you'll see a message like this:

No 'id' in package.json: creating a new ID for you.
package.json modified: please re-run 'cfx run'

Run cfx run again, and it will run an instance of Firefox. In the bottom-right corner of the browser you'll see an icon with the Firefox logo. Click the icon, and a new tab will open with http://www.mozilla.org/ loaded into it.

This add-on 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 URL that gets loaded:

var widgets = require("widget");
var tabs = require("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, and this time the icon is the jQuery favicon, and clicking it takes you to http://www.jquery.com.

cfx xpi

You'll use cfx run while developing your add-on, but once you're done with that, you use cfx xpi to build an XPI file. This is the installable file format for Firefox add-ons. You can distribute XPI files yourself or publish them to http://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.

The my-addon.xpi file can be found in the directory in which you ran the command.

To test it, install it 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.

Now you have the basic cfx commands, you can try out the SDK's features.