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 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.