Thunderbird/Add-ons Guide 57

Add-ons Guide for Thunderbird 57 and beyond

Mozilla core have disabled "legacy" add-ons (add-ons which are not based purely on WebExtensions) in Firefox 57. Because legacy add-ons are not supported from mozilla57 any more, many interfaces have been removed from Mozilla core.

Despite the interface removals, Thunderbird 57-60 and beyond and Seamonkey will still support these as legacy add-ons if the appropriate modifications are done to the add-on to adapt to the changed interfaces.

In addition, Thunderbird will be adding WebExtension support (bug 1396172) while maintaining "legacy" add-ons and hybrid add-ons. (Note, WebExtension in Thunderbird via bug 1396172 is not yet implmented.)

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).
• 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();

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();
• Components.utils.import() has changed to ChromeUtils.import().

Outlook and Suggestion

Suggestion for add-on authors wishing to be compatible with Thunderbird 59: Go, go, go! The fix for bug 1414398 (default preferences) and bug 1419145 (menu to access add-on options, tab options (3) work) has arrived (2017-12-12 and 2017-12-22). bug 1418914 has been fixed and then inline options can be achieved via an embedded WebExtension.

All add-ons compatible with TB 58 beta need further changes as mentioned above to be compatible with TB 59 Beta and TB 60 Daily.

Also Note

The list above only contains selected changes relevant to add-ons. The full list of changes can be seen at Firefox developer release notes where all the details, bugzilla bug reports and patches implementing those changes can be found.