Quicktext v6: Convert your scripts now to be ready early!

[jobisoft]

It is now time to update your scripts!

Quicktext v6 has reached its second milestone in being converted to the WebExtension technology. The ultimate goals of this effort are described in the announcement for the first milestone. Everything mentioned there is still important, so if you have not read that, please do so soon.

One major change in v6 is the new script engine. Quicktext v5 executed scripts with system privileges and just like Quicktext itself, scripts had full access to your computer and could do everything. This is no longer the case for Quicktext v6. The new script engine supports 2 different modes:

• internal scripts
• external scripts

If you use scripts in your daily workflow, we suggest trying out the pre-release and convert your scripts now. Otherwise, you may end up with a broken workflow, when Quicktext v6 is pushed as the official new version to all users.

Internal scripts

These scripts are how we used to define scripts in the "Scripts" tab of the Quicktext Manager UI. They now run with reduced privileges and instead of using core functions or accessing DOM elements of the compose window, they have access to a subset of the official WebExtension APIs. These APIs are used by add-on developers, are well documented and aim to be stable. That means your scripts will not break anymore when a new version of Thunderbird is released.

To see what is available for you, execute the following script:

console.log(this)

Currently, this will return something like the following:

Internal scripts have partial access to the compose API, the messages API and the identities API.

The methods of this.compose.* differ from the methods of the official compose API: The first tabId parameter must not be specified, as the methods available to internal scripts will always act on the current compose window.

Example

The AddRecipients community script now has to look like this:

  let type = this.quicktext.variables[0];
  let adresses = this.quicktext.variables[1].split(';');

  if (!type || !["to", "cc", "bcc", "reply-to"].includes(type)) {
    return;
  }

  if (type == "reply-to") {
    type = "replyTo";
  }

  let details = await this.compose.getComposeDetails();
  let recipients = new Set([...details[type], ...adresses].map(e => e.trim()));
  await this.compose.setComposeDetails({
    [type]: Array.from(recipients)
  });

Scripts no longer manipulate the compose fields directly, but can use getComposeDetails() to pull information from the composer and setComposeDetails() to update properties of the composer.

External scripts

There will be cases, where the methods available to internal scripts will be insufficient. We do plan to expose more methods on request, but we cannot expose all WebExtension APIs. Furthermore, there might even be cases where scripts still need to do everything. Both scenarios can be solved by external scripts.

An external script is shipped in a separate add-on. Since it can be executed natively, it can use all WebExtension APIs. For advanced use-cases, such an external script add-on can even include an Experiment and again have full access to the user's system.

As an example, we created a "Quicktext Community Scripts Add-on", which includes converted versions of the community scripts. At this point, we have not yet decided to officially make that available on ATN. We are still looking for a maintainer, as we do not have the resources to maintain it ourselves.

If that community add-on is installed, any of its stored scripts can be used by Quicktext. Instead of using the SCRIPT tag, use the ESCRIPT tag. To run the AddRecipients script:

[[[email protected]|AddRecipients|to|[email protected]]]

The first parameter is the id of the add-on, which has the script, the second parameter is the name of the requested script, followed by variables passed into the script. We also added the CSCRIPT tag, which simplifies this for the community script add-on:

[[CSCRIPT=AddRecipients|to|[email protected]]]

An example of a custom external script which uses an Experiment can be found here.

Note: Both examples of external script add-ons provide the same environment and the same this object to scripts. Any internal script using this.* should therefore work fine as an external script. External scripts however can use all the WebExtension APIs from the browser.* name space and will not work as internal scripts.

Need more help?

The converted community scripts in the scripts.mjs file of the "Quicktext Community Scripts Add-on" should give you an idea how to convert your scripts. You can however also ask questions in this issue.

Wanna try?

The pre-release can be found here:

• Release page: https://github.com/jobisoft/quicktext/releases/tag/v6.3.3
• XPI download: https://github.com/jobisoft/quicktext/releases/download/v6.3.3/quicktext_6_3_3.xpi

What about updates?

The provided pre-release version of Quicktext v6 will receive auto-updates from this GitHub repository, if a new pre-release version is published. Once the final version is published on ATN, the pre-release version will update to the ATN version and then receive regular updates through ATN again.