Thunderbird/Add-ons Guide 63

Add-ons Guide for Thunderbird 63 and beyond

Note: The documentation at https://thunderbird-webextensions.readthedocs.io/en/latest/how-to/extensions68.html is a better place to start learning about converting add-ons to run on recent Thunderbird builds. However, this page contains details about specific issues you may encounter that aren't all documented there, so this may be a useful reference as well.

If you have programming questions or wish to discuss the future can be posted in the mozilla.dev.apps.thunderbird newsgroup, see Communication Channels.

Supported extension types

The following extension types are supported in from Thunderbird 63 and beyond:

WebExtensions

This is the same type of addon that Firefox currently uses. For a general introduction, see WebExtensions and What are WebExtensions.

However, the APIs are necessarily different between Thunderbird and Firefox. Some applicable Firefox APIs work in Thunderbird (just try it), other Firefox APIs do not work, and Thunderbird has a few Thunderbird-specific APIs added. There is some documentation for the Thunderbird WebExtension APIs. For any API that is not yet provided, WebExtension Experiments can be used.

There are not many WebExtensions for Thunderbird yet, so you're in new territory. Don't expect a smooth ride. But being a pioneer can be exciting, too. Help wanted!

Details: WebExtensions have a manifest.json. As documented on Thunderbird WebExtension APIs, the following WebExtension APIs are available in Thunderbird:

• Tabs and Windows API, bug 1455471, TB 60 and TB 63+
• Address Book API, bug 1469238, TB 64+
• FileLink API, bug 1481052, TB 64+, will be in TB 60.4
• Toolbar buttons WebExtensions API, bug 1487008, TB 64+
• Folder tab (3-pane) API, bug 1499617, in preparation
• Composition API, bug 1503423, in preparation
• And more, check meta-bug 1396172

Bootstrapped extensions

Bootstrapped/restartless extensions with an install.rdf manifest. The code to handle bootstrapped extension and install.rdf has been moved to comm-central in bug 1510097 and should be stable now. Important: Bootstrapped legacy extensions continue to work without a manifest.json file and will in fact break if you add that file.

"Legacy" XUL extensions with overlays

"Legacy" XUL extensions with overlays are still "somewhat" supported in Thunderbird 63 and beyond. An inbuilt overlay loader will load XUL overlays for extensions but may cause graphical glitches or malfunctions. We're tracking this in bug 1476259.

Warning: Scripts in overlays are now run after all elements have been inserted into the document. This may cause unexpected behavior if your script previously ran before elements were inserted. For elements with event handlers these event handlers may run when the element is added, and they may fail if they rely on content being set up by a script which now runs after the creation of the element.

To use this overlay loader, XUL overlay legacy extensions must replace install.rdf file with a WebExtensions style manifest.json file, which includes the key "legacy" set to true. See Lightning as an example:
https://hg.mozilla.org/comm-central/rev/e81f4b59a00a7d3e18d50fd3851ecbd47762a186#l2.5 (Note: In this changeset the @variables@ are build variables, add-ons need to use fixed strings).
If your add-on has options specified in install.rdf, you need to put this in the manifest.json also. To do this, add the file to the key "legacy" instead of the value true in the following way:

{
  …
  "legacy" : {
    "options" : {
      "page" : "chrome://[path to your options.xul]",
      "open_in_tab" : true/false
    }
  }
}

The key open_in_tab is optional and defaults to value false. Value true corresponds to optionsType 3 in install.rdf.

Examples of extensions converted to this type (as of 3rd December 2018):

• Mail Redirect (version on ATN includes a good example of a working manifest.json)
• "Lightning"
• "Compact Header"
• "Signature Switch"
• "ThunderHTMLedit"

Removed in Thunderbird 60

Overlays have been progressively removed starting from this version. By version 63, there are no overlays left in Thunderbird. Due to Thunderbird's own overlay loader, XUL add-ons can still use overlays, but they can of course not overlay the removed Thunderbird overlays any more. For example, if your add-on overlaid mailWindowOverlay.xul, that needs to be changed; in this example you most likely need to overlay messenger.xul now.

Removed in Thunderbird 61

• XUL element method .insertItemAt(), replacement: .insertBefore()
• XUL element method .removeItemAt(), replacement: .remove(), example: listElement.removeItemAt(i) -> listElement.getItemAtIndex(i).remove()
• You can also use .setUnsafeInnerHTML() or document.allowUnsafeHTML = true, as a workaround to the above, see here.
• The interface of AddonManager.getAddonByID has changed. It now returns a promise, so instead of calling it as AddonManager.getAddonByID(addon_id, callback_function), you need to call it as AddonManager.getAddonByID(addon_id).then(callback_function').

Removed in Thunderbird 63

• XUL elements listbox, listboxitem and listcell.
  Replacement: richlistbox (example migration)
• XUL stringbundleset / stringbundle. You will also be unable to use the `nsIStringBundleService` interface.
  Replacement: Use Services.strings.createBundle(...).
  In order to use stringbundles, you need to load stringbundle.js in your XUL: <script type="application/x-javascript" src="chrome://global/content/elements/stringbundle.js"/>, but the XUL Overlay loader takes care of this. See also bug 1459743.

Note: I am not sure the above information is correct with current Thunderbird trunk builds as of March 30, 2019. I got errors when attempting to embed stringbundle elements in XUL overlays. Jikamens (talk) 00:34, 31 March 2019 (UTC)

• mailServices.js has been renamed to MailServices.jsm. The old name keeps working for now, but you get a deprecation warning in the error console if you use the old name.
• Starting in Thunderbird 63, all XBL-bindings will be removed from Thunderbird. That means, that if you have a XBL=binding in your add-on that extends a binding that is removed, your binding will fail. With this query, you can see all the bugs related to de-xbl-ing Thunderbird, and see how the removal of each binding is handled.
• A bunch of globals in the message composition window were removed: nsIMsgCompDeliverMode, nsIMsgCompSendFormat, nsIMsgCompConvertible, nsIMsgCompType, nsIMsgCompFormat, nsIAbPreferMailFormat, nsIPlaintextEditorMail, nsISupportsString, and mozISpellCheckingEngine. If you use any of these, there are available as the same names underneath Ci. (a.k.a. Components.interfaces.).

Removed in Thunderbird 64

• XUL element colorpicker.
  Replacement: HTML input type=color

Removed in Thunderbird 65

• XUL element progressmeter.
  Replacement: HTML progress (example migration)

• There is no longer a statusbar element. Instead of putting statusbar elements inside a statusbarpanel in your XUL, they need to go inside an hbox. The hbox contains have the same names as the old statsusbar containers, so you just need to change the element type. Also, if your status bar items had popup menus attached to them, you will need to do that differently now as well. See this example.

Changes in Thunderbird 67

• Thunderbird no longer passes in the aContext argument to the onDataAvailable methods of stream listeners, so stream listeners need to be updated so that they no longer expect this argument.

• MailUtils.getFolderForUri was renamed to MailUtils.getExistingFolder.

Importing javascript modules

A major backwards-incompatible change was made to importing javascript modules. Where once you used any of these:

Components.utils.import("resource://foo/modules/Foo.jsm");
// or…
Cu.import("resource://foo/modules/Foo.jsm");
// or…
ChromeUtils.defineModuleGetter(this, "Foo", "resource://foo/modules/Foo.jsm");

// or the two-argument variation:
var { Foo } = Cu.import("resource://foo/modules/Foo.jsm", null);
// or…
var scope = {}; Cu.import("resource://foo/modules/Foo.jsm", scope); // scope.Foo…

You should now do this:

var { Foo } = ChromeUtils.import("resource://foo/modules/Foo.jsm");
// or…
var scope = ChromeUtils.import("resource://foo/modules/Foo.jsm"); // scope.Foo…

ChromeUtils.import is a replacement for Components.utils.import (which was also changed) in this way. Note that no second argument is supplied. The returned object is a dictionary of only the objects listed in EXPORTED_SYMBOLS.

Editable menulists

The standard XUL element menulist no longer supports the editable attribute. However, editable menulists have been re-implemented using a custom element. To be able to use it, one has to include menulist.css and customElements.js:

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://messenger/content/menulist.css" type="text/css"?>

...

<script type="application/javascript" src="chrome://messenger/content/customElements.js"/>

...

<menulist is="menulist-editable" editable="true">
  <menupopup>
    <menuitem label="Label1" />
  </menupopup>
</menulist>

...

To be able to use this custom element from JS, the following is needed (in addition to the includes mentioned above):

let menulist = document.createElement("menulist", { is : "menulist-editable"});
menulist.setAttribute("is", "menulist-editable");
menulist.setAttribute("editable", "true");

See also

More information about updating extensions for Thunderbird 68 can be found here.