-
Notifications
You must be signed in to change notification settings - Fork 22.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Move legacy userScripts API documentation
- Loading branch information
Showing
12 changed files
with
235 additions
and
30 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
51 changes: 51 additions & 0 deletions
51
files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| --- | ||
| title: userScripts (Legacy) | ||
| slug: Mozilla/Add-ons/WebExtensions/API/userScripts_legacy | ||
| page-type: webextension-api | ||
| browser-compat: webextensions.api.userScripts_legacy | ||
| --- | ||
|
|
||
| {{AddonSidebar}} | ||
|
|
||
| > [!WARNING] | ||
| > This is documentation for the legacy `userScripts` API. It's available in Firefox for Manifest V2. For functionality to work with user scripts in Manifest V3 see the new {{WebExtAPIRef("userScripts")}} API. | ||
| Use this API to register user scripts, third-party scripts designed to manipulate webpages or provide new features. Registering a user script instructs the browser to attach the script to pages that match the URL patterns specified during registration. | ||
|
|
||
| This API offers similar capabilities to {{WebExtAPIRef("contentScripts")}} but with features suited to handling third-party scripts: | ||
|
|
||
| - execution is in an isolated sandbox: each user script is run in an isolated sandbox within the web content processes, preventing accidental or deliberate interference among scripts. | ||
| - access to the `window` and `document` global values related to the webpage the user script is attached to. | ||
| - no access to WebExtension APIs or associated permissions granted to the extension: the API script, which inherits the extension's permissions, can provide packaged WebExtension APIs to registered user scripts. An API script is declared in the extension's manifest file using the "user_scripts" manifest key. | ||
|
|
||
| > [!WARNING] | ||
| > This API requires the presence of the [`user_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts) key in the manifest.json, even if no API script is specified. For example. `user_scripts: {}`. | ||
| To use the API, call `{{WebExtAPIRef("userScripts_legacy.register","register()")}}` passing in an object defining the scripts to register. The method returns a Promise that is resolved with a `{{WebExtAPIRef("userScripts_legacy.RegisteredUserScript","RegisteredUserScript")}}` object. | ||
|
|
||
| > [!NOTE] | ||
| > User scripts are unregistered when the related extension page (from which the user scripts were registered) is unloaded, so you should register a user script from an extension page that persists at least as long as you want the user scripts to stay registered. | ||
| ## Types | ||
|
|
||
| - {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript","userScripts.RegisteredUserScript")}} | ||
| - : The `object` returned by the {{WebExtAPIRef("userScripts_legacy.register","register()")}} method. It represents the registered user scripts and is used to deregister the user scripts. | ||
|
|
||
| ## Methods | ||
|
|
||
| - {{WebExtAPIRef("userScripts_legacy.register()","userScripts.register()")}} | ||
| - : Registers user scripts. | ||
|
|
||
| ## Events | ||
|
|
||
| - {{WebExtAPIRef("userScripts_legacy.onBeforeScript","userScripts.onBeforeScript")}} | ||
| - : An event available to the API script, registered in[`"user_scripts"`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts), that execute before a user script executes. Use it to trigger the export of the additional APIs provided by the API script, so they are available to the user script. | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [Working with `userScripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/Working_with_userScripts) | ||
| - {{WebExtAPIRef("contentScripts","browser.contentScripts")}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
75 changes: 75 additions & 0 deletions
75
files/en-us/mozilla/add-ons/webextensions/api/userscripts_legacy/register/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| --- | ||
| title: userScripts.register() (Legacy) | ||
| slug: Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/register | ||
| page-type: webextension-api-function | ||
| browser-compat: webextensions.api.userScripts_legacy.register | ||
| --- | ||
|
|
||
| {{AddonSidebar}} | ||
|
|
||
| > [!WARNING] | ||
| > This is documentation for the legacy `userScripts` API. It's available in Firefox for Manifest V2. For functionality to work with user scripts in Manifest V3 see the new {{WebExtAPIRef("userScripts")}} API. | ||
| This method enables user scripts to be registered from an extension's pages (such as the background page). | ||
|
|
||
| This method is very similar to the {{WebExtAPIRef("contentScripts.register","contentScripts.register()")}} API method (for example, they both return a promise that resolves to an API object with an {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript.unregister","unregister()")}} method for unregistering the script). There are, however, differences in the options supported. | ||
|
|
||
| This is an asynchronous method that returns a {{JSxRef("Promise")}}. | ||
|
|
||
| ## Syntax | ||
|
|
||
| ```js-nolint | ||
| const registeredUserScript = await browser.userScripts.register( | ||
| userScriptOptions // object | ||
| ); | ||
| // … | ||
| await registeredUserScript.unregister(); | ||
| ``` | ||
|
|
||
| ### Parameters | ||
|
|
||
| - `userScriptOptions` | ||
|
|
||
| - : `object`. Represents the user scripts to register. It has similar syntax to {{WebExtAPIRef("contentScripts.register","contentScripts.register()")}}. | ||
|
|
||
| The `UserScriptOptions` object has the following properties: | ||
|
|
||
| - `scriptMetadata` {{Optional_Inline}} | ||
| - : A `JSON` object containing arbitrary metadata properties associated with the registered user scripts. However, while arbitrary, the object must be serializable, so it is compatible with [the structured clone algorithm.](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) This metadata is used to pass details from the script to the [API script](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts). For example, providing details of a subset of the APIs that need to be injected by the [API script](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/user_scripts). The API does not use this metadata, | ||
| - `allFrames` {{Optional_Inline}} | ||
| - : Same as `all_frames` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) key. | ||
| - `cookieStoreId` {{optional_inline}} | ||
| - : An array of cookie store ID strings or a string containing a cookie store ID. Registers the user script in the tabs that belong to the cookie store IDs. This enables scripts to be registered for all default or non-contextual identity tabs, private browsing tabs (if the [extension is enabled in private browsing](https://support.mozilla.org/en-US/kb/extensions-private-browsing)), the tabs of a [contextual identity](/en-US/docs/Mozilla/Add-ons/WebExtensions/Work_with_contextual_identities), or a combination of these. | ||
| - `excludeGlobs` {{Optional_Inline}} | ||
| - : Same as `exclude_globs` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) key. | ||
| - `excludeMatches` {{Optional_Inline}} | ||
| - : Same as `exclude_matches` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) key. | ||
| - `includeGlobs` {{Optional_Inline}} | ||
| - : Same as `include_globs` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) key. | ||
| - `js` | ||
| - : An array of objects. Each object has either a property named `file`, which is a URL starting at the extension's manifest.json and pointing to a JavaScript file to register, or a property named `code`, which contains JavaScript code to register. | ||
| - `matchAboutBlank` {{Optional_Inline}} | ||
| - : Same as `match_about_blank` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) key. | ||
| - `matches` | ||
| - : Same as `matches` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) key. | ||
| The URL patterns provided in `matches` must be enabled by the host permissions defined in the manifest [`permission`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions) property or enabled by the user from the [`optional_permissions`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/optional_permissions) list. For example, if matches includes `https://mozilla.org/a` a script is only registered if host permissions include, for example, `https://mozilla.org/*`. If the URL pattern isn't enabled, the call to register fails with the error "Permission denied to register a user script for ORIGIN". | ||
| - `runAt` {{Optional_Inline}} | ||
| - : Same as `run_at` in the [`content_scripts`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/content_scripts) key. | ||
|
|
||
| Unlike content script options, the userScriptOptions object does not have a CSS property. Use {{WebExtAPIRef("contentScripts.register","contentScripts.register()")}} to dynamically register and unregister stylesheets. | ||
|
|
||
| ### Return value | ||
|
|
||
| A {{JSxRef("Promise")}} that is fulfilled with a {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript","RegisteredUserScript")}} object that is use to unregister the user scripts. | ||
|
|
||
| > [!NOTE] | ||
| > User scripts are unregistered when the related extension page (from which the user scripts were registered) is unloaded, so you should register user scripts from an extension page that persists at least as long as you want the user scripts to stay registered. | ||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - {{WebExtAPIRef("contentScripts.register","contentScripts.register()")}} | ||
| - {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript.unregister","RegisteredUserScript.unregister()")}} |
27 changes: 27 additions & 0 deletions
27
...illa/add-ons/webextensions/api/userscripts_legacy/registereduserscript/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| --- | ||
| title: userScripts.RegisteredUserScript (Legacy) | ||
| slug: Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/RegisteredUserScript | ||
| page-type: webextension-api-type | ||
| browser-compat: webextensions.api.userScripts_legacy.RegisteredUserScript | ||
| --- | ||
|
|
||
| {{AddonSidebar}} | ||
|
|
||
| > [!WARNING] | ||
| > This is documentation for the legacy `userScripts` API. It's available in Firefox for Manifest V2. For functionality to work with user scripts in Manifest V3 see the new {{WebExtAPIRef("userScripts")}} API. | ||
| A `RegisteredUserScript` object is returned by a call to {{WebExtAPIRef("userScripts_legacy.register","userScripts.register()")}} and represents the user scripts registered in that call. | ||
|
|
||
| The object defines a single method, {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript.unregister","unregister()")}}, which is used to unregister the user scripts. | ||
|
|
||
| > [!NOTE] | ||
| > If this object is destroyed (for example because it goes out of scope) then the associated scripts will be unregistered automatically, so you should keep a reference to this object for as long as you want the user scripts to stay registered. | ||
| ## Methods | ||
|
|
||
| - {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript.unregister","unregister()")}} | ||
| - : Unregisters the user scripts represented by this object. | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} |
43 changes: 43 additions & 0 deletions
43
...s/webextensions/api/userscripts_legacy/registereduserscript/unregister/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| --- | ||
| title: RegisteredUserScript.unregister() (Legacy) | ||
| slug: Mozilla/Add-ons/WebExtensions/API/userScripts/RegisteredUserScript_legacy/unregister | ||
| page-type: webextension-api-function | ||
| browser-compat: webextensions.api.userScripts_legacy.RegisteredUserScript.unregister | ||
| --- | ||
|
|
||
| {{AddonSidebar}} | ||
|
|
||
| > [!WARNING] | ||
| > This is documentation for the legacy `userScripts` API. It's available in Firefox for Manifest V2. For functionality to work with user scripts in Manifest V3 see the new {{WebExtAPIRef("userScripts")}} API. | ||
| The `unregister()` method of the {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript","RegisteredUserScript")}} object unregisters the user scripts represented by the object, user scripts that were registered using {{WebExtAPIRef("userScripts_legacy.register","userScripts.register()")}}. | ||
|
|
||
| > [!NOTE] | ||
| > User Scripts are automatically unregistered when the related extension page (from which the user scripts were registered) is unloaded, so you should register a user script from an extension page that persists at least as long as you want the user scripts to stay registered. | ||
| ## Syntax | ||
|
|
||
| ```js-nolint | ||
| const registeredUserScript = await browser.userScripts.register( | ||
| userScriptOptions // object | ||
| ); | ||
| // … | ||
| await registeredUserScript.unregister() | ||
| ``` | ||
|
|
||
| ### Parameters | ||
|
|
||
| None. | ||
|
|
||
| ### Return value | ||
|
|
||
| A {{JSxRef("Promise")}} that is resolved once the user scripts are unregistered. The promise does not return a value. | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - {{WebExtAPIRef("userScripts_legacy.register","userScripts.register()")}} | ||
| - {{WebExtAPIRef("userScripts_legacy.RegisteredUserScript","RegisteredUserScript")}} |
7 changes: 5 additions & 2 deletions
7
...pi/userscripts/userscriptoptions/index.md → ...scripts_legacy/userscriptoptions/index.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes
File renamed without changes
Oops, something went wrong.