Adapt to Changes in Thunderbird 61-68
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.
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 underneath
Components.interfaces.
- nsMsgFolderFlags
nsIMsgCompDeliverMode
nsIMsgCompSendFormat
nsIMsgCompConvertible
nsIMsgCompType
nsIMsgCompFormat
nsIAbPreferMailFormat
nsIPlaintextEditorMail
nsISupportsString
mozISpellCheckingEngine
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.
If you have your own XBL bindings, you can convert them to custom elements. Here are some notes on the process of converting an XBL binding into a custom element.
As part of the de-XBL effort, the usage of the nsIDOMDocumentXBL Interface has also been deprecated. This includes:
- getAnonymousElementByAttribute()
- getAnonymousNodes()
They have to be replaced by
document.getElementById()
, document.querySelectorAll()
or similar methods. The documents these methods have been used with have probably changed dramatically. Check out searchfox.org to learn about the current layouts.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:
<dialog
xmlns:html="http://www.w3.org/1999/xhtml"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
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!
Removed. Use
<html:input type="color">
Removed. Use
<html:progress max="100">
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
, label
or image
elements)Furthermore, a few dedicated
listbox/richtlistbox
methods have been removed and can be replaced as follows:listbox.appendItem(label, value)
:
let newNode = document.createXULElement("richlistitem");
// Store the value in the list item as before.
newNode.value = value;
let newLabel = document.createXULElement("label");
// The label is now stored in the value attribute of the label element.
newLabel.value = label;
newNode.appendChild(newLabel);
listbox.appendChild(newNode);
listbox.insertItemAt(index, label, value)
:
let newNode = document.createXULElement("richlistitem");
// See above example.
let refNode = listbox.getItemAtIndex(index);
refNode.parentNode.insertBefore(newNode, refNode);
listbox.removeItemAt(index)
:
listbox.getItemAtIndex(index).remove();
Removed. Use
<html:textarea>
All preference related XUL elements have been removed. If you have something like this in your add-on:
preferences.xul
<?xml version="1.0"?>
<?xml-stylesheet type="text/css" href="chrome://global/skin/"?>
<?xml-stylesheet type="text/css" href="chrome://messenger/skin/preferences/preferences.css"?>
<!DOCTYPE prefwindow SYSTEM "chrome://path/to/locale.dtd">
<prefwindow
id="appPreferences"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<prefpane
id="pane1"
label="&title">
<preferences>
<preference
id="pref1"
name="extensions.nameOfAddon.pref1"
type="bool"/>
<preference
id="pref2"
name="extensions.nameOfAddon.pref2"
type="string"/>
</preferences>
<checkbox
id="checkbox1"
preference="pref1"
label="&checkbox1.label;"
accesskey="&checkbox1.accesskey;"/>
<textbox
id="textbox1"
preference="pref2"/>
</prefpane>
</prefwindow>
it must be replaced by a
dialog
as follows:preferences.xul
<?xml version="1.0"?>
<?xml-stylesheet type="text/css" href="chrome://global/skin/"?>
<?xml-stylesheet type="text/css" href="chrome://messenger/skin/preferences/preferences.css"?>
<!DOCTYPE dialog SYSTEM "chrome://path/to/locale.dtd">
<dialog
id="appPreferences"
buttons="accept"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<vbox>
<checkbox
id="checkbox1"
preference="extensions.nameOfAddon.pref1"
label="&checkbox1.label;"
accesskey="&checkbox1.accesskey;"/>
<textbox
id="textbox1"
preference="extensions.nameOfAddon.pref2"/>
</vbox>
<script
src="chrome://global/content/preferencesBindings.js"
type="application/javascript"/>
<script
src="chrome://path/to/preferences.js"
type="application/javascript"/>
</dialog>
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:preferences.js
Preferences.addAll([
{ id: "extensions.nameOfAddon.pref1", type: "bool" },
{ id: "extensions.nameOfAddon.pref2", type: "string" },
{ id: "extensions.nameOfAddon.pref3", type: "int" },
]);
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:preferences.xul
<dialog
id="appPreferences"
type="child"
buttons="accept, cancel"
xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
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.Both elements have been removed. To load and access your own string property files, include the following in your JavaScript:
let bundle = Services.strings.createBundle("chrome://path/to/your/string.property");
let stringProp = bundle.GetStringFromName("...");
Both elements are deprecated and its usage in Thunderbird is removed. They can be replaced by
hbox
elements with an appropriate class
identifier:<hbox class="statusbar">
<label class="statusbarpanel"
context="..."
popup="..."
value="label" />
</hbox>
You may actually use other elements besides
hbox
as a replacement for the statusbarpanel
, like label
or image
.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:<?xml version="1.0"?>
<?xml-stylesheet type="text/css" href="chrome://global/skin/global.css"?>
<!-- New stylesheet needed: -->
<?xml-stylesheet type="text/css" href="chrome://messenger/skin/menulist.css"?>