Contributing to Thunderbird
Add-on Development
Convert Bootstrapped Extension to Legacy WebExtension
Switch to JSON manifest
You must switch from an RDF manifest (
install.rdf) to a JSON manifest (manifest.json). Here is a basic example. This RDF manifest:1
<?xml version="1.0" encoding="utf-8"?>
2
<RDF xmlns="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
3
xmlns:em="http://www.mozilla.org/2004/em-rdf#">
4
<Description about="urn:mozilla:install-manifest">
5
<em:id>[email protected]</em:id>
6
<em:type>2</em:type>
7
<em:bootstrap>true</em:bootstrap>
8
<em:name>Extension</em:name>
9
<em:description>Does a thing!</em:description>
10
<em:version>1.0</em:version>
11
<em:optionsURL>chrome://myextension/content/options.xul</em:optionsURL>
12
<em:optionsType>3</em:optionsType><!-- Options in a tab -->
13
<em:iconURL>chrome://myextension/content/icon32x32.png</em:iconURL>
14
<em:targetApplication>
15
<Description>
16
<em:id>{3550f703-e582-4d05-9a08-453d09bdfdc6}</em:id>
17
<em:minVersion>60.0</em:minVersion>
18
<em:maxVersion>60.*</em:maxVersion>
19
</Description>
20
</em:targetApplication>
21
</Description>
22
</RDF>
Copied!
Becomes this JSON manifest:
1
{
2
"manifest_version": 2,
3
"applications": {
4
"gecko": {
5
"id": "[email protected]",
6
"strict_min_version": "68.0"
7
}
8
},
9
"name": "Extension",
10
"description": "Does a thing",
11
"version": "2.0",
12
"icons": {
13
"32": "content/icon32x32.png"
14
},
15
"legacy": {
16
"type" : "bootstrap",
17
"options": {
18
"page": "chrome://myextension/content/options.xul",
19
"open_in_tab": true
20
}
21
}
22
}
Copied!
Detailed information about the possible config options for
manifest.json can be found in the MDN documentation.The
legacy key enables Thunderbird’s legacy support, for bootstrap extension you have to set the type key to bootstrap.The URL for icons must no longer be full chrome URL as before, but a simple path relative to the root directory of the add-on.
The shown example also specifies an optional
options key to define the options page. The key open_in_tab is optional and defaults to a value offalse. If your old RDF manifest included an em:optionsType of 3, you can set open_in_tab to true, to have your options opened again in a new tab instead of a new window.This example is only in English. You probably want to use translated strings in your manifest. Read this MDN article about it. Unfortunately that means you now need two sets of translated strings, one (that you already have) for your extension and another for the manifest.
Possible timing issues
The changes made in Thunderbird for bootstrapped add-ons to use
manifest.json may have changed when your code runs relative to events or notifications you've been listening for.- Use the window mediator or window watcher services to be notified about opening and closing windows, rather than listening for notifications.
- Wherever you access a window, always check if it has been completely loaded (
document.readyState == "complete"), or otherwise, wait for the load event.
In the following example,
loadIntoWindow is waiting for the window to be fully loaded and eventually calls loadIntoWindowAfterWindowIsReady to actually do something with it. There is no need to listen to any other load events outside of loadIntoWindow. This example also checks the state of already open windows during startup (line 14).bootstrap.js
1
var { Services } = ChromeUtils.import("resource://gre/modules/Services.jsm");
2
3
function install(data, reason) {
4
}
5
6
function uninstall(data, reason) {
7
}
8
9
function startup(data, reason) {
10
// Check if the window we want to modify is already open.
11
let windows = Services.wm.getEnumerator("mail:3pane");
12
while (windows.hasMoreElements()) {
13
let domWindow = windows.getNext().QueryInterface(Ci.nsIDOMWindow);
14
WindowListener.loadIntoWindow(domWindow);
15
}
16
17
// Wait for any new windows to open.
18
Services.wm.addListener(WindowListener);
19
}
20
21
function shutdown(data, reason) {
22
// When the application is shutting down we normally don't have to clean
23
// up any UI changes made.
24
if (reason == APP_SHUTDOWN) {
25
return;
26
}
27
28
let windows = Services.wm.getEnumerator("mail:3pane");
29
while (windows.hasMoreElements()) {
30
let domWindow = windows.getNext().QueryInterface(Ci.nsIDOMWindow);
31
WindowListener.unloadFromWindow(domWindow);
32
}
33
34
// Stop listening for any new windows to open.
35
Services.wm.removeListener(WindowListener);
36
}
37
38
var WindowListener = {
39
40
async loadIntoWindow(window) {
41
console.log("load (1/2): " + window.document.readyState);
42
if (window.document.readyState != "complete") {
43
// Make sure the window load has completed.
44
await new Promise(resolve => {
45
window.addEventListener("load", resolve, { once: true });
46
});
47
}
48
49
this.loadIntoWindowAfterWindowIsReady(window);
50
},
51
52
loadIntoWindowAfterWindowIsReady(window) {
53
console.log("load (2/2): " + window.document.readyState);
54
55
// Check if the opened window is the one we want to modify.
56
if (window.document.documentElement
57
.getAttribute("windowtype") === "mail:3pane") {
58
let document = window.document;
59
60
// Take any steps to add UI or anything to the window
61
// document.getElementById() etc. will work here.
62
}
63
},
64
65
unloadFromWindow(window) {
66
console.log("unload: " + window.document.readyState);
67
let document = window.document;
68
69
// Take any steps to remove UI or anything from the window
70
// document.getElementById() etc. will work here.
71
},
72
73
// nsIWindowMediatorListener functions
74
onOpenWindow(xulWindow) {
75
// A new window has opened.
76
let domWindow = xulWindow.QueryInterface(Ci.nsIInterfaceRequestor)
77
.getInterface(Ci.nsIDOMWindow);
78
79
this.loadIntoWindow(domWindow);
80
},
81
82
onCloseWindow(xulWindow) {
83
},
84
85
onWindowTitleChange(xulWindow, newTitle) {
86
},
87
};
88
Copied!
So you basically have to rename your current
loadIntoWindow to loadIntoWindowAfterWindowIsReady and add the new asynchronous loadIntoWindow , to make sure to access the window only after it has been fully loaded.Export as PDF
Copy link
Edit on GitHub