Thunderbird/Add-ons Guide 57

From MozillaWiki
Jump to: navigation, search

Add-ons Guide for Thunderbird 57 to Thunderbird 60 ESR

(For Thunderbird 62 and beyond please visit the Add-ons Guide 62. Thunderbird 61 never existed, so we're skipping that number.)

Legacy add-ons: Thunderbird 57-60 and Seamonkey will still support legacy add-ons if add-on author makes modifications to adapt to the changed interfaces. The items to be modified are listed below. (The reasons for these changes is Firefox platform have disabled "legacy" add-ons in Firefox 57, add-ons which are not based purely on WebExtensions, so Mozilla removed core interfaces.)

WebExtension: WebExtension does not exist yet in Thunderbird. Thunderbird will be adding WebExtension support in bug 1396172 while maintaining "legacy" add-ons and hybrid add-ons.

Questions and Help: Add-on developers can get help in the mozilla.dev.apps.thunderbird newsgroup (the traditional venue) or in maildev mailing list. (see Thunderbird/CommunicationChannels#If_you.27re_a_developer Please ask questions in a forum before filing a bug report in bugzilla. Also test and fix your add-on using the latest beta version of Thunderbird.


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.
    Screenshot showing Add-on Options in TB 59
  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)
  • Expression Closures have been dropped: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Operators/Expression_closures (use arrow functions).

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.