Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.
From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).
From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.
Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
This tutorial describes the use of low-level APIs. These APIs are still in active development, and we expect to make incompatible changes to them in future releases.
The guide to event-driven programming with the SDK describes how to consume events: that is, how to listen to events generated by event targets. For example, you can listen to the tabs
module's ready
event or the Panel
object's show
event.
With the SDK, it's also simple to implement your own event targets. This is especially useful if you want to build your own modules, either to organize your add-on better or to enable other developers to reuse your code. If you use the SDK's event framework for your event targets, users of your module can listen for events using the SDK's standard event API.
In this tutorial we'll create part of a module to access the browser's Places API. It will emit events when the user adds and visits bookmarks, enabling users of the module to listen for these events using the SDK's standard event API.
Using the Places API
First, let's write some code using Places API that logs the URIs of bookmarks the user adds.
Create a new directory called "bookmarks", navigate to it, and run jpm init
, accepting all the defaults. Then open "index.js" and add the following code:
var {Cc, Ci} = require("chrome"); var { XPCOMUtils } = require("resource://gre/modules/XPCOMUtils.jsm"); var bookmarkService = Cc["@mozilla.org/browser/nav-bookmarks-service;1"] .getService(Ci.nsINavBookmarksService); var bookmarkObserver = { onItemAdded: function(aItemId, aFolder, aIndex) { console.log("added ", bookmarkService.getBookmarkURI(aItemId).spec); }, onItemVisited: function(aItemId, aVisitID, time) { console.log("visited ", bookmarkService.getBookmarkURI(aItemId).spec); }, QueryInterface: XPCOMUtils.generateQI([Ci.nsINavBookmarkObserver]) }; exports.main = function() { bookmarkService.addObserver(bookmarkObserver, false); }; exports.onUnload = function() { bookmarkService.removeObserver(bookmarkObserver); }
Try running this add-on, adding and visiting bookmarks, and observing the output in the console.
Modules as Event Targets
We can adapt this code into a separate module that exposes the SDK's standard event interface.
To do this we'll use the event/core
module.
Create a new file in "lib" called "bookmarks.js", and add the following code:
var { emit, on, once, off } = require("sdk/event/core"); var {Cc, Ci} = require("chrome"); var { XPCOMUtils }= require("resource://gre/modules/XPCOMUtils.jsm"); var bookmarkService = Cc["@mozilla.org/browser/nav-bookmarks-service;1"] .getService(Ci.nsINavBookmarksService); var bookmarkObserver = { onItemAdded: function(aItemId, aFolder, aIndex) { emit(exports, "added", bookmarkService.getBookmarkURI(aItemId).spec); }, onItemVisited: function(aItemId, aVisitID, time) { emit(exports, "visited", bookmarkService.getBookmarkURI(aItemId).spec); }, QueryInterface: XPCOMUtils.generateQI([Ci.nsINavBookmarkObserver]) }; bookmarkService.addObserver(bookmarkObserver, false); exports.on = on.bind(null, exports); exports.once = once.bind(null, exports); exports.removeListener = function removeListener(type, listener) { off(exports, type, listener); };
This code implements a module which can emit added
and visited
events. It duplicates the previous code, but with a few changes:
- import
emit()
,on()
,once()
, andoff()
fromevent/core
- replace listener functions with calls to
emit()
, passing the appropriate event type - export its own event API. This consists of three functions:
on()
: start listening for events or a given typeonce()
: listen for the next occurrence of a given event, and then stopremoveListener()
: stop listening for events of a given type
The on()
and once()
exports delegate to the corresponding function from event/core
, and use bind()
to pass the exports
object itself as the target
argument to the underlying function. The removeListener()
function is implemented by calling the underlying off()
function.
We can use this module in the same way we use any other module that emits module-level events, such as tabs
. For example, we can adapt "index.js" as follows:
var bookmarks = require("./bookmarks"); function logAdded(uri) { console.log("added: " + uri); } function logVisited(uri) { console.log("visited: " + uri); } exports.main = function() { bookmarks.on("added", logAdded); bookmarks.on("visited", logVisited); }; exports.onUnload = function() { bookmarks.removeListener("added", logAdded); bookmarks.removeListener("visited", logVisited); }
Classes as Event Targets
Sometimes we want to emit events at the level of individual objects, rather than at the level of the module.
To do this, we can inherit from the SDK's EventTarget
class. EventTarget
provides an implementation of the functions needed to add and remove event listeners: on()
, once()
, and removeListener()
.
In this example, we could define a class BookmarkManager
that inherits from EventTarget
and emits added
and visited
events.
Open "bookmarks.js" and replace its contents with this code:
var { emit } = require("sdk/event/core"); var { EventTarget } = require("sdk/event/target"); var { Class } = require("sdk/core/heritage"); var { merge } = require("sdk/util/object"); var {Cc, Ci} = require("chrome"); var { XPCOMUtils } = require("resource://gre/modules/XPCOMUtils.jsm"); var bookmarkService = Cc["@mozilla.org/browser/nav-bookmarks-service;1"] .getService(Ci.nsINavBookmarksService); function createObserver(target) { var bookmarkObserver = { onItemAdded: function(aItemId, aFolder, aIndex) { emit(target, "added", bookmarkService.getBookmarkURI(aItemId).spec); }, onItemVisited: function(aItemId, aVisitID, time) { emit(target, "visited", bookmarkService.getBookmarkURI(aItemId).spec); }, QueryInterface: XPCOMUtils.generateQI([Ci.nsINavBookmarkObserver]) }; bookmarkService.addObserver(bookmarkObserver, false); } var BookmarkManager = Class({ extends: EventTarget, initialize: function initialize(options) { EventTarget.prototype.initialize.call(this, options); merge(this, options); createObserver(this); } }); exports.BookmarkManager = BookmarkManager;
The code to interact with the Places API is the same here. However:
- we're now importing from four modules:
event/core
gives usemit()
: note that we don't needon
,once
, oroff
, since we will useEventTarget
for adding and removing listenersevent/target
gives usEventTarget
, which implements the interface for adding and removing listenerscore/heritage
gives usClass()
, which we can use to inherit fromEventTarget
util/object
gives usmerge()
, which just simplifies setting up theBookmarkManager
's properties
- we use
Class
to inherit fromEventTarget
. In itsinitialize()
function, we:- call the base class initializer
- use
merge()
to copy any supplied options into the newly created object - call
createObserver()
, passing in the newly created object as the event target
createObserver()
is the same as in the previous example, except that inemit()
we pass the newly createdBookmarkManager
as the event target
To use this event target we can create it and call the on()
, once()
, and removeListener()
functions that it has inherited:
var bookmarks = require("./bookmarks"); var bookmarkManager = bookmarks.BookmarkManager({}); function logAdded(uri) { console.log("added: " + uri); } function logVisited(uri) { console.log("visited: " + uri); } exports.main = function() { bookmarkManager.on("added", logAdded); bookmarkManager.on("visited", logVisited); }; exports.onUnload = function() { bookmarkManager.removeListener("added", logAdded); bookmarkManager.removeListener("visited", logVisited); }
Implementing "onEvent" Options
Finally, most event targets accept options of the form "onEvent", where "Event" is the capitalized form of the event type. For example, you can listen to the Panel
object's show
event either by calling:
myPanel.on("show", listenerFunction);
or by passing the onShow
option to Panel
's constructor:
var myPanel = require("sdk/panel").Panel({ onShow: listenerFunction, contentURL: "https://en.wikipedia.org/w/index.php" });
If your class inherits from EventTarget
, options like this are automatically handled for you. For example, given the implementation of BookmarkManager
above, your "index.js" could be rewritten like this:
var bookmarks = require("./bookmarks"); function logAdded(uri) { console.log("added: " + uri); } function logVisited(uri) { console.log("visited: " + uri); } var bookmarkManager = bookmarks.BookmarkManager({ onAdded: logAdded, onVisited: logVisited }); exports.onUnload = function() { bookmarkManager.removeListener("added", logAdded); bookmarkManager.removeListener("visited", logVisited); }