Labs/Jetpack/Release Notes/1.0b5
About
Add-on SDK is a software development kit that provides a set of tools and APIs for building, testing, and packaging Firefox add-ons.
The 1.0b5 release is the fifth beta release of the SDK. We expect that it will be the final beta release, and it includes a number of important changes and additions, which are listed below. It also contains the first breaking change in our supported APIs (a change to the default value of contentScriptWhen), and new APIs for communication with content scripts which we expect to replace the existing ones in most cases, although the old APIs are still supported.
Installation
Obtain the SDK in your favorite compression format:
Then unpack the archive, open the addon-sdk-1.0b5/README.txt file, and follow its instructions.
Major Changes
Bug 584064: Hotkeys API
The new hotkeys module enables you to add hotkeys (keyboard shortcuts) to your add-on.
Bug 653187: Deprecation of global messaging primitives
To prevent pollution of the global namespace we've deprecated the following global content script objects:
postMessage(...)
on('message', ...)
onMessage(...)
These objects are now attached to the global self object, except for onMessage, which should be replaced by self.on('message', ...).
| Old-style | New-style |
postMessage(myMessage); |
self.postMessage(myMessage); |
on('message', function(aMessage) {
//
});
|
self.on('message', function(aMessage) {
//
});
|
onMessage = function(aMessage) {
//
};
|
self.on('message', function(aMessage) {
//
});
|
The old APIs are still present for the time being, but the SDK will emit a warning if you use them.
Note that this change only affects code running in content scripts.
Bug 635748: New APIs for communicating with Content Scripts
In previous versions of the SDK, the basic mechanism for communicating between a content script and the main add-on code is the message event. You send messages using postMessage and receive them using on('message', ...).
The problem with this is that as soon as you want to send more than one sort of message between the two sides, you need to embed the message type in the message payload, and then need a switch statement in the other side to dispatch them:
self.postMessage({
kind: 'mouseover',
element: event.target.toString()
});
...
self.postMessage({
kind: 'mouseout',
element: event.target.toString()
});
worker.on('message', function(message) {
switch(message.kind) {
case 'mouseover':
console.log('mouseover: ' + message.element);
break;
case 'mouseout':
console.log('mouseout: ' + message.element);
break;
}
});
We've now introduced support for user-defined events in content scripts, so you can send your own named events between the add-on code and content scripts. So the code above could be rewritten like this:
self.port.emit('mouseover', event.target.toString());
self.port.emit('mouseout', event.target.toString());
worker.port.on('mouseover', function(message) {
console.log('mouseover: ' + message);
});
worker.port.on('mouseout', function(message) {
console.log('mouseout: ' + message);
});
We're not deprecating the old messaging style, but we think the new style will work better in many situations. User-defined events are documented more fully in the Working with Content Scripts guide.
Bug 642447: New default value for contentScriptWhen
We've added a new possible value for contentScriptWhen, called 'end', which corresponds to the window.onload event. We've also changed the default value for contentScriptWhen from 'start' to 'end'.
Note that this is a compatibility break.
It's documented in the Working with Content Scripts guide as well as the API docs for modules that use contentScriptWhen.
Bug 630962: Window-specific widgets
We've introduced a new object called WidgetView, which enables you to change the content of a widget on a per-window basis. You access a WidgetView from an instance of a Widget, the WidgetView is associated with a specific window, and any changes you make to that WidgetView only apply to that window.
WidgetView is part of the Widget API.
Bug 627607: Module resolution at build time
We've rewritten the linker so as to do module resolution at link time rather than build time. You shouldn't notice any difference as a result of this, but it's an essential step towards the new security model, paves the way for reductions in add-on package size, and will eventually enable add-ons to load modules from other CommonJS environments.
There's a good description of the change in the GitHub commit.
Minor Changes
Bug 646345: Add --binary-args argument to cfx
This enables you to pass custom arguments to Firefox, so you can use Firefox features which need to be enabled with a command line argument, such as -chromebug or -jsconsole.
Bug 646343: New cfx option "--no-run"
Rather than launching Firefox, this experimental option displays the command needed to launch the application, which can then be used to launch the application in a debugger like GDB.
Bug 607601: New 'detach' event for Worker objects
This new event is emitted by a Worker object when its associated page is unloaded, either because the host tab is closed or because the location of the host tab changes. Its primary use is documented in the Page-Mod API documentation.
Bug 614712: Change directory names for add-ons: 'docs'->'doc, 'tests' -> 'test'
To match CommonJS we've changed the preferred names of the documentation and test directories for add-ons:
'docs' -> 'doc' 'tests' -> 'test'
cfx init will now generate a skeleton add-on with those names.
Note that add-ons which use the old names will still work perfectly well.
Bug 654588: Remove cryptographic JIDs
The ID values generated for new addons are no longer based upon cryptographic signing keys; now they're just random strings starting with "jid1-". The ~/.jetpack/ directory created by earlier versions can be safely removed, and you should no longer see "cfx xpi" complain about a missing private key.
Known Issues
bug 647527: private browsing activation races tab closure
If an add-on closes a tab and then immediately activates private browsing, the private browsing activation may take effect before the tab closure is recorded in session history, causing the tab to reopen when private browsing is deactivated; alternately, the add-on script may become unresponsive.
bug 556562: mozrunner installation may break cfx test
If you have copy of mozrunner installed on your system, the cfx test command may not work correctly.
HTML <select> menus don't work properly in panels.
bug 641396: first Firefox tab doesn't emit "ready" event
The first Firefox tab in a window doesn't emit the "ready" event when the content in the tab is ready.
bug 641396: tab activated by window activation doesn't emit "activate" event
A tab activated by window activation (i.e. the user switches from one window to another) doesn't emit the "activate" event.
bug 652548: panel text color doesn't contrast with background on Mac OS X
On Mac OS X, the default color of text in panels doesn't contrast sufficiently with the panel background, making text in panels difficult to read.
Outstanding Bugs
Also see the complete list of known issues and requests for enhancement.
Feedback and Bug Reports
We'd love to hear any feedback you have regarding this release! You can post it to the discussion group or report a bug.
