Comment on page
Convert Overlay Extension to Legacy WebExtension
You must switch from an RDF manifest (
install.rdf) to a JSON manifest (
manifest.json). Here is a basic example. This RDF manifest:
<?xml version="1.0" encoding="utf-8"?>
<em:description>Does a thing!</em:description>
<em:optionsType>3</em:optionsType><!-- Options in a tab -->
Becomes this JSON manifest:
"id": "[email protected]",
"description": "Does a thing",
legacykey enables Thunderbird’s legacy support. Setting the
xulengages the new XUL overlay loader. The overlay loader is a Thunderbird component that takes XUL code as written in an overlay extension and applies it to the UI. In Thunderbird 60, this was a part of the core UI library, but it was removed. We have built a new overlay loader to replace as much of the removed code as possible.
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
optionskey to define the options page. The key
open_in_tabis optional and defaults to a value of
false. If your old RDF manifest included an
em:optionsTypeof 3, you can set
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.
Examples of overlay extension converted like this are:
Overlays in Thunderbird itself (except the calendar extensions) have been removed, so extensions can not overlay the removed Thunderbird overlays any more. For example, if your add-on overlaid
mailWindowOverlay.xul, that needs to be changed; in this example you most likely need to overlay
Furthermore, the new overlay loader does not properly support dependencies between overlays in different add-ons. As a result, you should only reference elements from the original document you're overlaying, or other overlays in the same extension. Most notably, you need to switch to non-overlay methods when altering the calendar user interface in the main window, or your add-on will not load relieably.
stylelines in your
chrome.manifestare now handled by the new overlay loader. You’ll see lines like this in the Error Console:
Ignoring unrecognized chrome manifest directive 'overlay'.
Those errors come from the old system, which no longer deals with such things.
You might see the same line, but regarding
<script>tags added to an overlay file are now run after the application of the entire overlay, regardless of their position in the overlay. This may cause unexpected behavior if your script previously ran before elements were inserted. For elements with event handlers these event handlers may run when the element is added, and they may fail if they rely on content being set up by a script which now runs after the creation of the element.
You may be used to putting the contents of a script directly in a document. This currently still works but it may break in the future. Inline scripts are strongly discouraged. Use a file instead.