Bug 1943050 user scripts API - move legacy content #37975
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
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
|
There was a problem hiding this comment. Line 42 should be updated to add a space before the - - : 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.
+ - : 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.There was a problem hiding this comment. This line will go when the page is updated to add the new API docs. |
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
| 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. | ||
|
Comment on lines
+10
to
+11
There was a problem hiding this comment. Is it possible (and a good idea) to move this block into a reusable fragment that we can include in each page? (I may have asked something like this before on a previous issue. If so, apologies for the repetition.) There was a problem hiding this comment. As far as I'm aware, banners have to be coded as a macro (https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Banners_and_notices). If there is another option, it's not obviously documented. Even if the process was simple, as the banners here are static and will not be used ad hoc, the benefit of including a reusable fragment seemed limited. |
||
|
|
||
| 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` (Legacy)](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts_legacy/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
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()")}} |
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}} |
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_legacy/RegisteredUserScript/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")}} |
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
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@dotproto redirects are set automatically and we're specifically told not to edit them manually, see https://github.com/mdn/content/blob/main/CONTRIBUTING.md#moving-documents