Labs/Jetpack/Release Notes/1.0b5

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

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 messaging style, but 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 create a WidgetView from an instance of a Widget that's attached to a specific window, and any changes you make to that WidgetView only apply to that instance.

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 and will eventually enable add-ons to load other commonJS modules.

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

Known Issues

Firefox 4.0 bug may affect Page-Mods

Page-mod may be matched multiple times if contentScriptWhen is set to 'start': see bug 641457. This is caused by platform bug 642145, which is fixed in Firefox 4.0.1.

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.