Table of contents
- 1. The startup and shutdown process
- 2. Notes on modifying the application user interface
- 3. Creating a boostrapped extension
- 4. Bootstrap entry points
Traditional extensions include overlays, wherein the application can load up XUL from the extension's package and automatically apply it atop its own UI. While this makes creating extensions that add to the application's user interface relatively easy, it means that updating, installing, or disabling an extension requires an application restart.
Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1) introduces bootstrapped extensions. These are special extensions that, instead of using overlays to apply their user interface to the application, programmatically insert themselves into the application. This is done using a special script file that's included in the extension that contains functions the browser calls to command the extension to install, uninstall, start up, and shut down.
All the application does is call into this script file; the extension is responsible for adding and removing its user interface and handling any other setup and shutdown tasks it requires.
This article discusses how bootstrapped extensions work.
As an aside, extensions created using the Mozilla Labs Add-on Builder web site are bootstrapped; however, because all the bootstrapping code is generated for you, you don't really need to think about it.
The startup and shutdown process
A key feature of bootstrapped extensions is that they must be able to be started up and shut down on demand by the application. When the extension's
startup() function is called, it must manually inject its user interface and other behavior into the application. Similarly, when its
shutdown() function is called, it must remove anything it's added to the application, as well as all references to any of its objects.
There are several scenarios in which the
startup() function may be called; for example:
- When the extension is first installed, assuming that it's both compatible with the application and is enabled.
- When the extension becomes enabled using the add-ons manager window.
- When the application is started up, if the extension is enabled and compatible with the application.
Some examples of when the
shutdown() function may be called:
- When the extension is uninstalled, if it's currently enabled.
- When the extension becomes disabled.
- When the user quits the application, if the extension is enabled.
Notes on modifying the application user interface
chrome.manifest in bootstrapped add-ons
You can use a
chrome.manifest file in bootstrapped add-ons to:
- make your add-on's content available via a
chrome://URL (using the
skininstructions in the manifest);
- replace existing
chrome://URIs with your content (using the
chrome.manifest instructions are supported in bootstrapped add-ons, for example you still cannot register XUL Overlays from a bootstrapped add-on. See the
chrome.manifest documentation for details.
In Firefox 10 and later the
chrome.manifest file located in the root of the add-on's XPI (i.e. a sibling of the
install.rdf) is loaded automatically. In Firefox 8 and 9 you had to load/unload the manifest manually using
. This feature was unavailable in Firefox versions before 8.
Adding user interface manually
If you decide to go ahead and try to develop a bootstrapped extension that modifies the application's user interface, here are a few suggestions to get you started.
You need to look up the relevant application UI elements by their ID by calling
, then manipulate them to inject your UI. For example, you can get access to the menu bar in Firefox with
Be sure that at shutdown time, you remove any user interface you've added.
Creating a boostrapped extension
To mark an extension as bootstrappable, you need to add the following element to its install manifest:
Because older versions of Firefox don't know about the
bootstrap property or
bootstrap.js file, it's not overly difficult to create an XPI that will work on both as a boostrappable extension and as a traditional extension. Create your extension as a bootstrappable extension, then add the traditional overlays as well. Newer versions of Firefox will use the
bootstrap.js script, ignoring the components and overlays, while older versions will use the overlays.
Bootstrap entry points
bootstrap.js script should contain several specific functions, which are called by the browser to manage the extension. The script gets executed in a privileged sandbox, which is cached until the extension is shut down.
Called when the extension needs to start itself up. This happens at application launch time or when the extension is enabled after being disabled (or after it has been shut down in order to install an update. As such, this can be called many times during the lifetime of the application.
This is when your add-on should inject its UI, start up any tasks it may need running, and so forth.
void startup( data, reason );
Called when the extension needs to shut itself down, such as when the application is quitting or when the extension is about to be upgraded or disabled. Any user interface that has been injected must be removed, tasks shut down, and objects disposed of.
void shutdown( data, reason );
- A bootstrap data structure.
- One of the reason constants, indicating why the extension is being shut down. This will be one of
Your bootstrap script may optionally include an
install() function, which the application calls before the first call to
startup() after the extension is installed, upgraded, or downgraded.
install()never gets called if it is uninstalled before becoming compatible. However, if the extension gets upgraded to a version that's compatible with the application, its
install()function will be called at that time, before the first
void install( data, reason );
- A bootstrap data structure.
- One of the reason constants, indicating why the extension is being installed. This will be one of
This optional function is called after the last call to
shutdown() before a particular version of an extension is uninstalled. This will not be called if
install() was never called.
uninstall()can be called even on extensions that are currently disabled, or are not compatible with the current application. Because of this, it's crucial that the function be implemented to gracefully handle APIs that may not be present in the application. This function will also not be called if a third-party application removes the extension while Firefox isn't running.
void uninstall( data, reason );
The bootstrap functions accept a
reason parameter, which explains to the extension why it's being called. The reason constants are:
| ||1||The application is starting up.|
| ||2||The application is shutting down.|
| ||3||The add-on is being enabled.|
| ||4||The add-on is being disabled. (Also sent during uninstallation)|
| ||5||The add-on is being installed.|
| ||6||The add-on is being uninstalled.|
| ||7||The add-on is being upgraded.|
| ||8||The add-on is being downgraded.|
Each of the entry points is passed a simple data structure containing some useful information about the add-on being bootstrapped. More information about the add-on can be obtained by calling
| || ||The ID of the add-on being bootstrapped.|
| || ||The version of the add-on being bootstrapped.|
| || ||The installation location of the add-on being bootstrapped. This may be a directory or an XPI file depending on whether the add-on is installed unpacked or not.|
| || ||A URI pointing at the root of the add-ons files, this may be a jar: or file: URI depending on whether the add-on is installed unpacked or not.|
- Wladimir Palant explains problems and bugs found when converting an existing extension, including some solutions and workarounds.
- Mark Finkle provides some simple example code for restartless add-ons in mobile Firefox, adding resources (like the options window) to bootstrapped extensions and using default preferences without a default/preferences/prefs.js file.
- Kris Maglione writes about the requirements for the cleanup procedures in bootstrapped extensions.
- Edward Lee shows off some helpful coding patterns and examples you can use in your bootstrapped add-on.
- Erik Vold's quick tutorial on restartless addons:Part 1, Part 2, Part 3, Part 4. Part 5, Part 6, Part 7 and Part 8.
- Documentation for Inline Options in Firefox 7 and later.