Jetpack/Release Notes/1.0
Contents
- 1 About
- 2 Major Features
- 3 Installation
- 4 Getting Help
- 5 Known Issues
- 6 Notable Changes Since 1.0b5
- 6.1 Bug 601295: Content script access to the DOM is now proxied
- 6.2 Cross-site XmlHttpRequests are no longer permitted in content scripts in Firefox 5
- 6.3 Changes to linker search behavior
- 6.4 Bug 653256: Make smaller XPIs by only including modules that are actually used
- 6.5 timers and self modules are moved from api-utils to addon-kit
- 7 Feedback and Bug Reports
About
This is the first stable release of the Add-on SDK.
The Add-on SDK makes it easy to develop Firefox add-ons using JavaScript, HTML, and CSS. This means you no longer need to understand how to work with the XUL or XPCOM to write add-ons.
Add-ons developed with the SDK are:
- restartless: so users can try them out without interrupting their browsing
- forward-compatible: will continue to work as new versions of Firefox are released. In particular they are already structured to work with Electrolysis, the forthcoming architecture in which Firefox uses separate processes to display the browser UI, handle web content and execute add-ons.
To learn more about the SDK, you can browse the documentation.
Major Features
The SDK provides two things:
- a set of JavaScript APIs which you can use to create your user interface, and to interact with web content and the browser
- a command-line tool called
cfxwhich takes care of packaging your code into an add-on, leaving you free to concentrate on the code itself
JavaScript APIs
For an overview of the APIs check out the API introduction in the online documentation.
In 1.0 we've defined a limited set of supported APIs which cover the following categories:
- building a UI: defining dialogs, widgets, context menu items, and notification alerts
- interacting with the web: fetching, examining, and modifying web pages
- interacting with the browser: accessing the clipboard, getting information about the set of open windows and tabs, and handling private browsing
- some basic utility functions like persistent storage
There are additional APIs which you can use, but we don't yet consider them stable, so we might change them in incompatible ways in future releases.
The SDK is extensible by design: so it's possible for you to create your own APIs that expose additional functionality, and make them available to other developers. Here's a list of some of these third party modules.
cfx
cfx is the command-line tool the SDK supplies for:
- initializing your add-on: creating its skeleton structure
- running your add-on to smoke test it without needing to going through the packaging/installation cycle
- unit testing
- packaging your add-on as an installable XPI file
Installation
To use the SDK you download and install it locally. You'll need Python version 2.5 or 2.6, and Firefox version 4 or higher.
Obtain the SDK in your favorite compression format:
Then unpack the archive, open the addon-sdk-1.0/README.txt file, and follow its instructions.
Getting Help
If you can't find the answer to your question in the documentation:
- see if your question is answered in the FAQ
- SDK users and project team members discuss problems and proposals on the project mailing list. Someone else may have had the same problem you do, so try searching the list. You're welcome to post a question, too.
- ask other SDK users and developers in #jetpack on Mozilla's IRC network
Known Issues
See the complete list of known issues and requests for enhancement. We've listed some of the more important issues separately below.
If your add-on has a long name, and the path to your Firefox profile is long enough, then the XPI installation process will try to create an intermediate file with a name longer than the maximum supported length on some Windows systems. If that happens you may get an error like:
"<your add-on> could not be installed because Firefox cannot modify the needed file"
The main fix for this will be bug 638742, which is to stop unpacking the XPI completely. When that is done, none of the pathnames will matter: they'll all stay safely trapped inside the zipfile. At that point, the name of the XPI file and the length of the profile directory will be the only issues.
Until then, the best advice is to use shorter package names or install Firefox higher up the directory tree so the profile directory's absolute path is shorter.
The SDK automatically includes a dependency on the packages supplied with the SDK such as addon-kit and api-utils. This means that you can require() modules in the SDK such as widget without having to specify addon-kit as a dependency.
You can also use modules from other packages, such as the packages listed here, by including a reference to the package in your package.json file.
However, if you do add any dependencies to package.json, then the SDK will no longer add addon-kit or api-utils automatically, and you must add them manually if you want to include their modules.
The SDK will give an error if your package name contains spaces or Unicode characters.
If your add-on stores data using the simple-storage API, the data is not cleaned up when your add-on is uninstalled.
Some core JavaScript functions, such as btoa(), are not available to add-on code.
selection.text returns null instead of the selected text when the selection is in a text box or text area.
If an add-on is uninstalled while it's disabled, it's not notified of uninstall. If the add-on needs to do some special cleanup on uninstall, like removing persistent storage such as a file, this won't be possible if it has been disabled.
bin\activate fails to find 64-bit Python on 64-bit Windows environments, as it assumes Python is 32-bit.
On Windows, bin\activate sometimes gives the following error:
"Error: The system was unable to find the specified registry key or value"
This does not seem to affect the functioning of the SDK.
By default, widgets are placed on the add-on bar, and given a height to match the height of that bar. If the user moves the widget to a different toolbar, and that toolbar has a different height, the widget's height is not updated accordingly.
A widget containing HTML content gets no icon in the Customize Toolbar Window.
When a user removes a widget from the toolbar its detach event does not get sent.
Selection events for a page are not sent if the page did not fully load (for example, because the user stopped the page loading).
Notable Changes Since 1.0b5
Bug 601295: Content script access to the DOM is now proxied
We've changed the way content scripts interact with web pages, in order to improve security.
Previously, content scripts that accessed DOM objects in the page would frequently access the same objects as those being accessed by the page. This gives rise to two problems:
- many changes to the page would be visible to the page, making it obvious to the page that an add-on was modifying it.
- a malicious page might redefine functions and properties of them so they don't do what the add-on expects. For example, if a content script calls
document.getElementById()to retrieve a DOM element, then a malicious page could redefine its behavior to return something unexpected.
To deal with these problems, DOM objects like the global window object are now implemented in a way that ensures that content scripts that access those objects will get the native implementations of their properties and methods.
Content scripts that modify those DOM objects will modify a proxy object instead of the real object.
Finally: sometimes add-ons need access to custom, document-defined JavaScript objects. For example, GMail provides a custom JavaScript API which would not be accessible using the proxy. To meet use cases like this, in bug 660780 we've provided access to the unwrapped window via a global unsafeWindow object in content scripts. But note that this is experimental and may change or be removed completely in future releases.
Cross-site XmlHttpRequests are no longer permitted in content scripts in Firefox 5
Firefox 4 allowed content scripts to make cross-site requests using XmlHttpRequest. So, for example, if you injected a content script into http://www.mozilla.org/, the content script would be allowed to send a request to http://www.google.com/ using XmlHttpRequest.
It was always the intention that cross-site requests should not be possible in a content script, and in Firefox 5 this is no longer possible.
Changes to linker search behavior
This changes the way the SDK's linker resolves require() statements, making it more compatible with CommonJS and NPM.
It's documented in the GitHub commit and in the Module Search guide in the SDK.
Bug 653256: Make smaller XPIs by only including modules that are actually used
Previously, if you used any modules in a package, then your XPI would include all modules in the package. With this change only modules you actually use get included.
Note that this is behavior is not currently the default: to enable it you need to pass the experimental --strip-xpi option to cfx.
timers and self modules are moved from api-utils to addon-kit
This should not affect anyone currently using either module, but reflects the fact that both of these modules are heavily used by people writing add-ons.
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.
