contentScripts API

Hint

The contentScripts API is inherited from Firefox, and its primary documentation is maintained by Mozilla at MDN. Thunderbird implements only the subset of functions, events, and types listed here. The MDN pages may provide further details and examples, but they may also reference features that are not supported in Thunderbird.

Functions

register(contentScriptOptions)

– [Added in TB 59]

Register a content script programmatically

Parameters

contentScriptOptions

contentScriptOptions

(RegisteredContentScriptOptions)



Types

ExecutionWorld

The JavaScript world for a script to execute within. ISOLATED is the default execution environment of content scripts, MAIN is the web page’s execution environment.

string

Supported values:

ISOLATED



MAIN



ExtensionFileOrCode

Specify code, either by pointing to a file or by providing the code directly. Only one of the two is allowed.

object

file

file

(ExtensionURL)



A URL relative to the extension’s manifest.json file, and pointing to a JavaScript file to register.

or

object

code

code

(string)



A string of JavaScript code to register.

ExtensionURL

A path relative to the root of the extension.

string

MatchPattern

string

Supported values:

<all_urls>



or

MatchPatternRestricted

or

MatchPatternUnestricted

MatchPatternRestricted

Same as MatchPattern above, but excludes <all_urls>

string

or

string

MatchPatternUnestricted

Mostly unrestricted match patterns for privileged add-ons. This should technically be rejected for unprivileged add-ons, but, reasons. The MatchPattern class will still refuse privileged schemes for those extensions.

string

RegisteredContentScript

– [Added in TB 59]

An object that represents a content script registered programmatically

object

RegisteredContentScriptOptions

Details of a content script registered programmatically

object

matches

matches

(array of MatchPattern)



allFrames

[allFrames]

(boolean, optional)



If allFrames is true, implies that the JavaScript or CSS should be injected into all frames of current page. By default, it’s false and is only injected into the top frame.

cookieStoreId

[cookieStoreId]

(array of string or string, optional)



limit the set of matched tabs to those that belong to the given cookie store id

css

[css]

(array of ExtensionFileOrCode, optional)



The list of CSS files to inject

excludeGlobs

[excludeGlobs]

(array of string, optional)



excludeMatches

[excludeMatches]

(array of MatchPattern, optional)



includeGlobs

[includeGlobs]

(array of string, optional)



js

[js]

(array of ExtensionFileOrCode, optional)



The list of JS files to inject

matchAboutBlank

[matchAboutBlank]

(boolean, optional)



If matchAboutBlank is true, then the code is also injected in about:blank and about:srcdoc frames if your extension has access to its parent document. Ignored if matchOriginAsFallback is specified. By default it is false.

matchOriginAsFallback

[matchOriginAsFallback]

(boolean, optional)



If matchOriginAsFallback is true, then the code is also injected in about:, data:, blob: when their origin matches the pattern in ‘matches’, even if the actual document origin is opaque (due to the use of CSP sandbox or iframe sandbox). Match patterns in ‘matches’ must specify a wildcard path glob. By default it is false.

runAt

[runAt]

(RunAt, optional)



The soonest that the JavaScript or CSS will be injected into the tab. Defaults to “document_idle”.

world

[world]

(ExecutionWorld, optional)



The JavaScript world for a script to execute within. Defaults to “ISOLATED”.

RunAt

– [Added in TB 45]

The soonest that the JavaScript or CSS will be injected into the tab.

string

Supported values:

document_end



document_idle



document_start

