Jetpack/FAQ

Add-on Builder and Add-on SDK are tools that let developers make great add-ons using HTML, JavaScript and CSS. Developers have the choice of working in an online hosted environment with the Add-on Builder or locally through a command line interface with the Add-on SDK.

Add-on Builder and Add-on SDK are two products in the Jetpack project; with a goal to make building add-ons even easier for developers.

General

What is the Add-on SDK?

The Add-on SDK is a downloadable software development kit for building Firefox add-ons in a command line interface environment. It includes high-level APIs for interacting with and modifying web pages and Firefox's user interface along with tools for creating, testing, and packaging add-ons.

What is the Jetpack SDK?

Jetpack SDK is the old name for the Add-on SDK.

What are the benefits of using the Add-on SDK and Add-on Builder?

These tools lets you build Firefox add-ons using common web technologies like HTML, JavaScript and CSS, and it includes tools to make it easy to create, test, and package add-ons.

The tools are designed to produce add-ons that will be forwards-compatible with future versions of Firefox, so you won't need to update your add-on every time a new version of Firefox is released. Add-on SDK and Add-on Builder-based add-ons benefit from a security model that limits the harm that can be caused by a vulnerability in add-on code.

Finally, the Add-on SDK and Add-on Builder implement the CommonJS Packages and Modules specifications to enable a rich ecosystem of third-party APIs that developers can use to build their add-ons in addition to the APIs built into the Add-on SDK itself. We maintain a page listing some of the extra third-party APIs you can use in your add-on.

What are the benefits to users of add-ons created with the Add-on SDK and Add-on Builder?

Add-ons created with the Add-on Builder or the Add-on SDK are restartless by default, meaning users can install and remove add-ons built with these tools instantly, without interrupting their browser experience through a browser restart. This makes it easier to try add-ons and personalize their browsing experience.

Developers and users alike also will not have to worry about add-on compatibility with new versions of Firefox.

Can I do everything with the Add-on SDK and Add-on Builder that I could with a XUL-based add-on? Should I rewrite my XUL-based add-on now?

You can do nearly everything with an Add-on SDK and Add-on Builder based add-on that you can do with a XUL-based add-on, including:

• modifying XUL windows
• accessing XPCOM components
• loading your own XPCOM components, both binary and JavaScript.

You have to do some things differently: in particular, you can't use XUL overlays in Builder / SDK-based add-ons because they are not compatible with restartless add-ons. Instead, you have to use DOM manipulation.

Add-on Builder and the Add-on SDK are aimed primarily at Web developers who wish to write add-ons but are unfamiliar with the traditional XUL-based approach. So it supports a set of easy-to-use high level JavaScript APIs which address the most common use cases encountered by add-on developers. Using only the high level APIs, you can't do everything a XUL-based add-on can do.

However, we're adding to the set of high level APIs, to make it easier to write advanced add-ons using the SDK and Builder.

So if you're a XUL add-on developer, an early adopter, and are willing to participate in the development process, then now is a great time to try out the Add-on SDK and Add-on Builder and help us figure out the right set of features to enable you to make the transition.

What do I need to know to write an add-on using the Add-on Builder and Add-on SDK?

You'll develop add-ons using JavaScript, and you'll interact with web content via the DOM. You'll use HTML and CSS to structure and style your own user interface components.

What are the system requirements for the Add-on Builder?

You need a current version of Firefox, and an Internet connection.

What are the system requirements for the Add-on SDK?

You need Python 2.5, 2.6, or 2.7, and a current version of Firefox.

If you're running Windows, MozillaBuild, while not mandatory, will install the correct version of Python and the MSYS package, which will make it easier to work with the SDK.

Will the Add-on SDK be fully integrated into Firefox?

The Add-on SDK is currently a separate product from Firefox. But we are investigating ways in which the SDK could be integrated into Firefox.

Do users need to download or install anything to use Add-on SDK and Add-on Builder based add-ons?

No. Users only need to install the SDK/Builder based add-ons themselves, which are all hosted in the same place as traditional XUL-based add-ons: addons.mozilla.org.

Will Mozilla stop supporting XUL-based add-ons?

Mozilla has no plans to stop supporting XUL-based add-ons, and it would be premature to start making such plans, as the vast majority of Firefox add-ons are XUL-based.

If at some point in the future that ratio changes, and the vast majority of Firefox add-ons are Builder/SDK-based, then it may make sense to consider deprecating XUL-based add-ons.

What about Firefox Mobile?

The Jetpack team's current focus is creating the best possible experience for developers of desktop Firefox add-ons. We are well aware, however, of the importance of mobile Firefox to Mozilla and its users, and we plan to prioritize mobile Firefox add-on development in a future release of the Add-on SDK and Add-on Builder.

In version 1.5 the SDK started to offer experimental support for the native version of Firefox Mobile.

What is Jetpack?

Jetpack is a project to make it easy to build Firefox add-ons using common web technologies like HTML, JavaScript, and CSS. Our goal is to enable anyone who can build a web site to participate in making the Web a better place to work, communicate, and play.

I have a Google Chrome plugin/Safari add-on. Will it work as a Firefox add-on?

You will need to do some porting, but the changes should be relatively straightforward. David Morgan has written an extension for Chrome and Firefox that shares much of the code: http://code.google.com/p/scry/.

Programming

Building a UI

How can I place my add-on's widget in a different part of the Firefox UI?

You can only place widgets in the add-on bar, although users can move them from there to another toolbar.

The purpose of the add-on bar is to consolidate add-on buttons/icons/widgets in a known location in the browser chrome, so that users who install an add-on with a UI will know where to look for it.

How can I make a Widget look and behave differently in different windows?

Use a WidgetView.

How can I have a Preferences UI/Options UI for my add-on?

The simple-prefs module offers basic support for preferences.

Why can't I create Firefox toolbars using the Add-on SDK / Add-on Builder?

In the past, we haven't provided much guidance to add-on developers about how best to integrate their user interfaces into Firefox, and the add-ons manager did not make it easy for users to access an add-on's preferences. The result of this has been a proliferation of toolbars and menu items, which can lead to a cluttered and confusing user experience.

Therefore in the Add-on SDK and Add-on Builder, the preferred way for add-ons to expose a permanent user interface is through the widget API, which will ensure that the user interfaces for all add-ons default to a standard location (the add-on bar) where users will expect to see them.

Can I add items to Firefox's menus in my add-on?

No you cannot. You can add items to the context menu, but not the main menu. We'll add support for this in a future release. There is a "menu items" module listed in the Additional Modules page, that enables you to do this.

How can I customize my widget's context menu?

That's not currently possible.

My add-on needs to prompt the user to select a file. Is there a module in the Add-on SDK to help me with this?

Not in the core set, but you can find a external file selection module in the Additional Modules page.

Interacting With the Web

Why can't my add-on code access web content directly?

The SDK and Builder enforce a separation between:

• the main add-on code, which has access to SDK APIs and even XPCOM objects, but can't access web content
• content scripts, which can interact directly with web content, but don't get access to the SDK APIs or XPCOM

This is for two reasons:

Security

Code that interacts directly with web content is more likely to become compromised by malicious web pages. If this code is given access to powerful APIs, then a malicious web page can do much more damage, including access to the user's local file system and cross-domain network requests. See this blog post on the SDK's security mechanisms, and this study on browser extension security.

Multi-process support

The Mozilla platform intended to move towards a model in which it uses separate processes to display the UI, handle web content, and execute add-ons. This is expected to improve the responsiveness of the UI, application stability, and performance, especially on multi-core machines.

In this architecture the main add-on code will run in the add-on process and will not have direct access to any web content.

At the moment this work is on hold: but it is still likely to happen in the future. Add-on SDK and Add-on Builder are designed to be forward compatible with the change, so that when this happens you won't need to rewrite add-ons written using the Add-on SDK / Add-on Builder.

What's a content script?

A content script is a script that runs in the context of a web page. If you need to interact with web content in your add-on, you will use a content script to access and manipulate web content.

Content scripts don't share an execution context with add-on code, so code in a content script can't directly access variables and functions in the add-on code or vice versa. Instead, you communicate between content scripts and add-on code using a message-passing scheme.

I have a panel hosting some content, and it has a content script associated with it. Whenever the panel's location changes the content script stops working, and gives me this error: "ERR_DESTROYED, "The page has been destroyed and can no longer be used." How can I fix this?

The best workaround for this is to load the panel's document in an iframe, and change that. Then the panel's content scripts will continue to work.

How can I run a content script in the context of the currently active tab?

Use tab.attach().

How can I assign a value in a content script to a variable in my main add-on script?

You might try to do something like this:

var a = 1; 

var pageMod = require("page-mod"); 
pageMod.PageMod({ 
include: "*", 
contentScriptWhen: "ready", 
contentScript: "a = 2;"
}); 

This isn't going to work, because the content script ""a = 2;"" is running in a different context to the main script, and can't see the declaration of a. You'd need to pass the value as a message to the add-on script, and do the assignment in there:

var a = 1; 

var pageMod = require("page-mod"); 
pageMod.PageMod({ 
include: "*", 
contentScriptWhen: "ready", 
contentScript: "self.postMessage(2);", 
onAttach: function onAttach(worker) {
worker.on("message", function(data) {
  a = data;
  });
}
});

General Programming

Why doesn't window.alert() work in my add-on?

On the web, JavaScript executes in the context of a web page, and has access to that page's DOM content. This enables you to call functions like window.alert(), and to access the document object. But these are DOM features, not JavaScript features.

The add-on code does not execute in the context of a page, and the DOM is therefore not available. To access the DOM of a particular page, you need to use a content script.

Standard JavaScript APIs, such as Array and JSON, are available to add-on code.

See https://developer.mozilla.org/en/The_DOM_and_JavaScript for a good summary of the difference between the DOM and JavaScript, and this SDK guide for a summary of the APIs that are and are not available to add-on code.

For debugging purposes you can log strings to the console using the global console object.

Can I use XUL in an Add-on SDK / Add-on Builder based add-on?

Yes. However, some of the features of the traditional XUL-based add-on platform, such a XUL overlays, are not available to Builder / SDK - based add-ons because they are incompatible with instant install/removal of add-ons or loading add-ons in separate processes.

Can I use jQuery in my add-on?

Yes, you can. Just add it as another content script. See the 'reddit-panel' example in the Add-on SDK.

Can I use other CommonJS modules like node.js in my add-on?

Not yet, although we plan to add this ability.

Can I use Add-on SDK / Add-on Builder modules in a traditional XUL extension?

Not yet, although we plan to add this ability.

Is there a Socket API in the Add-on SDK?

Not in the core set, but you can find a external sockets module in the Additional Modules page.

What's the local path on disk for my add-on's data directory?

The add-on's data directory does not map to a particular location on disk. The require("self").data.url(name) function will give you a URL that's usable from within the addon itself (e.g. as a content script).

How can I read from/write to a file?

You can use the file module. However, if you just need some persistent storage and don't need the data to be available outside your add-on, you can use the simple-storage module.

How can I access data from my add-on's 'package.json' file, such as my add-on's name or version number?

Use the self module.

How can I debug my add-on?

You can run debuggers such as Venkman and Chromebug by:

1. specifying a profile that has these add-ons installed via the cfx --profiledir option
2. passing the -venkman or -chromebug argument to Firefox using the cfx --binary-args option:

cfx --profiledir /my/profile/name --binary-args -chromebug run

How can I localize strings appearing in my add-on?

The 1.5 release of the SDK delivers the first stage of support for localization. See the tutorial. Note that at the moment you can only localize strings appearing in code, not strings inside HTML content.

Using Builder

Builder lacks end-user documentation; what follows are some common issues encountered when trying to use builder.

• Adding preferences or other custom values to package.json: To add preferences to package.json for an add-on you've created using builder, you need to take the following steps:

1. Click on the 'gear' button to open the add-on properties dialog.
2. In the field at the bottom of the dialog labeled 'Extra package.json Properties', paste in your JSON properties:

{
	"preferences": [{
	       "name": "somePreference",
	       "title": "Some preference title",
	       "type": "string",
	       "value": "this is the default string value"
	   },
	   {
	       "name": "integerPreference",
	       "title": "Integer preference title",
	       "type": "integer",
	       "value": 10
	   },
	   {
	       "name": "booleanPreference",
	       "title": "Boolean preference title",
	       "type": "bool",
	       "value": false
	   },
           {
               "name": "buttonPreference",
               "title": "Button preference title",
               "type": "control",
	       "label": "Text that appears in the button"
           }]
}

Please note that the JSON fragment requires the enclosing curly braces - in other words the pasted text needs to be a complete JSON value.