Introduction

This interactive API reference should be just enough to get you started. Jetpack has a wealth of APIs, however, and not all are described here. Visit the online documentation for the full, community-supported reference.

The Global Namespace

The global namesace of a Jetpack Feature is where most of its functionality can be found. Special care has been taken to make this namespace look and function as much like a Web page's global namespace as possible.
XMLHttpRequest provides an easy way to retrieve data at a URL. Check out its reference documentation for more information.

Unlike the class of the same name available to web content, the XMLHttpRequest object available to Jetpacks can access data at any domain.

Note that jQuery is also available to Jetpacks, and it provides a very simple API to XMLHttpRequest functionality. See the jQuery Ajax documentation for more information.

The jetpack namespace is available to all Jetpack Features, and is the main point of contact for Features with the rest of Firefox. The API is intended as a lightweight backwards-compatible facade to the underlying Mozilla platform, which means that if you write a Feature using the Jetpack library, you won't have to change your code as Firefox continues to evolve.
This object grants access to the user's current selection. It allows reading out of the selection as text or html. Additionally it allows Jetpack Features to listen for when the user changes selections.

This selection object is currently experimental, so load it with:

jetpack.future.import("selection");

See JEP 12: Selection for documentation on how to use jetpack.selection. Or install a demo feature, Selection Demo and check its source for a more hands-on approach.

This object contains methods relevant to the Jetpack-added SlideBar that appears at the left side of the browser window when the user's pointer moves towards the icon on the left of the tab-strip. Features can add an icon and have the SlideBar open to display additional content and then slide away when the user returns to the page.

This slideBar object is currently experimental, so load it with:

jetpack.future.import("slideBar");

See JEP 16: SlideBar for documentation on how to use jetpack.slideBar. Or install a demo feature, Video Slide - SlideBar Demo and check its source for a more hands-on approach.

This object contains methods relevant to the status bar that appears at the bottom of the browser window. Note that the user has the option to disable the display of the status bar in Firefox's "View" menu.
The initial HTML contents of the new status bar panel. The URL of the status bar panel's HTML contents. Size of the content area to render html or url, in pixels. The callback function to invoke when the new panel is created on a status bar.
This function adds a new panel to the status bar of all open browser windows. When any new browser windows open, the panel is automatically added to them as well.

The following example embeds an icon into the status bar that, when clicked, displays a notification message to the user.

jetpack.statusBar.append({ html: '', width: 16, onReady: function(doc) { $(doc).find("img").click(function() { jetpack.notifications.show("hai2u"); }); }});

Technically speaking, the status bar panel is an iframe element. While this comes at a relatively high resource cost, it also enables the full breadth of generativity that the Web has to offer. In the future, we may add additional parameters to this function allowing the addition of simpler, less resource-intensive elements such as static text labels and images.

This object contains everything related to permanent and temporary storage.
See the Simple Persistent Storage JEP.

The simple storage is sandboxed to each Jetpack, so that you never have to worry about collisions with somebody else's code.

Here's a quick example of how to use the simple storage API:

jetpack.future.import("storage.simple"); var myStorage = jetpack.storage.simple; myStorage.forever = { hello: "world" };

And then later:

jetpack.future.import("storage.simple"); console.log(jetpack.storage.simple.forever.hello);

That's all there is to it! Simply treat the jetpack.storage.simple object the same way you would any regular JavaScript object. The properties attached to it will automatically be saved.

You can attach any object to jetpack.storage.live and it will be available for you to use until Firefox is restarted. For example:
jetpack.storage.live.myData = {hello: "world"}; console.log( jetpack.storage.live.myData );
This object provides access to the system clipboard. See the Clipboard JEP for a complete API reference.

Here's a quick example demonstrating how to set and get text from the clipboard.

jetpack.future.import("clipboard"); jetpack.clipboard.set("So long and thanks for all the fish!"); console.log(jetpack.clipboard.get());
Eventually, this object will be the end-all be-all of easy communication with your users. Notification bars, transparent messages, Growls, doorknob messages, and so forth will all go through here. For now, it just has simple notifications.
The title of the notification. The URL to the notification's icon. The body of the notification.
This function displays a simple notification message. On Windows and Linux it's a toaster notification, and on OS X it's a Growl message (if Growl is installed). Instead of passing in an options object, the caller can simply pass in a string, which is used as the body argument.

The following example displays a message with a title, icon, and body.

jetpack.notifications.show({title: 'hai2u', body: 'o hai.', icon: 'http://www.mozilla.org/favicon.ico'});
jetpack.tabs is a live array with special tab-related properties.
The currently focused/active tab as a Tab object.

The following example displays the name of the currently focused tab.

jetpack.notifications.show(jetpack.tabs.focused.url);
This object is used to log messages to the for debugging purposes. Use the methods log, info, warn, and error to log messages of varying importance. All of these methods can take any number of arguments; all of the arguments are logged.

The following example logs some information to the console.

console.log('Hello from the Jetpack Feature', this);
This function works just like the Web's window.setInterval() function.
This function works just like the Web's window.clearInterval() function.
This function works just like the Web's window.setTimeout() function.
This function works just like the Web's window.clearTimeout() function.
This is jQuery, a lightweight JavaScript library. For convenience, it's also available as the $ function.

All Ajax requests made using jQuery are done using a cross-site XMLHttpRequest object.

For more information on jQuery, please consult the jQuery Documentation.
This string contains the URL representing the source code of the Feature.

The following example logs the location to the console.

console.log(location);

Tab Objects

A Tab represents a tab in a browser window.
The HTML document that the tab is currently displaying. If the tab is closed, this value is null.
The window that the tab is currently displaying (to the Web page in the tab, this is known as window). If the tab is closed, this value is null.
The underlying XUL tab element that this tab represents. Access this as a last resort, since anything done with this object is subject to changes in the Mozilla platform.

If the tab is already closed, this value is null.

A boolean indicating whether or not the tab is closed. This can be the case if, for instance, your code assigns a variable to a tab and later references it after the tab has been closed.
Makes the tab the currently selected one.
Closes the tab. If the tab is already closed, this method does nothing.
A string representing the URL that the tab is currently viewing. If the tab is closed, this value is null.
A string representing the URL of the tab's favicon. If the tab has no favicon or is closed, this value is null.
A live array is an Array that represents some aspect of system state and has no mutator methods, and is effectively "read-only". In particular, this includes pop(), push(), reverse(), shift(), sort(), splice(), and unshift().

While it's technically possible for the array indices of an live array to be modified, they shouldn't be.

The callback to call when the event is triggered.
A live event binder that is triggered whenever a Tab object is closed.

This binder method is available on Tab objects and the jetpack.tabs live array.

Event handlers registered with this event binder are currently not passed any arguments. When called, their this variable is set to the Tab object on which the event was triggered.

The following example code uses the jetpack.tabs.onClose handler to display a notification message whenever the user closes a tab.

jetpack.tabs.onClose(function() { jetpack.notifications.show("You closed " + this.url); });
The callback to call when the event is triggered.
A live event binder that is triggered whenever a Tab object becomes the currently selected tab.

This binder method is available on Tab objects and the jetpack.tabs live array.

Event handlers registered with this event binder are currently not passed any arguments. When called, their this variable is set to the Tab object on which the event was triggered.

The following example code uses the jetpack.tabs.onFocus handler to display a notification message whenever the user switches to a new tab.

jetpack.tabs.onFocus(function() { jetpack.notifications.show("You selected " + this.url); });
The callback to call when the event is triggered.
A live event binder that is triggered whenever a Tab object's containing HTML document, or one of its sub-documents (e.g., an iframe), has finished loading its DOM. At a purely technical level, this is triggered when the target document's DOMContentLoaded event is fired.

This binder method is available on Tab objects and the jetpack.tabs live array.

Event handlers registered with this event binder are passed the HTML document of the object that triggered the event. When called, their this variable is set to the Tab object on which the event was triggered.

The following example code uses the jetpack.tabs.onReady handler to display a notification message the next time the user visits a page.

jetpack.tabs.onReady(function onNextPage(doc) { if (!doc.defaultView.frameElement) { jetpack.notifications.show("Loaded " + doc.location.href); jetpack.tabs.onReady.unbind(onNextPage); }});
A standard JavaScript number, e.g., 12.
A JavaScript string representing a URL. For example, "http:///www.imdb.com".
A standard immutable JavaScript string. For example, "hai2u".
A JavaScript Object representing the arguments to a function, where each property of the object represents the name and value of an argument.

An Options Object is useful when a function takes many arguments whose order would be difficult to remember; it's especially useful when some or all of those arguments are optional.

A standard JavaScript function. For example, function(x) { return x + 1; }.
This is the standard DOM document object, which is commonly known within web pages as the document variable. If you need to access the web page's window object through its document, use document.defaultView.
An event handler is just a function that is called whenever a particular event occurs. It's usually passed a single argument that contains specific information about the event that was triggered.
A live event binder is a method of a parent object, usually beginning with the prefix on, which allows a client to be notified, via a callback function, whenever an event occurs on the parent object.

If the parent object is a live array, then the client is notified whenever the relevant event is fired on any member of the live array, even if the member wasn't in the live array when the event binding was created. For an example of this, see jetpack.tabs.onReady.

Every live event binder method itself has a method called unbind, which can be passed a callback to unbind. For an example, see jetpack.tabs.onReady.