Thunderbird/Add-ons Guide 57

Add-ons Guide for Thunderbird 57 to Thunderbird 60 ESR

(For developer information about Thunderbird 61 and beyond visit the Add-ons Guide 63. Note: Thunderbird 61 and 62 betas were skipped. The next beta after 60 is 63.)

Ask Questions, Get Help: Developers are encouraged to ask for help and advice in the mozilla.dev.apps.thunderbird newsgroup, see Communication Channels. Please check this document and ask questions in a forum before filing a bug report. Also, if you target version is 60, test and fix your add-on using version 60 release, not nightly builds or beta.

Legacy, pre-version 57 add-ons - Thunderbird 57-60 (and Seamonkey) still support legacy add-ons (except binary add-ons, see below), but all add-on authors must check to see whether code changes are needed. The complexity of the add-on determines how it is affected - many add-ons are not heavily affected, some not affected at all. Some add-ons do not need any code changes, and some only trivial or minor refactoring or name changes. Some need to adapt to changed interfaces. Some only need changes to startup and intialization, others may need more extensive changes. A non-exhaustive list of of things to be modified is below. Every beta from 57 to 60 delivered changes. So for example if your add-on is compatible with beta 58 you may still need to make further changes. Example changes to version 59 involve bug 1414398 default preferences, and bug 1419145 menu to access add-on options and tab options.

Why: Firefox platform have disabled "legacy" add-ons in Firefox 57 (that is, all add-ons not based purely on WebExtensions), so Mozilla removed some core interfaces which are also used by Thunderbird. However, unlike Firefox, Thunderbird has not killed legacy add-ons, because the Thunderbird team lessened the impact of those changes on Thunderbird add-on developers, where possible.

WebExtension aka futures: Thunderbird 60 does not have WebExtensions support. Going forwards, bug 1396172 will add WebExtension support in Thunderbird beta 63, while maintaining "legacy" add-ons and hybrid add-ons.

Removed in mozilla53

Binary add-ons are no longer supported by the Mozilla platfrom since Thunderbird 53. (Binary add-ons were already discontinued in Firefox 41, see here.) Further reading: tb-planning post of November 2016, bug 1314955 which removed the feature from the Mozilla platform. It is however still possible to install the "binary component" separately. As an example, check how Enigmail installs and communicates with both GPG and the pEp engine.

Removed interfaces in mozilla57

• nsILocalFile -- replacement: nsIFile
• extIApplication, nsIEntityConverter
• nsIProgrammingLanguage
• nsILocaleService and friends
• nsIScriptableDateFormat -- replacement: Intl.DateTimeFormat and mozIntl.DateTimeFormat (use: |Services.intl.createDateTimeFormat(...)| in Thunderbird 57 and 58, changed to |new Services.intl.DateTimeFormat(...)| from Thunderbird 59).
• nsIScriptableUnicodeConverter -- replacement: TextDecoder and TextEncoder; their web pages claim they only accept "utf-8" as the charset encoding, but that's not true, at least not in Thunderbird.
• nsIFilePicker.show() -- replacement: nsIFilePicker.open() (async), example: Changeset where Thunderbird implemented that change. There's also a "lazy" replacement:

function PickerShow(fp) {
  let done = false;
  let rv, result;
  fp.open(result => {
    rv = result;
    done = true;
  });
  let thread = Components.classes["@mozilla.org/thread-manager;1"]
                         .getService().currentThread;
  while (!done) {
    thread.processNextEvent(true);
  }
  return rv;
}

• nsIDownloadManager
• Promise.jsm -- replacement: PromiseUtils.jsm
• nsIPrefBranch2 and nsIPrefBranchInternal -- replacement: nsIPrefBranch
• nsIExternalProtocolService.loadUrl -- replacement: nsIExternalProtocolService.loadURI
• nsIInputStreamPump.init: Change of arguments
• nsIAtomService - see bug 1393692 for removal from Thunderbird

Changes to JS and XUL in mozilla57

[1]

• `for each ()` construct [2] -- replacement: 'for (x of object)' or 'for (x of Object.values())'
• `with` construct [3]
• catch (ex if ex instanceof ExceptionType) (removed in mozilla47 already)
• versioned Javascript support -- replacement: In XUL files, links to JS files using <script type="application/x-javascript" ... > or <script type="application/x-javascript;version=1.7" ... >, change to <script type="application/javascript" ... >
• __iterator__ and Iterator()
• "legacy" generators, now need to use `function*` syntax (removed in mozilla? already)
• imports must be 100% correct now: Components.utils.import("resource://gre/modules/...") for Mozilla central imports, Components.utils.import("resource:///modules/...") for Thunderbird imports.

Changes in thunderbird57

• steelIApplication (removed due to removal of extIApplication) -- replacement: Services, AppConstants
• for (x in fixIterator(obj)) (removed due to removal of __iterator__) -- replacement: for (x of fixIterator(obj))

Removed in mozilla58

• Date.prototype.toLocaleFormat
• {get,set}ComplexValue use of nsISupportsString -- replacement: {get,set}StringPref(), example: Changeset where Thunderbird implemented that change
• Mechanism to store add-on preferences in defaults/preferences/xx.js. Thunderbird 58 Beta not affected (beta 1+2: backout of this core change, beta 3 has fix from TB 59). A fix has landed on Daily 59 as of 2017-12-12, see bug 1414398.

Changes to JS in mozilla58

[4]

• StopIteration [5]

Removed and changed in mozilla59

• Dialog (optionsType=1) and Inline (2) options were removed in bug 1414406. Thunderbird will not support that feature any more, only options in tabs (3) work now. Replacements:

1. If add-on's install.rdf contains no <em:optionsType> declaration, the add-on's preferences page (<em:optionsURL>) will only be accessible via a new submenu in Tools menu (implemented in bug 1419145, landed on Daily 59 as of 2017-12-22). The preferences will open in a dialog, as was the case in older versions.
   
2. If add-on's install.rdf contains <em:optionsType>3</em:optionsType>, the Preferences button will appear in the Add-on Manager tab besides the add-on, as was the case in older versions. Clicking the button will open the preferences page in a new tab. The preferences page (optionsURL) is also accessible via the new submenu in Tools menu and will open in a tab. No other value of <em:optionsType> is supported and TB will even refuse to install such add-ons (decision from bug 1414406).
3. Alternatively, add-ons may embed a WebExtension to display inline options [6][7]. This should be working now that bug 1418914 has been fixed.

• The statusbarpanel-iconic and statusbarpanel-iconic-text was removed, use toolbarbutton instead. See bug 1417198 for an example.
• nsIURI.spec is read-only, use url.mutate().setSpec(aSpec).finalize();

Changes to JS in mozilla59

[8]

• catch (ex if ...)
• |Services.intl.createDateTimeFormat(...)| in Thunderbird 57 and 58 changed to |new Services.intl.DateTimeFormat(...)|
• Components.classes['@mozilla.org/xmlextras/xmlhttprequest;1'] changed to new XMLHttpRequest(). Potentially you need to add Components.utils.importGlobalProperties(["XMLHttpRequest"]), which might not be necessary from version 61.

Changes in thunderbird59

• The id of the tab container of the 3pane has changed from "tabcontainer" to "tabmail-tabs". This was done to align the naming with the corresponding Firefox tab container. Add-ons need to replace document.getElementById("tabcontainer") with document.getElementById("tabmail-tabs").
• The bindings for the toolbar customization have moved from "global" to "messenger". If your add-on has customizable icons, please modify your chrome.manifest as shown below:

style chrome://global/content/customizeToolbar.xul    chrome://.../skin/... .css appversion<59.0a1
style chrome://messenger/content/customizeToolbar.xul chrome://.../skin/... .css appversion>=59.0a1

• CSS for the preference dialogs has moved from Mozilla core to Thunderbird. Add-ons that have an options/preferences dialog using <prefwindow> that requires this CSS need to add

<?xml-stylesheet type="text/css" href="chrome://messenger/skin/preferences/preferences.css"?>

to the XUL file that defines that dialog.

• Many bindings have moved from Mozilla core to Thunderbird. If you use any of the following

toolbar.xml#toolbox
toolbar.xml#toolbar
toolbar.xml#toolbar-drag
toolbar.xml#toolbar-menubar-autohide
mailWidgets.xml#menulist-description
mailWidgets.xml#menuitem-iconic-desc-noaccel
datetimepicker.xml#datepicker-popup
datetimepicker.xml#datepicker-grid
datetimepicker.xml#timepicker
spinbuttons.xml#spinbuttons
generalBindings.xml#statusbar
generalBindings.xml#statusbar
generalBindings.xml#statusbarpanel
generalBindings.xml#statusbarpanel

you need to include

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

in the respective XUL file of your add-on.

Removed and changed in mozilla60

• Removed interfaces: nsIDOMXPathResult, nsIDOMNodeFilter, many methods of nsIDOMNode, nsIDOMElement::{Get|Set}Attribute(), nsIDOMHTMLElement, nsIDOMHTMLDocument, nsIDOMHTMLMediaElement, nsIDOMFormData. Some of the removed interfaces only affect C++ in Thunderbird internally but are listed here for completeness.
• All attributes of nsIURI.spec are read-only, use for example url.mutate().setQuery(aQuery).finalize(); More examples in bug 1440693.
• Components.utils.import() has changed to ChromeUtils.import(). The old form still works (but is slower)
• Assignment to .innerHTML of an element does not work any more in chrome documents. As a temporary workaround, .setUnsafeInnerHTML or |document.allowUnsafeHTML = true;| can be used. This workaround was removed at mozilla61. The correct solution is to use .textContent, document.createElement(), DOMParser.parseFromString or document.execCommand("insertHTML", ...). Note that the jQuery library uses .innerHTML.
• Expression Closures have been dropped: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Expression_closures (use arrow functions).

Other changes relevant for TB60

• TB does no longer automatically pick up code changes if the addon is in a directory. Code changes are only picked up if install.rdf is changed. Also, it appears that TB needs to be restarted twice for the new code to come over (e.g. by restart addon or manually).
• Certain ways of defining Cu, Ci etc. do not work any longer, because Cc, Ci, Cu, and Cr are now defined by default in chrome (e.g. this does not work: const {classes: Cc, interfaces: Ci, utils: Cu, results : Cr} = Components; as found in some addons)
• Since ca. 60.6.1: Importing modules must be done like this: var { Gloda } = ChromeUtils.import("resource:///modules/gloda/public.js");, see TB 68 guide for more explanation

Also Note

The list above only contains selected changes relevant to Thunderbird add-ons. A larger list, some of which are only relevant to Firefox, can be seen at Firefox developer release notes where all the details, bugzilla bug reports and patches implementing the above changes, and more, can be found. If you find something missing in the list above, please tell us <tbd>.