Updating extensions for Firefox 3

  • Revision slug: Updating_extensions_for_Firefox_3
  • Revision title: Updating extensions for Firefox 3
  • Revision id: 114686
  • Created:
  • Creator: MarkFinkle
  • Is current revision? No
  • Comment /* Removed interfaces */

Revision Content

{{template.Fx_minversion_header(3)}}{{template.Draft()}} 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! Simply use the Developer Control Panel at AMO to adjust the maxVersion. You can avoid having to have your extension re-reviewed this way.

Step 1: Update the install manifest

The first step -- and, for most extensions, the only one that will be needed -- is to update the install manifest file, <tt>install.rdf</tt>, to indicate compatibility with Firefox 3.

Simply find the line indicating the maximum compatible version of Firefox (which, for Firefox 2, might look like this):

 <em:maxVersion>2.0.0.*</em:maxVersion>

Change it to indicate compatibility with Firefox 3:

 <em:maxVersion>3.0.*</em:maxVersion>

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.*".

{{template.Note("Note that at this point more changes in Firefox 3 are expected. These changes may break some extensions, so you shouldn\'t release an extension with <code>3.0.*</code> <code>maxVersion</code> to the users until the Firefox 3 release candidate is out. During the Firefox 3 Beta period, you should use <code>3.0b3</code> as your <code>maxVersion</code>.")}}

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.

{{template.Note("If your extension still uses an <code><a href=\"en/Install.js\">Install.js</a></code> script instead of an <a href=\"en/Install_Manifests\">install manifest</a>, you need to make the transition to an install manifest now. Firefox 3 no longer supports <code>install.js</code> scripts in XPI files.")}}

Add localizations to the install manifest

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.

Step 2: Ensure you are providing secure updates

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.

Step 3: Deal with changed APIs

Several APIs have been changed in significant ways. The most significant of these, which will likely affect a large number of extensions, are:

DOM

{{wiki.template(':en/DOM/WRONG_DOCUMENT_ERR_note')}}

Bookmarks & History

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 Making the transition to Places for details on updating your existing extension to use the Places API.

Download Manager

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 {{template.Interface("nsIDownloadManager")}}, {{template.Interface("nsIDownloadProgressListener")}}, and Monitoring downloads for more information.

Password Manager

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.
  • nsILoginInfo
  • nsILoginManager

Popups (Menus, Context Menus, Tooltips and Panels)

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.{{template.XULMeth("showPopup")}} has been deprecated in favor of new popup.{{template.XULMeth("openPopup")}} and popup.{{template.XULMeth("openPopupAtScreen")}}.

Removed interfaces

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:

  • nsIDOMPaintListener
  • nsIDOMScrollListener
  • nsIDOMMutationListener
  • nsIDOMPageTransitionListener
  • nsICloseAllWindows (see {{template.Bug(386200)}})

Step 4: Check for relevant chrome changes

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>

{{template.Note("This change is effective for Firefox 3 beta 4 and the pre-beta 4 nightlies.")}}

Other changes

Add simple changes you had to make while updating your extension to work with Firefox 3 here.

{{ wiki.languages( { "fr": "fr/Mise_\u00e0_jour_des_extensions_pour_Firefox_3", "ja": "ja/Updating_extensions_for_Firefox_3", "pl": "pl/Aktualizacja_rozszerze\u0144_dla_Firefoksa_3" } ) }}

Revision Source

<p>{{template.Fx_minversion_header(3)}}{{template.Draft()}}
This article provides information that will be useful to developers that wish to update their extensions to work properly under Firefox 3.
</p><p>Before going further, there's one helpful hint we can offer: if the only change your extension requires is a bump to the <code>maxVersion</code> field in its install manifest, and you host your extension at <a class="external" href="https://addons.mozilla.org">addons.mozilla.org</a>, you don't actually need to upload a new version of your extension!  Simply use the Developer Control Panel at AMO to adjust the <code>maxVersion</code>.  You can avoid having to have your extension re-reviewed this way.
</p>
<h3 name="Step_1:_Update_the_install_manifest"> Step 1: Update the install manifest </h3>
<p>The first step -- and, for most extensions, the only one that will be needed -- is to update the <a href="en/Install_Manifests">install manifest</a> file, <tt>install.rdf</tt>, to indicate compatibility with Firefox 3.
</p><p>Simply find the line indicating the maximum compatible version of Firefox (which, for Firefox 2, might look like this):
</p>
<pre class="eval"> <span class="plain">&lt;em:maxVersion&gt;2.0.0.*&lt;/em:maxVersion&gt;</span>
</pre>
<p>Change it to indicate compatibility with Firefox 3:
</p>
<pre class="eval"> <span class="plain">&lt;em:maxVersion&gt;3.0.*&lt;/em:maxVersion&gt;</span>
</pre>
<p>Then reinstall your extension.
</p><p>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.*".
</p><p>{{template.Note("Note that at this point more changes in Firefox 3 are expected. These changes may break some extensions, so you shouldn\'t release an extension with &lt;code&gt;3.0.*&lt;/code&gt; &lt;code&gt;maxVersion&lt;/code&gt; to the users until the Firefox 3 release candidate is out. During the Firefox 3 Beta period, you should use &lt;code&gt;3.0b3&lt;/code&gt; as your &lt;code&gt;maxVersion&lt;/code&gt;.")}}
</p><p>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.
</p><p>{{template.Note("If your extension still uses an &lt;code&gt;&lt;a href=\"en/Install.js\"&gt;Install.js&lt;/a&gt;&lt;/code&gt; script instead of an &lt;a href=\"en/Install_Manifests\"&gt;install manifest&lt;/a&gt;, you need to make the transition to an install manifest now.  Firefox 3 no longer supports &lt;code&gt;install.js&lt;/code&gt; scripts in XPI files.")}}
</p>
<h4 name="Add_localizations_to_the_install_manifest"> Add localizations to the install manifest </h4>
<p>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 <a href="en/Localizing_extension_descriptions">Localizing extension descriptions</a> for more details.
</p>
<h3 name="Step_2:_Ensure_you_are_providing_secure_updates"> Step 2: Ensure you are providing secure updates </h3>
<p>If you are hosting addons yourself and not on a secure add-on hosting provider like <a class="external" href="https://addons.mozilla.org">addons.mozilla.org</a> 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 <a href="en/Extension_Versioning%2c_Update_and_Compatibility#Securing_Updates">Securing Updates</a> for more information.
</p>
<h3 name="Step_3:_Deal_with_changed_APIs"> Step 3: Deal with changed APIs </h3>
<p>Several APIs have been changed in significant ways.  The most significant of these, which will likely affect a large number of extensions, are:
</p>
<h4 name="DOM"> DOM </h4>
<p>{{wiki.template(':en/DOM/WRONG_DOCUMENT_ERR_note')}}
</p>
<h4 name="Bookmarks_&amp;_History"> Bookmarks &amp; History </h4>
<p>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 <a href="en/Places">Places</a> architecture.  See <a href="en/Making_the_transition_to_Places">Making the transition to Places</a> for details on updating your existing extension to use the Places API.
</p>
<h4 name="Download_Manager"> Download Manager </h4>
<p>The Download Manager API has changed slightly due to the transition from an RDF data store to using the <a href="en/Storage">Storage</a> 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 {{template.Interface("nsIDownloadManager")}}, {{template.Interface("nsIDownloadProgressListener")}}, and <a href="en/Monitoring_downloads">Monitoring downloads</a> for more information.
</p>
<h4 name="Password_Manager"> Password Manager </h4>
<p>If your extension accesses user login information using the Password Manager, it will need to be updated to use the new Login Manager API.
</p>
<ul><li> The article <a href="en/Using_nsILoginManager">Using nsILoginManager</a> 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.
</li><li> <code><a href="en/NsILoginInfo">nsILoginInfo</a></code>
</li><li> <code><a href="en/NsILoginManager">nsILoginManager</a></code>
</li></ul>
<h4 name="Popups_.28Menus.2C_Context_Menus.2C_Tooltips_and_Panels.29"> Popups (Menus, Context Menus, Tooltips and Panels) </h4>
<p>The XUL Popup system was heavily modified in Firefox 3. The Popup system includes main menus, context menus and popup panels. A guide to <a href="en/XUL/PopupGuide">using Popups</a> has been created, detailing how the system works. One thing to note is that <code>popup.{{template.XULMeth("showPopup")}}</code> has been deprecated in favor of new <code>popup.{{template.XULMeth("openPopup")}}</code> and <code>popup.{{template.XULMeth("openPopupAtScreen")}}</code>.
</p>
<h4 name="Removed_interfaces"> Removed interfaces </h4>
<p>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:
</p>
<ul><li> <code>nsIDOMPaintListener</code>
</li><li> <code>nsIDOMScrollListener</code>
</li><li> <code>nsIDOMMutationListener</code>
</li><li> <code>nsIDOMPageTransitionListener</code>
</li><li> <code>nsICloseAllWindows</code> (see {{template.Bug(386200)}})
</li></ul>
<h3 name="Step_4:_Check_for_relevant_chrome_changes">Step 4: Check for relevant chrome changes</h3>
<p>There has been a minor change to the chrome that may require changes in your code.  A new <code>vbox</code> 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.
</p><p>For example, if you previously overlaid some chrome before the status bar, like this:
</p>
<pre>&lt;window id="main-window"&gt;
  &lt;something insertbefore="status-bar" /&gt;
&lt;/window&gt;
</pre>
<p>You should now overlay it like this:
</p>
<pre>&lt;vbox id="browser-bottombox"&gt;
  &lt;something insertbefore="status-bar" /&gt;
&lt;/vbox&gt;
</pre>
<p>{{template.Note("This change is effective for Firefox 3 beta 4 and the pre-beta 4 nightlies.")}}
</p>
<h3 name="Other_changes"> Other changes </h3>
<p><i>Add simple changes you had to make while updating your extension to work with Firefox 3 here.</i>
</p>
<ul><li> {{template.Interface("nsIAboutModule")}} implementations are now required to support the <code>getURIFlags</code> method. See {{template.Source("netwerk/protocol/about/public/nsIAboutModule.idl", "nsIAboutModule.idl")}} for documentation. This affects extensions that provide new <tt>about:</tt> URIs. ({{template.Bug(337746)}})
</li><li> The {{template.XULElem("tabbrowser")}} element is no longer part of "toolkit" ({{template.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).
</li><li> Changes to <a href="en/NsISupports_proxies">nsISupports proxies</a> <a class="external" href="http://groups.google.com/group/mozilla.dev.platform/browse_thread/thread/78236a4b312a2de4/939240fc3f5123a8?lnk=st&amp;rnum=1#939240fc3f5123a8"> and possibly to threading-related interfaces need to be documented.
</a></li><li><a class="external" href="http://groups.google.com/group/mozilla.dev.platform/browse_thread/thread/78236a4b312a2de4/939240fc3f5123a8?lnk=st&amp;rnum=1#939240fc3f5123a8"> If you use XML processing instructions, such as <code>&lt;?xml-stylesheet ?&gt;</code> in your XUL files, be aware of the changes made in {{template.Bug(319654)}}:
<ol><li> XML PIs are now added to a XUL document's DOM. This means {{template.Domxref("document.firstChild")}} is no longer guaranteed to be the root element. If you need to get the root document in your script, use {{template.Domxref("document.documentElement")}} instead.
</li><li> <code>&lt;?xml-stylesheet ?&gt;</code> and <code>&lt;?xul-overlay ?&gt;</code> processing instructions now have no effect outside the document prolog.
</li></ol>
</a></li><li><a class="external" href="http://groups.google.com/group/mozilla.dev.platform/browse_thread/thread/78236a4b312a2de4/939240fc3f5123a8?lnk=st&amp;rnum=1#939240fc3f5123a8"> <code>window.addEventListener("load", myFunc, true)</code> is not fired when loading web content (browser page loads). This is due to {{template.Bug(296639)}} which changes the way inner and outer windows communicate. The simple fix here is to use <code>gBrowser.addEventListener("load", myFunc, true)</code> as described </a><a href="en/Code_snippets/Tabbed_browser#Detecting_page_load">here</a> and works in Firefox 2 as well.
</li><li> <code>content.window.getSelection()</code> gives an object (which can be converted to a string by <code>toString()</code>), unlike the now deprecated <code>content.document.getSelection()</code> which returns a string
</li><li> <code>event.preventBubble()</code> was deprecated in Firefox 2 and has been removed in Firefox 3. Use <a href="en/DOM/event.stopPropagation"><code>event.stopPropagation()</code></a>, which also works in Firefox 2 as well.
</li></ul>
<div class="noinclude">
</div>
{{ wiki.languages( { "fr": "fr/Mise_\u00e0_jour_des_extensions_pour_Firefox_3", "ja": "ja/Updating_extensions_for_Firefox_3", "pl": "pl/Aktualizacja_rozszerze\u0144_dla_Firefoksa_3" } ) }}
Revert to this revision