Updating extensions for Firefox 3
This article provides information that will be useful to developers that wish to update their extensions to work properly under Firefox 3.
Before going further, there's one helpful hint we can offer: if the only change your extension requires is a bump to the
maxVersion field in its install manifest, and you host your extension at addons.mozilla.org, you don't actually need to upload a new version of your extension! Use the Developer Control Panel at AMO to adjust the
maxVersion. You can avoid having to have your extension re-reviewed this way.
Find the line indicating the maximum compatible version of Firefox (which, for Firefox 2, might look like this):
Change it to indicate compatibility with Firefox 3:
Then reinstall your extension.
Note that Firefox 3 does away with the extra ".0" in the version number, so instead of using "3.0.0.*, you only need to use "3.0.*".
There have been (and will continue to be) a number of API changes that will likely break some extensions. We're still working on compiling a complete list of these changes.
Firefox 3 supports new properties in the install manifest to specify localized descriptions. The old methods still work however the new allow Firefox to pick up the localizations even when the add-on is disabled and pending install. See Localizing extension descriptions for more details.
If you are hosting addons yourself and not on a secure add-on hosting provider like addons.mozilla.org then you must provide a secure method of updating your add-on. This will either involve hosting your updates on an SSL website, or using cryptographic keys to sign the update information. Read Securing Updates for more information.
Several APIs have been changed in significant ways. The most significant of these, which will likely affect a large number of extensions, are:
Nodes from external documents should be cloned using
document.importNode() (or adopted using
document.adoptNode()) before they can be inserted into the current document. For more on the
Node.ownerDocument issues, see the W3C DOM FAQ.
Firefox doesn't currently enforce this rule (it did for a while during the development of Firefox 3, but too many sites break when this rule is enforced). We encourage Web developers to fix their code to follow this rule for improved future compatibility.
If your extension accesses bookmark or history data in any way, it will need substantial work to be compatible with Firefox 3. The old APIs for accessing this information have been replaced by the new Places architecture. See the Places migration guide for details on updating your existing extension to use the Places API.
The Download Manager API has changed slightly due to the transition from an RDF data store to using the Storage API. This should be a pretty easy transition to make. In addition, the API for monitoring download progress has changed to support multiple download manager listeners. See
nsIDownloadProgressListener, and Monitoring downloads for more information.
If your extension accesses user login information using the Password Manager, it will need to be updated to use the new Login Manager API.
- The article Using nsILoginManager includes examples, including a demonstration of how to write your extension to work with both the Password Manager and the Login Manager, so it will work with both Firefox 3 and earlier versions.
You can also override the built-in password manager storage if you want to provide your own password storage implementation in your extensions. See Creating a Login Manager storage module for details.
The XUL Popup system was heavily modified in Firefox 3. The Popup system includes main menus, context menus and popup panels. A guide to using Popups has been created, detailing how the system works. One thing to note is that
popup.showPopup has been deprecated in favor of new
handleEnter() method has been changed to accept an argument that indicates whether the text was selected from the autocomplete popup or by the user pressing enter after typing text.
- When a
DOMParseris instantiated, it inherits the calling code's principal and the
baseURIof the window the constructor came from.
- If the caller has UniversalXPConnect privileges, it can pass parameters to
new DOMParser(). If fewer than three parameters are passed, the remaining parameters will default to
- The first parameter is the principal to use; this overrides the default principal normally inherited.
- The second parameter is the
- The third parameter is the
- If you initialize a
DOMParserusing a contract, such as by calling
createInstance(), and you don't call the
init()method, attempting to initiate a parsing operation will automatically create and initialize the
DOMParserwith a null principal and
The internal string API is no longer exported; you must migrate to the external string API. See these articles for helpful information:
The following interfaces were removed from Gecko 1.9, which drives Firefox 3. If your extension makes use of any of these, you'll need to update your code:
nsICloseAllWindows(see bug 386200)
There have been a few changes to chrome layout that may affect some extensions.
There has been a minor change to the chrome that may require changes in your code. A new
vbox has been added, called "browser-bottombox", which encloses the find bar and status bar at the bottom of the browser window. Although this doesn't affect the appearance of the display, it may affect your extension if it overlays chrome relative to these elements.
For example, if you previously overlaid some chrome before the status bar, like this:
<window id="main-window"> <something insertbefore="status-bar" /> </window>
You should now overlay it like this:
<vbox id="browser-bottombox"> <something insertbefore="status-bar" /> </vbox>
Or use the following technique to make your overlay work on both Firefox 2 and Firefox 3:
<window id="main-window"> <vbox id="browser-bottombox" insertbefore="status-bar"> <something insertbefore="status-bar" /> </vbox> </window>
Extensions that attempt to overlay onto the "appcontent" box try to float chrome over document content will no longer display that material. You should update your extension to use the new
<xul:panel> XUL element. If you wish to keep the panel from automatically disappearing after a delay, you can set the
noautohide attribute to
Add simple changes you had to make while updating your extension to work with Firefox 3 here.
chrome://browser/base/utilityOverlay.jsis no longer supported for security reasons. If you were previously using this, you should switch to
nsIAboutModuleimplementations are now required to support the
getURIFlagsmethod. See nsIAboutModule.idl for documentation. This affects extensions that provide new
about:URIs. (bug 337746)
<xul:tabbrowser>element is no longer part of "toolkit" (bug 339964). This means this element is no longer available to XUL applications and extensions. It continues to be used in the main Firefox window (browser.xul).
- Changes to nsISupports proxies and possibly to threading-related interfaces need to be documented.
- If you use XML processing instructions, such as
<?xml-stylesheet ?>in your XUL files, be aware of the changes made in bug 319654:
- XML PIs are now added to a XUL document's DOM. This means
document.firstChildis no longer guaranteed to be the root element. If you need to get the root document in your script, use
<?xul-overlay ?>processing instructions now have no effect outside the document prolog.
- XML PIs are now added to a XUL document's DOM. This means
window.addEventListener("load", myFunc, true)is not fired when loading web content (browser page loads). This is due to bug 296639 which changes the way inner and outer windows communicate. The simple fix here is to use
gBrowser.addEventListener("load", myFunc, true)as described here and works in Firefox 2 as well.
content.window.getSelection()gives an object (which can be converted to a string by
toString()), unlike the now deprecated
content.document.getSelection()which returns a string
event.preventBubble()was deprecated in Firefox 2 and has been removed in Firefox 3. Use
event.stopPropagation(), which works in Firefox 2 as well.
- Timers that are initiated using
setTimeout()are now blocked by modal windows due to the fix made for bug 52209. You may use
- If your extension needs to allow an untrusted source (e.g., a web site) to access the extension's chrome, then you must use the new