This document tries to cover all the changes that may by needed to make add-ons compatible with Thunderbird 68. If you find stuff that is no longer working but is not yet on this list, ask for help and advice in the mozilla.dev.apps.thunderbird newsgroup or check our communication channels.
The changes are grouped by category and are listed in the order we became aware of them.
Removed global Variables
A bunch of global variables available in some window scopes were removed. If you have used any of these, there are still available as the same names underneathComponents.interfaces.
main window
nsMsgFolderFlags
message composition window
nsIMsgCompDeliverMode
nsIMsgCompSendFormat
nsIMsgCompConvertible
nsIMsgCompType
nsIMsgCompFormat
nsIAbPreferMailFormat
nsIPlaintextEditorMail
nsISupportsString
mozISpellCheckingEngine
Removed XBL bindings
XBL is on death row. Many XBL bindings have been replaced or simply no longer exist. The remainder are being removed. This may result in slight behaviour changes for some UI components.
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.
Some XUL elements (or some of their attributes) no longer exist and must be replaced by an HTML element or some other XUL element. It does not matter, if you use these elements in a XUL file (as in overlay extensions) or create them via JavaScript (as in bootstrapped extensions).
In order to use HTML elements in a XUL file, you must load the HTML namespace into your overlay or dialog:
The following list also includes deprecated elements, which could still be used but Thunderbird has already started to purge their usage. In that case you must update your overlay files which are overlaying such elements, otherwise your overlay will not be applied. Check SearchFox for the current state of the files you are overlaying.
The replacements listed here might work in subtly different ways. Check your functionality!
<colorpicker>
Removed. Use
1
<html:inputtype="color">
Copied!
<progressmeter>
Removed. Use
1
<html:progressmax="100">
Copied!
<listbox>, <listitem>, <listcell> and <listcols>
All <listbox> related elements have been removed. Use<richlistbox> instead. A <richlistbox> does not support cells or columns, just one <richlistitem> per row (which can contain multiple other elements like hbox, vbox, labelor image elements)
Furthermore, a few dedicated listbox/richtlistboxmethods have been removed and can be replaced as follows:
listbox.appendItem(label, value):
1
let newNode = document.createXULElement("richlistitem");
2
​
3
// Store the value in the list item as before.
4
newNode.value = value;
5
let newLabel = document.createXULElement("label");
6
// The label is now stored in the value attribute of the label element.
7
newLabel.value = label;
8
​
9
newNode.appendChild(newLabel);
10
listbox.appendChild(newNode);
Copied!
listbox.insertItemAt(index, label, value):
1
let newNode = document.createXULElement("richlistitem");
Note that the DOCTYPE changed and the preference attribute now contains the full ID of the preference. If you used more than one prefpane you need to rework the UI into tabs.
Furthermore, note the included JavaScript file preferencesBindings.js at the bottom, which is mandatory to recreate the functionality of the preference attribute. It is also mandatory, that you include a custom JavaScript file (aspreferences.js in the above example) afterwards, which defines the types of the used preferences (which was formerly done inside the preferences tag). The file can be as short as this:
Per default, all preferences will be saved instantly after they have been changed. If you want to postpone saving until the user clicks the OK button, add a type attribute and a cancel button to the dialog:
If you are doing or plan to do any advanced stuff with the preferences in JavaScript, like validating user entered values and such, it is recommended to abandon the usage of the preference attribute (and preferencesBindings.js) and directly use the preferences service instead. Check out options.xul and options.js of the Shrunked Image Resizer.
<stringbundleset> and <stringbundle>
Both elements have been removed. To load and access your own string property files, include the following in your JavaScript:
1
let bundle = Services.strings.createBundle("chrome://path/to/your/string.property");
2
let stringProp = bundle.GetStringFromName("...");
Copied!
<statusbar> and <statusbarpanel>
Both elements are deprecated and its usage in Thunderbird is removed. They can be replaced by hboxelements with an appropriate class identifier:
1
<hboxclass="statusbar">
2
<labelclass="statusbarpanel"
3
context="..."
4
popup="..."
5
value="label"/>
6
</hbox>
Copied!
You may actually use other elements besides hbox as a replacement for the statusbarpanel, like label or image.
<menulist editable="true">
The XUL element menulist no longer supports the editable attribute. However, editable menulists have been re-implemented as custom elements. To be able to use it, you need some extra files to be linked from your document:
If you do not want to be dependent on Lightning being installed, you need to include the above files with your add-on.
<notificationbox>
Removed. Thunderbird now has fixed build in notification boxes, where notifications can be added. The following list shows how to access some of them:
Main window:
let notifyBox = specialTabs.msgNotificationBar;
Message composer window:
let notifyBox = gNotification.notificationbox;
Below the receipient list in the message composer window: let notifyBox = gMessageNotificationBar.msgNotificationBar;
Most calendar dialogs:
let notifyBox = gNotification.notificationbox;
Since you no longer "own" notification boxes, you should not clear them by calling
notifyBox.removeAllNotifications();
as that would remove notifications added by others. You can get a specific notification by calling
let notification = notifyBox.getNotificationWithValue(value);
and remove only that via
notificationbox.removeNotification(notification);
You can still add notification boxes wherever you want, if you do not want to use the build in notification boxes (or if there is none). More details can be found here.
<textbox type="search">
Removed. Use:
1
<textbox is="search-textbox" class="searchBox">
Copied!
Renamed XUL elements
<mail-multi-emailHeaderField>
The element mail-multi-emailHeaderField has been renamed into mail-multi-emailheaderfield (no camelCase anymore).
Each treecol can be either shown or hidden via the column picker. Up to TB68 the column picker closed after a column had been selected/toggled. By adding closemenu="none" to a treecol, the column picker stays open after the display state of associated treecol has been toggled.
Changed event behavior
<dialog> events
Previously, if you had a <dialog> and you wanted to respond to the buttons being pressed, you’d have something like this:
1
<dialogbuttons="accept,cancel"
2
ondialogaccept="return onAccept();">
3
<!-- dialog contents -->
4
</dialog>
Copied!
The event handler would return true if the dialog should close, or false to prevent closing. This no longer works. Instead, add the event handlers in JavaScript:
event.preventDefault();// Prevent the dialog closing.
3
});
Copied!
To prevent closing of the dialog, call preventDefault(). A return value is not needed.
This is valid for ondialogaccept, ondialogextra1, ondialogextra2 and ondialogcancel.
<wizard> and <wizardpage> events
The section about <dialog> events also applies to all onwizard… events on <wizard>, and onpage… events on <wizardpage>.
Changes to Geko JavaScript Engine
As JavaScript itself evolves, browser engines will change accordingly. The following changes represent changes that affect Javascript extension developers.
String Generic Methods Deprecated
The nonstandard generic string methods have been deprecated and removed in the Geko engine and therefore Thunderbird 68+. A deprecation exception is issued if any methods are used. The updated paradigm uses String instance methods allowing for the use on any object.
Deprecated Generics Syntax:
1
var strWithPadding =" Hello There ";
2
String.trim(strWithPadding);
Copied!
Instance Method Replacement:
1
var strWithPadding =" Hello There ";
2
strWithPadding.trim();
Copied!
The following String methods are affected by the change:
(All other String methods use the instance paradigm already)
Changes for JavaScript modules
Renamed JavaScript modules
A number of Javascript modules have been renamed with the .jsm extension. Most notably:
mailServices.js has been renamed to MailServices.jsm. This change was originally backwards-compatible with a deprecation warning, but the changes to module importing (see below) made that pointless and the old file has now been removed completely.
MailUtils.js is now MailUtils.jsm.
MailUtils.getFolderForUri was renamed to MailUtils.getExistingFolder.
Changed import of JavaScript modules
In Thunderbird 67, a major backwards-incompatible change was made to importing JavaScript modules. Where once you used any of these:
var scope = ChromeUtils.import("resource://foo/modules/Foo.jsm");// scope.Foo…
Copied!
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.
Changed API
LoginManager
The function to retrieve passwords has lost its first parameter. Instead of
1
var logins = Services.logins.findLogins({}, origin, formOrigin, realm);
Copied!
call it as
1
var logins = Services.logins.findLogins(origin, formOrigin, realm);
Copied!
document.persist(id, attribute)
Removed, use:
1
Services.xulStore.persist(node, attribute);
Copied!
Note: document.persist() used the ID attribute whereas xulStore.persist() uses the actual DOM node. More details in bug 1476678.
AddonManager
All methods of the AddonManager API now return a Promise instead of executing a callback. Instead of calling it as
The defaultAccount member can (since TB 65) have a null value - if for some reason it doesn't have, or can't work out, the default account.
Hence you need to null-check it, and possibly handle not having an account at all (if in no other way than by an error message).
nsIStringBundleService
Removed. Use
1
Services.strings.createBundle("chrome://...")
Copied!
nsIStreamListener
The onDataAvailable method lost its context argument. This was removed in bug 1525319 which breaks the API.
To be backward compatible you need to probe the parameters. In case the third parameter is an nsIInputStream it is the old API. If the second one is an input stream it is the new API.
1
onDataAvailable(...args){
2
// The old API passes the stream as third parameter.
thrownewError("Unknown signature for nsIStreamListener.onDataAvailable()");
11
}
Copied!
nsIRequestObserver
The onStartRequest and onStopRequest methods also no longer have a context argument, which could be detected in a similar way.
nsIProtocolHandler
The obsolete method newChannel was removed and newChannel2 was renamed to newChannel. (Bug 1528971.)
As newChannel has been unused for a long time it should be safe to just replace the old newChannel implementation with the newChannel2 and forward calls from newChannel2.
1
// Change the signature to the new one...
2
// ... you'll need to add the loadInfo parameter.
3
//
4
// Note loadInfo may be null in Thunderbird 60.
5
newChannel(URI, loadInfo){
6
// Do your logic here
7
}
8
​
9
// Keep the old method as it will be needed for backward compatibility...
10
// ... and forward the request to the new method.
11
newChannel2(URI, loadInfo){
12
returnthis.newChannel(URI, loadInfo);
13
}
Copied!
nsIScriptableUnicodeConverter
The method convertFromByteArray has been removed. The new preferred way to deal with unicode is through the TextEncoder and TextDecoder classes.
To convert byte arrays to different charsets, use
1
let charset ='utf-8';
2
let encodedByteArray =[/* ... */];
3
let decoder =newTextDecoder(charset);// charset can be omitted, default is utf-8
4
let decodedString = decoder.decode(newUint8Array(encodedByteArray));
Copied!
nsIDOMElement, nsIDOMNode and other basic DOM interfaces
Removed. Use Element, Node, etc. instead, which are now available in all scopes.
nsIDOMParser, nsIDOMSerializer, nsIXMLHttpRequest
These no longer need to be created by Cc[...].createInstance(Ci....), but simply via the new keyword:
new DOMParser();
new XMLSerializer();
new XMLHttpRequest();
They should be available in all scopes now. If not, the following is needed:
Cu.importGlobalProperties(["DOMParser"]);
Cu.importGlobalProperties(["XMLSerializer"]);
Cu.importGlobalProperties(["XMLHttpRequest"]);
nsITreeBoxObject, nsITreeColumn, nsITreeView
Trees have changed a lot. The tree object is now a XULTreeElement. It has lost thetreeBoxObject property, because the nsITreeBoxObject has been removed. Most of its methods can now be accessed directly through the tree object. For example:
1
// The treeBoxObject has been removed.
2
// tree.treeBoxObject.getLastVisibleRow();
3
tree.getLastVisibleRow();
Copied!
Furthermore, nsITreeColumn has been replaced by the TreeColumn object. Even though their interfaces look the same, they could behave differently. Check your implementation, as this affects almost all methods of nsITreeView.
If a method requires a TreeColumn parameter, a simple { id: columnName } object no longer works. Get a proper TreeColumn object via tree.columns.getNamedColumn(columnName).
Trees no longer support selecting individual cells. The TreeColumn object no longer has a selectable attribute and nsITreeView has lost its isSelectable() method.
In general, check searchfox.com to see the current definitions of tree related implementations:
A long time ago newChannelFromURI2() has been added as an alternative to newChannelFromURI(), which as become deprecated by now. With ESR68 the old name is used again.