From 6b440cc45d5a813939e20a8a842cbd73b6781b53 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Sat, 9 Dec 2023 06:58:50 +1300 Subject: [PATCH 01/12] Add documentation of component.utils exportFunction and cloneInto --- .../webextensions/api/components/index.md | 51 +++++ .../api/components/utils/cloneinto/index.md | 160 +++++++++++++ .../components/utils/exportfunction/index.md | 213 ++++++++++++++++++ .../api/components/utils/index.md | 55 +++++ 4 files changed, 479 insertions(+) create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/components/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/index.md new file mode 100644 index 000000000000000..7899c03341e3e09 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/index.md @@ -0,0 +1,51 @@ +--- +title: components +slug: Mozilla/Add-ons/WebExtensions/API/components +page-type: webextension-api +browser-compat: webextensions.api.components +--- + +{{AddonSidebar}} + +Utilities that enables an extension to [share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts). + +## Properties + +- {{WebExtAPIRef("components.utils")}} + - : Provides various utilities. + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.devtools`](https://developer.chrome.com/docs/extensions/mv2/devtools/) API. + + diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md new file mode 100644 index 000000000000000..4b29712a848c36e --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md @@ -0,0 +1,160 @@ +--- +title: components.utils.cloneInto() +slug: Mozilla/Add-ons/WebExtensions/API/components/utils/cloneInto +page-type: webextension-api-function +browser-compat: webextensions.api.components.utils.cloneInto +--- + +{{AddonSidebar()}} + +This function provides a safe way to take an object defined in a privileged scope and create a [structured clone](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) of it in a less-privileged scope. It returns a reference to the clone: + +```js +var clonedObject = cloneInto(myObject, targetWindow); +``` + +You can then assign the clone to an object in the target scope as an expando property, and scripts running in that scope can access it: + +```js +targetWindow.foo = clonedObject; +``` + +In this way privileged code, such as an add-on, can share an object with less-privileged code such as a web page script. + +## Syntax + +```js-nolint +let clonedObject = Components.utils.cloneInto( + obj, // object + targetScope, // object + options // object +); +``` + +### Parameters + +- `obj` + - : `object`. The object to clone. +- `targetScope` + - : `object`. The object to attach the object to. +- `options` {{optional_inline}} + - : `object`. Options for the function, as follows: + - `cloneFunctions` {{optional_inline}} + - : `Boolean`. Whether the object's functions should be cloned. Default to `false`. Cloned functions have the same semantics as functions exported using [`Components.utils.exportFunction`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction). See [Cloning objects that have functions](#Cloning_objects_that_have_functions). {{optional_inline}} + - `wrapReflectors` {{optional_inline}} + - : `boolean`. Whether objects reflected from C++, such as DOM objects, should be cloned. Defaults to `false`. See [Cloning objects that contain DOM elements](#Cloning_objects_that_contain_DOM_elements). + +### Return Value + +A reference to the cloned object. + +## Examples + +This add-on script creates an object, clones it into the content window and makes it a property of the content window global: + +```js +// add-on script +var addonScriptObject = { greeting: "hello from add-on" }; +contentWindow.addonScriptObject = cloneInto(addonScriptObject, contentWindow); +``` + +Scripts running in the page can access the object: + +```js +// page script +button.addEventListener( + "click", + function () { + console.log(window.addonScriptObject.greeting); // "hello from add-on" + }, + false, +); +``` + +Of course, you don't have to assign the clone to the window itself: you can assign it to some other object in the target scope: + +```js +contentWindow.foo.addonScriptObject = cloneInto( + addonScriptObject, + contentWindow, +); +``` + +You can also pass it into a function defined in the page script. Suppose the page script defines a function like this: + +```js +// page script +function foo(greeting) { + console.log("they said: " + greeting.message); +} +``` + +The add-on script can define an object, clone it, and pass it into this function: + +```js +// add-on script +var addonScriptObject = { message: "hello from add-on" }; +contentWindow.foo(cloneInto(addonScriptObject, contentWindow)); // "they said: hello from add-on" +``` + +### Cloning objects that have functions + +If the object to clone contains functions, you must pass the `{cloneFunctions:true}` flag or you get an error. If you do pass this flag, then functions in the object are cloned using the same mechanism used in [`Components.utils.exportFunction`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction): + +```js +// add-on script +var addonScriptObject = { + greetme: function () { + alert("hello from add-on"); + }, +}; +contentWindow.addonScriptObject = cloneInto(addonScriptObject, contentWindow, { + cloneFunctions: true, +}); +``` + +```js +// page script +var test = document.getElementById("test"); +test.addEventListener( + "click", + function () { + window.addonScriptObject.greetme(); + }, + false, +); +``` + +### Cloning objects that contain DOM elements + +By default, if the object you clone contains objects that are reflected from C++, such as DOM elements, the cloning operation fails with an error. If you pass the `{wrapReflectors:true}` flag, then the object you clone contains these objects: + +```js +// add-on script +var addonScriptObject = { + body: contentWindow.document.body, +}; +contentWindow.addonScriptObject = cloneInto(addonScriptObject, contentWindow, { + wrapReflectors: true, +}); +``` + +```js +// page script +var test = document.getElementById("test"); +test.addEventListener( + "click", + function () { + console.log(window.addonScriptObject.body.innerHTML); + }, + false, +); +``` + +Access to these objects in the target scope is subject to the normal [script security checks](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html). + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md new file mode 100644 index 000000000000000..0c492bdfe902968 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md @@ -0,0 +1,213 @@ +--- +title: components.utils.exportFunction() +slug: Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction +page-type: webextension-api-function +browser-compat: webextensions.api.components.utils.exportFunction +--- + +{{AddonSidebar()}} + +This function provides a safe way to expose a function from a privileged scope to a less-privileged scope. In this way privileged code, such as an add-on, can share code with less-privileged code like a normal web page script. A function exported from privileged to less-privileged code can be called from the less privileged code's context. + +The function has access to its surrounding closure just as if it were being called in the privileged context. + +The exported function does not have to be added to the less privileged code's global window object: it can be exported to any object in the target scope. + +`exportFunction()` is made available as a global in sandboxes which have the `wantExportHelpers` option set in the [`Sandbox()`](https://www.devdoc.net/web/developer.mozilla.org/en-US/docs/Components.utils.Sandbox.html) constructor. This includes Add-on SDK [content scripts](https://www.devdoc.net/web/developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/Accessing_the_DOM.html). + +To understand what happens if the functions you export accept arguments, see [Exporting functions that take arguments](#Exporting_functions_that_take_arguments). + +## Syntax + +```js-nolint +let exportFunctionuating = Components.utils.exportFunction( + func, // function + targetScope, // object + options // object +); +``` + +### Parameters + +- `func` + - : `function`. The function to export. +- `targetScope` + - : `object`. The object to attach the function to. This does not have to be the global window object: it could be any other object in the target window, or an object created by the caller. +- `options` {{optional_inline}} + + - : `object`. Options for the function, as follows: + + - `defineAs` {{optional_inline}} + - : `string`. The name of the function in `targetScope`. If this is omitted, you need to assign the return value of `exportFunction()` to an object in the target scope. + - `allowCrossOriginArguments` {{optional_inline}} + - : `boolean`. Do not check that arguments to the exported function are [subsumed](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) by the caller: this allows the caller to pass objects with a different origin into the exported function, which can then use its privileged status to make cross-origin requests with them. Defaults to `false`. + +### Return value + +The placeholder function which has been created in the target context. + +## Exporting functions that take arguments + +Any arguments passed into the function are not cloned. Instead, they are passed through to the privileged scope as [Xrays](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xray_vision.html). + +### Modifying the argument + +An Xray for an object refers to the original, so any changes to the argument that are made in the exported function affect the original object that was passed in: + +```js +// ad// privileged scope: for example, a content script +function changeMyName(user) { + user.name = "Bill"; +} +exportFunction(changeMyName, contentWindow, { + defineAs: "changeMyName", +}); +``` + +```js +// ad// less-privileged scope: for example, a page script +var user = { name: "Jim" }; +var test = document.getElementById("test"); +test.addEventListener( + "click", + function () { + console.log(user.name); // "Jim" + window.changeMyName(user); + console.log(user.name); // "Bill" + }, + false, +); +``` + +Note that this is subject to the normal rules of Xrays: for example, an expando property added to a DOM node is not visible in the original object. + +### Xray filtering and waiving + +Xrays provide a filtered view of the original object. For the full details refer to the documentation for [Xray vision](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xray_vision.html), but for example: functions are not visible in the Xrays of JavaScript [`Object`](/en-US/docs/JavaScript/Reference/Global_Objects/Object.1.html) types. If you need unfiltered access to the original, you can [waive Xrays](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xray_vision.html#waiving-xray-vision): + +```js +// ad// privileged scope: for example, a content script +function logUser(user) { + // console.log(user.getUser()); // error + console.log(user.wrappedJSObject.getUser()); // "Bill" +} +exportFunction(logUser, contentWindow, { + defineAs: "logUser", +}); +``` + +```js +// ad// less-privileged scope: for example, a page script +var user = { + getUser: function () { + return "Bill"; + }, +}; +var test = document.getElementById("test"); +test.addEventListener( + "click", + function () { + window.logUser(user); + }, + false, +); +``` + +### Passing functions as arguments + +If functions are given as arguments, these are also passed as Xrays. Because you can call `Function` Xrays like normal functions, this means that passing callbacks into the exported function works: + +```js +// ad// privileged scope: for example, a content script +function logUser(getUser) { + console.log(getUser()); // "Bill" +} +exportFunction(logUser, unsafeWindow, { + defineAs: "logUser", +}); +``` + +```js +// ad// less-privileged scope: for example, a page script +function getUser() { + return "Bill"; +} +var test = document.getElementById("test"); +test.addEventListener( + "click", + function () { + window.logUser(getUser); + }, + false, +); +``` + +### Cross-origin checking + +When the exported function is called each argument, including `this`, is checked to make sure that the caller [subsumes](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) that argument. This prevents passing cross-origin objects (such as `Window` or `Location`) to privileged functions, as the privileged code has full access to those objects and might unintentionally do something dangerous. This provision can be overridden by passing `{ allowCrossOriginArguments: true }` to `exportFunction`. + +## Examples + +### Export to global scope + +This add-on script defines a function, then exports it to a content window: + +```js +// addon-script.js +var salutation = "hello "; +function greetme(user) { + return salutation + user; +} +Components.utils.exportFunction(greetme, contentWindow, { defineAs: "foo" }); +``` + +Instead of using `defineAs`, the script can assign the result of `exportFunction` to an object in the target scope: + +```js +// addon-script.js +var salutation = "hello "; +function greetme(user) { + return salutation + user; +} +contentWindow.foo = Components.utils.exportFunction(greetme, contentWindow); +``` + +Either way, code running in the content window's scope can call the function: + +```js +// page-script.js +var greeting = foo("alice"); +console.log(greeting); +// "hello alice" +``` + +### Export to an existing local object + +Instead of attaching the function to the target's global `window` object, the caller can attach it to any other object in the target context. Suppose the content window defines a local variable `bar`: + +```js +// page-script.js +var bar = {}; +``` + +Now the add-on script can attach the function to `bar`: + +```js +// addon-script.js +Components.utils.exportFunction(greetme, contentWindow.bar, { + defineAs: "greetme", +}); +``` + +```js +// page-script.js +var value = bar.greetme("bob"); +console.log(value); +// "hello bob" +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md new file mode 100644 index 000000000000000..caa30af29f45bd8 --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md @@ -0,0 +1,55 @@ +--- +title: components.utils +slug: Mozilla/Add-ons/WebExtensions/API/components/utils +page-type: webextension-api-property +browser-compat: webextensions.api.components.utils +--- + +{{AddonSidebar}} + +Utilities that enables an extension to [share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts). + +## Functions + +- [`components.utils.exportFunction()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction) + - : Exports a function from a privileged scope to a less-privileged scope. +- [`components.utils.cloneInto()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/cloneInto) + - : Creates a structured clone of an object defined in a privileged scope in a less-privileged scope. + +{{WebExtExamples("h2")}} + +## Browser compatibility + +{{Compat}} + +> **Note:** This API is based on Chromium's [`chrome.components.utils`](https://developer.chrome.com/docs/extensions/reference/components_utils/) API. + + From 48c8a78e97ca7649c53e8cc4585b9d721a52b077 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Sun, 10 Dec 2023 06:06:37 +1300 Subject: [PATCH 02/12] Resolved broken links, various edits --- .../components/utils/exportfunction/index.md | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md index 0c492bdfe902968..dfb27535db76444 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md @@ -7,15 +7,13 @@ browser-compat: webextensions.api.components.utils.exportFunction {{AddonSidebar()}} -This function provides a safe way to expose a function from a privileged scope to a less-privileged scope. In this way privileged code, such as an add-on, can share code with less-privileged code like a normal web page script. A function exported from privileged to less-privileged code can be called from the less privileged code's context. +This function provides a safe way to expose a function from a privileged scope to a less-privileged scope. This way, privileged code, such as an extension, can share code with less-privileged code, such as a standard web page script. A function exported from privileged to less-privileged code can be called from the less privileged code's context. -The function has access to its surrounding closure just as if it were being called in the privileged context. +The function has access to its surrounding closure as if it were called in the privileged context. -The exported function does not have to be added to the less privileged code's global window object: it can be exported to any object in the target scope. +The exported function doesn't need to be added to the less privileged code's global window object; it can be exported to any object in the target scope. -`exportFunction()` is made available as a global in sandboxes which have the `wantExportHelpers` option set in the [`Sandbox()`](https://www.devdoc.net/web/developer.mozilla.org/en-US/docs/Components.utils.Sandbox.html) constructor. This includes Add-on SDK [content scripts](https://www.devdoc.net/web/developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts/Accessing_the_DOM.html). - -To understand what happens if the functions you export accept arguments, see [Exporting functions that take arguments](#Exporting_functions_that_take_arguments). +See [Exporting functions that take arguments](#Exporting_functions_that_take_arguments) to understand what happens if the functions you export accept arguments. ## Syntax @@ -32,19 +30,19 @@ let exportFunctionuating = Components.utils.exportFunction( - `func` - : `function`. The function to export. - `targetScope` - - : `object`. The object to attach the function to. This does not have to be the global window object: it could be any other object in the target window, or an object created by the caller. + - : `object`. The object to attach the function to. This doesn't have to be the global window object: it could be any object in the target window or an object created by the caller. - `options` {{optional_inline}} - : `object`. Options for the function, as follows: - `defineAs` {{optional_inline}} - - : `string`. The name of the function in `targetScope`. If this is omitted, you need to assign the return value of `exportFunction()` to an object in the target scope. + - : `string`. The name of the function in `targetScope`. If omitted, you need to assign the return value of `exportFunction()` to an object in the target scope. - `allowCrossOriginArguments` {{optional_inline}} - - : `boolean`. Do not check that arguments to the exported function are [subsumed](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) by the caller: this allows the caller to pass objects with a different origin into the exported function, which can then use its privileged status to make cross-origin requests with them. Defaults to `false`. + - : `boolean`. Whether to check that arguments to the exported function are [subsumed](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) by the caller. This allows the caller to pass objects with a different origin into the exported function, which can then use its privileged status to make cross-origin requests with them. Defaults to `false`. ### Return value -The placeholder function which has been created in the target context. +The placeholder function created in the target context. ## Exporting functions that take arguments @@ -52,7 +50,7 @@ Any arguments passed into the function are not cloned. Instead, they are passed ### Modifying the argument -An Xray for an object refers to the original, so any changes to the argument that are made in the exported function affect the original object that was passed in: +An Xray for an object refers to the original. Any changes to the argument made in the exported function affect the original object passed in. For example: ```js // ad// privileged scope: for example, a content script @@ -79,11 +77,11 @@ test.addEventListener( ); ``` -Note that this is subject to the normal rules of Xrays: for example, an expando property added to a DOM node is not visible in the original object. +This behavior is subject to the normal rules of Xrays. For example, an expando property added to a DOM node isn't visible in the original object. ### Xray filtering and waiving -Xrays provide a filtered view of the original object. For the full details refer to the documentation for [Xray vision](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xray_vision.html), but for example: functions are not visible in the Xrays of JavaScript [`Object`](/en-US/docs/JavaScript/Reference/Global_Objects/Object.1.html) types. If you need unfiltered access to the original, you can [waive Xrays](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xray_vision.html#waiving-xray-vision): +Xrays provide a filtered view of the original object. For example, functions aren't visible in the Xrays of JavaScript [`Object`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) types. If you need unfiltered access to the original, you can [waive Xrays](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xray_vision.html#waiving-xray-vision): ```js // ad// privileged scope: for example, a content script @@ -113,9 +111,11 @@ test.addEventListener( ); ``` +See [Xray vision](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xray_vision.html) in the Firefox Source Tree documentation for more information. + ### Passing functions as arguments -If functions are given as arguments, these are also passed as Xrays. Because you can call `Function` Xrays like normal functions, this means that passing callbacks into the exported function works: +If functions are given as arguments, these are also passed as Xrays. As you can call `Function` Xrays like normal functions, this means that passing callbacks into the exported function works: ```js // ad// privileged scope: for example, a content script @@ -144,16 +144,16 @@ test.addEventListener( ### Cross-origin checking -When the exported function is called each argument, including `this`, is checked to make sure that the caller [subsumes](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) that argument. This prevents passing cross-origin objects (such as `Window` or `Location`) to privileged functions, as the privileged code has full access to those objects and might unintentionally do something dangerous. This provision can be overridden by passing `{ allowCrossOriginArguments: true }` to `exportFunction`. +When the exported function is called, each argument, including `this`, is checked to make sure that the caller [subsumes](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) that argument. This prevents passing cross-origin objects (such as `Window` or `Location`) to privileged functions, as the privileged code has full access to those objects and could unintentionally do something dangerous. This provision can be overridden by passing `{ allowCrossOriginArguments: true }` to `exportFunction`. ## Examples ### Export to global scope -This add-on script defines a function, then exports it to a content window: +This script defines a function, then exports it to a content window: ```js -// addon-script.js +// extension-script.js var salutation = "hello "; function greetme(user) { return salutation + user; @@ -164,7 +164,7 @@ Components.utils.exportFunction(greetme, contentWindow, { defineAs: "foo" }); Instead of using `defineAs`, the script can assign the result of `exportFunction` to an object in the target scope: ```js -// addon-script.js +// extension-script.js var salutation = "hello "; function greetme(user) { return salutation + user; @@ -190,10 +190,10 @@ Instead of attaching the function to the target's global `window` object, the ca var bar = {}; ``` -Now the add-on script can attach the function to `bar`: +Now the extension script can attach the function to `bar`: ```js -// addon-script.js +// extension-script.js Components.utils.exportFunction(greetme, contentWindow.bar, { defineAs: "greetme", }); From 50aec8a67bd43aedb3d650a13d72fc1a5906b10b Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Tue, 12 Dec 2023 04:14:02 +1300 Subject: [PATCH 03/12] various edits --- .../en-us/mozilla/add-ons/webextensions/api/components/index.md | 2 +- .../webextensions/api/components/utils/cloneinto/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/index.md index 7899c03341e3e09..18473ce3a81184f 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/index.md @@ -12,7 +12,7 @@ Utilities that enables an extension to [share objects with page scripts](/en-US/ ## Properties - {{WebExtAPIRef("components.utils")}} - - : Provides various utilities. + - : Provides functions to export functions and create structured clones of objects defined in a privileged scope in a less-privileged scope. ## Browser compatibility diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md index 4b29712a848c36e..53514dd973e7526 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md @@ -19,7 +19,7 @@ You can then assign the clone to an object in the target scope as an expando pro targetWindow.foo = clonedObject; ``` -In this way privileged code, such as an add-on, can share an object with less-privileged code such as a web page script. +In this way privileged code, such as an extension, can share an object with less-privileged code such as a web page script. ## Syntax From aa20e9f8d495f840ba933315aa63d41e7ed0b65f Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Tue, 12 Dec 2023 14:43:49 +1300 Subject: [PATCH 04/12] Various edits --- .../add-ons/webextensions/api/components/index.md | 2 +- .../api/components/utils/cloneinto/index.md | 10 +++++----- .../api/components/utils/exportfunction/index.md | 14 +++++++------- .../webextensions/api/components/utils/index.md | 2 +- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/index.md index 18473ce3a81184f..fcbe1e2d7bc81a2 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.components {{AddonSidebar}} -Utilities that enables an extension to [share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts). +Utilities that enable an extension to [share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts). ## Properties diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md index 53514dd973e7526..c1b2e01f9860073 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md @@ -19,7 +19,7 @@ You can then assign the clone to an object in the target scope as an expando pro targetWindow.foo = clonedObject; ``` -In this way privileged code, such as an extension, can share an object with less-privileged code such as a web page script. +This enables privileged code, such as an extension, to share an object with less-privileged code, such as a web page script. ## Syntax @@ -38,7 +38,7 @@ let clonedObject = Components.utils.cloneInto( - `targetScope` - : `object`. The object to attach the object to. - `options` {{optional_inline}} - - : `object`. Options for the function, as follows: + - : `object`. Options for the function. - `cloneFunctions` {{optional_inline}} - : `Boolean`. Whether the object's functions should be cloned. Default to `false`. Cloned functions have the same semantics as functions exported using [`Components.utils.exportFunction`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction). See [Cloning objects that have functions](#Cloning_objects_that_have_functions). {{optional_inline}} - `wrapReflectors` {{optional_inline}} @@ -71,7 +71,7 @@ button.addEventListener( ); ``` -Of course, you don't have to assign the clone to the window itself: you can assign it to some other object in the target scope: +Of course, you don't have to assign the clone to the window itself; you can assign it to some other object in the target scope: ```js contentWindow.foo.addonScriptObject = cloneInto( @@ -99,7 +99,7 @@ contentWindow.foo(cloneInto(addonScriptObject, contentWindow)); // "they said: h ### Cloning objects that have functions -If the object to clone contains functions, you must pass the `{cloneFunctions:true}` flag or you get an error. If you do pass this flag, then functions in the object are cloned using the same mechanism used in [`Components.utils.exportFunction`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction): +If the object to clone contains functions, you must pass the `{cloneFunctions:true}` flag, or you get an error. If you do pass this flag, then functions in the object are cloned using the same mechanism used in [`Components.utils.exportFunction`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction): ```js // add-on script @@ -127,7 +127,7 @@ test.addEventListener( ### Cloning objects that contain DOM elements -By default, if the object you clone contains objects that are reflected from C++, such as DOM elements, the cloning operation fails with an error. If you pass the `{wrapReflectors:true}` flag, then the object you clone contains these objects: +By default, if the object you clone contains objects reflected from C++, such as DOM elements, the cloning operation fails with an error. If you pass the `{wrapReflectors:true}` flag, then the object you clone contains these objects: ```js // add-on script diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md index dfb27535db76444..22671d00f311dce 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md @@ -7,9 +7,9 @@ browser-compat: webextensions.api.components.utils.exportFunction {{AddonSidebar()}} -This function provides a safe way to expose a function from a privileged scope to a less-privileged scope. This way, privileged code, such as an extension, can share code with less-privileged code, such as a standard web page script. A function exported from privileged to less-privileged code can be called from the less privileged code's context. +This function provides a safe way to expose a function from a privileged scope to a less-privileged scope. This enables privileged code, such as an extension, to share code with less-privileged code, such as a standard web page script. A function exported from privileged to less-privileged code can be called from the less privileged code's context. -The function has access to its surrounding closure as if it were called in the privileged context. +The function has access to its surrounding closure as if called in the privileged context. The exported function doesn't need to be added to the less privileged code's global window object; it can be exported to any object in the target scope. @@ -30,15 +30,15 @@ let exportFunctionuating = Components.utils.exportFunction( - `func` - : `function`. The function to export. - `targetScope` - - : `object`. The object to attach the function to. This doesn't have to be the global window object: it could be any object in the target window or an object created by the caller. + - : `object`. The object to attach the function to. This doesn't have to be the global window object; it could be an object in the target window or created by the caller. - `options` {{optional_inline}} - - : `object`. Options for the function, as follows: + - : `object`. Options for the function. - `defineAs` {{optional_inline}} - : `string`. The name of the function in `targetScope`. If omitted, you need to assign the return value of `exportFunction()` to an object in the target scope. - `allowCrossOriginArguments` {{optional_inline}} - - : `boolean`. Whether to check that arguments to the exported function are [subsumed](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) by the caller. This allows the caller to pass objects with a different origin into the exported function, which can then use its privileged status to make cross-origin requests with them. Defaults to `false`. + - : `boolean`. Whether to check that arguments to the exported function are [subsumed](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) by the caller. This allows the caller to pass objects with a different origin into the exported function, which can then use its privileged status to make cross-origin requests with the object. Defaults to `false`. ### Return value @@ -144,13 +144,13 @@ test.addEventListener( ### Cross-origin checking -When the exported function is called, each argument, including `this`, is checked to make sure that the caller [subsumes](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) that argument. This prevents passing cross-origin objects (such as `Window` or `Location`) to privileged functions, as the privileged code has full access to those objects and could unintentionally do something dangerous. This provision can be overridden by passing `{ allowCrossOriginArguments: true }` to `exportFunction`. +When the exported function is called, each argument, including `this`, is checked to ensure the caller [subsumes](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/index.html#subsumes) that argument. This prevents passing cross-origin objects (such as `Window` or `Location`) to privileged functions, as the privileged code has full access to those objects and could unintentionally do something dangerous. This provision can be overridden by passing `{ allowCrossOriginArguments: true }` to `exportFunction`. ## Examples ### Export to global scope -This script defines a function, then exports it to a content window: +This script defines a function and then exports it to a content window: ```js // extension-script.js diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md index caa30af29f45bd8..4f26e1b5554a488 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md @@ -7,7 +7,7 @@ browser-compat: webextensions.api.components.utils {{AddonSidebar}} -Utilities that enables an extension to [share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts). +Utilities that enable an extension to [share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts). ## Functions From 17c18b8c0a4fb71594c59fa3e4a8838acae02bd2 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 28 Dec 2023 12:38:20 +1300 Subject: [PATCH 05/12] Remove incorrect "based on" note --- .../webextensions/api/components/index.md | 32 ------------------- .../api/components/utils/index.md | 32 ------------------- 2 files changed, 64 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/index.md index fcbe1e2d7bc81a2..f7ac09d279e2142 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/index.md @@ -17,35 +17,3 @@ Utilities that enable an extension to [share objects with page scripts](/en-US/d ## Browser compatibility {{Compat}} - -> **Note:** This API is based on Chromium's [`chrome.devtools`](https://developer.chrome.com/docs/extensions/mv2/devtools/) API. - - diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md index 4f26e1b5554a488..b5d34895c2026b4 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md @@ -21,35 +21,3 @@ Utilities that enable an extension to [share objects with page scripts](/en-US/d ## Browser compatibility {{Compat}} - -> **Note:** This API is based on Chromium's [`chrome.components.utils`](https://developer.chrome.com/docs/extensions/reference/components_utils/) API. - - From 2c29e9575648c02d02ece973762a9af55c83e563 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Fri, 29 Dec 2023 06:25:11 +1300 Subject: [PATCH 06/12] move exportFunction and cloneInto under Content_scripts --- .../webextensions/api/components/index.md | 19 --------------- .../api/components/utils/index.md | 23 ------------------- .../cloneinto/index.md | 0 .../exportfunction/index.md | 0 4 files changed, 42 deletions(-) delete mode 100644 files/en-us/mozilla/add-ons/webextensions/api/components/index.md delete mode 100644 files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md rename files/en-us/mozilla/add-ons/webextensions/{api/components/utils => content_scripts}/cloneinto/index.md (100%) rename files/en-us/mozilla/add-ons/webextensions/{api/components/utils => content_scripts}/exportfunction/index.md (100%) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/index.md deleted file mode 100644 index f7ac09d279e2142..000000000000000 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: components -slug: Mozilla/Add-ons/WebExtensions/API/components -page-type: webextension-api -browser-compat: webextensions.api.components ---- - -{{AddonSidebar}} - -Utilities that enable an extension to [share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts). - -## Properties - -- {{WebExtAPIRef("components.utils")}} - - : Provides functions to export functions and create structured clones of objects defined in a privileged scope in a less-privileged scope. - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md b/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md deleted file mode 100644 index b5d34895c2026b4..000000000000000 --- a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: components.utils -slug: Mozilla/Add-ons/WebExtensions/API/components/utils -page-type: webextension-api-property -browser-compat: webextensions.api.components.utils ---- - -{{AddonSidebar}} - -Utilities that enable an extension to [share objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts). - -## Functions - -- [`components.utils.exportFunction()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction) - - : Exports a function from a privileged scope to a less-privileged scope. -- [`components.utils.cloneInto()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/cloneInto) - - : Creates a structured clone of an object defined in a privileged scope in a less-privileged scope. - -{{WebExtExamples("h2")}} - -## Browser compatibility - -{{Compat}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/components/utils/cloneinto/index.md rename to files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md diff --git a/files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md similarity index 100% rename from files/en-us/mozilla/add-ons/webextensions/api/components/utils/exportfunction/index.md rename to files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md From 7b321faaeabd85f8b12b4aee922081006038f070 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Fri, 29 Dec 2023 06:49:27 +1300 Subject: [PATCH 07/12] Cross-reference and slug corrections --- .../add-ons/webextensions/content_scripts/cloneinto/index.md | 2 +- .../webextensions/content_scripts/exportfunction/index.md | 2 +- .../mozilla/add-ons/webextensions/content_scripts/index.md | 2 +- .../webextensions/sharing_objects_with_page_scripts/index.md | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md index c1b2e01f9860073..319dbc8ebb8c1ae 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md @@ -1,6 +1,6 @@ --- title: components.utils.cloneInto() -slug: Mozilla/Add-ons/WebExtensions/API/components/utils/cloneInto +slug: Mozilla/Add-ons/WebExtensions/Content_scripts/cloneInto page-type: webextension-api-function browser-compat: webextensions.api.components.utils.cloneInto --- diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md index 22671d00f311dce..5b68740b4471965 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md @@ -1,6 +1,6 @@ --- title: components.utils.exportFunction() -slug: Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction +slug: Mozilla/Add-ons/WebExtensions/Content_scripts/exportFunction page-type: webextension-api-function browser-compat: webextensions.api.components.utils.exportFunction --- diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/index.md index 346cc8596eb97df..1249d8f79512eb3 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/index.md @@ -159,7 +159,7 @@ If a content script needs to use a JavaScript library, then the library itself s ] ``` -> **Note:** Firefox _does_ provide some APIs that enable content scripts to access JavaScript objects created by page scripts, and to expose their own JavaScript objects to page scripts. +> **Note:** Firefox provides [cloneInto()](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/cloneinto) and [exportFunction()](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/exportFunction) to enable content scripts to access JavaScript objects created by page scripts and expose their JavaScript objects to page scripts. > > See [Sharing objects with page scripts](/en-US/docs/Mozilla/Add-ons/WebExtensions/Sharing_objects_with_page_scripts) for more details. diff --git a/files/en-us/mozilla/add-ons/webextensions/sharing_objects_with_page_scripts/index.md b/files/en-us/mozilla/add-ons/webextensions/sharing_objects_with_page_scripts/index.md index 0bc2d40c6955572..601d079126e45c9 100644 --- a/files/en-us/mozilla/add-ons/webextensions/sharing_objects_with_page_scripts/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/sharing_objects_with_page_scripts/index.md @@ -91,7 +91,7 @@ Firefox also provides APIs enabling content scripts to make objects available to ### exportFunction -Given a function defined in the content script, `exportFunction()` exports it to the page script's scope, so the page script can call it. +Given a function defined in the content script, [`exportFunction()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/exportFunction) exports it to the page script's scope, so the page script can call it. For example, let's consider an extension which has a background script like this: @@ -151,7 +151,7 @@ window.notify("Message from the page script!"); ### cloneInto -Given an object defined in the content script, this creates a clone of the object in the page script's scope, thereby making the clone accessible to page scripts. By default, this uses the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) to clone the object, meaning that functions in the object are not included in the clone. To include functions, pass the `cloneFunctions` option. +Given an object defined in the content script, [cloneInto()](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts/cloneinto) creates a clone of the object in the page script's scope, thereby making the clone accessible to page scripts. By default, this uses the [structured clone algorithm](/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm) to clone the object, meaning that functions in the object are not included in the clone. To include functions, pass the `cloneFunctions` option. For example, here's a content script that defines an object that contains a function, then clones it into the page script's scope: From 44465a50348e60f3b63cf8bb5f62b2bf76bf85e2 Mon Sep 17 00:00:00 2001 From: rebloor Date: Thu, 4 Apr 2024 14:57:03 +1300 Subject: [PATCH 08/12] Apply suggestions from review Co-authored-by: Rob Wu --- .../content_scripts/cloneinto/index.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md index 319dbc8ebb8c1ae..28418238e4fda8b 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md @@ -1,8 +1,8 @@ --- -title: components.utils.cloneInto() +title: cloneInto() slug: Mozilla/Add-ons/WebExtensions/Content_scripts/cloneInto page-type: webextension-api-function -browser-compat: webextensions.api.components.utils.cloneInto +browser-compat: webextensions.api.ContentScriptGlobalScope.cloneInto --- {{AddonSidebar()}} @@ -24,7 +24,7 @@ This enables privileged code, such as an extension, to share an object with less ## Syntax ```js-nolint -let clonedObject = Components.utils.cloneInto( +let clonedObject = cloneInto( obj, // object targetScope, // object options // object @@ -40,9 +40,9 @@ let clonedObject = Components.utils.cloneInto( - `options` {{optional_inline}} - : `object`. Options for the function. - `cloneFunctions` {{optional_inline}} - - : `Boolean`. Whether the object's functions should be cloned. Default to `false`. Cloned functions have the same semantics as functions exported using [`Components.utils.exportFunction`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction). See [Cloning objects that have functions](#Cloning_objects_that_have_functions). {{optional_inline}} + - : `boolean`. Whether the object's functions should be cloned. Default to `false`. Cloned functions have the same semantics as functions exported using [`exportFunction`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/Content_scripts/exportFunction). See [Cloning objects that have functions](#Cloning_objects_that_have_functions). {{optional_inline}} - `wrapReflectors` {{optional_inline}} - - : `boolean`. Whether objects reflected from C++, such as DOM objects, should be cloned. Defaults to `false`. See [Cloning objects that contain DOM elements](#Cloning_objects_that_contain_DOM_elements). + - : `boolean`. Whether DOM objects should be passed by reference instead of cloned. DOM objects are usually not clonable. Defaults to `false`. See [Cloning objects that contain DOM elements](#Cloning_objects_that_contain_DOM_elements). ### Return Value @@ -55,7 +55,7 @@ This add-on script creates an object, clones it into the content window and make ```js // add-on script var addonScriptObject = { greeting: "hello from add-on" }; -contentWindow.addonScriptObject = cloneInto(addonScriptObject, contentWindow); +window.addonScriptObject = cloneInto(addonScriptObject, window); ``` Scripts running in the page can access the object: @@ -74,6 +74,7 @@ button.addEventListener( Of course, you don't have to assign the clone to the window itself; you can assign it to some other object in the target scope: ```js +// Content script contentWindow.foo.addonScriptObject = cloneInto( addonScriptObject, contentWindow, From 32258a6f648d55914c1e0484b8452f3a80625538 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 4 Apr 2024 15:15:04 +1300 Subject: [PATCH 09/12] Further updates from feedback --- .../content_scripts/cloneinto/index.md | 33 +++++++++---------- .../content_scripts/exportfunction/index.md | 16 ++++----- 2 files changed, 23 insertions(+), 26 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md index 28418238e4fda8b..b6dec9b2f0e042e 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md @@ -50,11 +50,11 @@ A reference to the cloned object. ## Examples -This add-on script creates an object, clones it into the content window and makes it a property of the content window global: +This content script creates an object, clones it into the content window and makes it a property of the content window global: ```js -// add-on script -var addonScriptObject = { greeting: "hello from add-on" }; +// content script +var addonScriptObject = { greeting: "hello from your extension" }; window.addonScriptObject = cloneInto(addonScriptObject, window); ``` @@ -65,7 +65,7 @@ Scripts running in the page can access the object: button.addEventListener( "click", function () { - console.log(window.addonScriptObject.greeting); // "hello from add-on" + console.log(window.addonScriptObject.greeting); // "hello from your extension" }, false, ); @@ -75,10 +75,7 @@ Of course, you don't have to assign the clone to the window itself; you can assi ```js // Content script -contentWindow.foo.addonScriptObject = cloneInto( - addonScriptObject, - contentWindow, -); +window.foo.addonScriptObject = cloneInto(addonScriptObject, window); ``` You can also pass it into a function defined in the page script. Suppose the page script defines a function like this: @@ -90,12 +87,12 @@ function foo(greeting) { } ``` -The add-on script can define an object, clone it, and pass it into this function: +The content script can define an object, clone it, and pass it into this function: ```js -// add-on script -var addonScriptObject = { message: "hello from add-on" }; -contentWindow.foo(cloneInto(addonScriptObject, contentWindow)); // "they said: hello from add-on" +// content script +var addonScriptObject = { message: "hello from your extension" }; +window.foo(cloneInto(addonScriptObject, window)); // "they said: hello from your extension" ``` ### Cloning objects that have functions @@ -103,13 +100,13 @@ contentWindow.foo(cloneInto(addonScriptObject, contentWindow)); // "they said: h If the object to clone contains functions, you must pass the `{cloneFunctions:true}` flag, or you get an error. If you do pass this flag, then functions in the object are cloned using the same mechanism used in [`Components.utils.exportFunction`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/components/utils/exportFunction): ```js -// add-on script +// content script var addonScriptObject = { greetme: function () { - alert("hello from add-on"); + alert("hello from your extension"); }, }; -contentWindow.addonScriptObject = cloneInto(addonScriptObject, contentWindow, { +window.addonScriptObject = cloneInto(addonScriptObject, window, { cloneFunctions: true, }); ``` @@ -131,11 +128,11 @@ test.addEventListener( By default, if the object you clone contains objects reflected from C++, such as DOM elements, the cloning operation fails with an error. If you pass the `{wrapReflectors:true}` flag, then the object you clone contains these objects: ```js -// add-on script +// content script var addonScriptObject = { - body: contentWindow.document.body, + body: window.document.body, }; -contentWindow.addonScriptObject = cloneInto(addonScriptObject, contentWindow, { +window.addonScriptObject = cloneInto(addonScriptObject, window, { wrapReflectors: true, }); ``` diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md index 5b68740b4471965..1e2e9d58e18898e 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md @@ -1,8 +1,8 @@ --- -title: components.utils.exportFunction() +title: exportFunction() slug: Mozilla/Add-ons/WebExtensions/Content_scripts/exportFunction page-type: webextension-api-function -browser-compat: webextensions.api.components.utils.exportFunction +browser-compat: webextensions.api.ContentScriptGlobalScope.exportFunction --- {{AddonSidebar()}} @@ -18,7 +18,7 @@ See [Exporting functions that take arguments](#Exporting_functions_that_take_arg ## Syntax ```js-nolint -let exportFunctionuating = Components.utils.exportFunction( +let exportFunctionuating = exportFunction( func, // function targetScope, // object options // object @@ -57,7 +57,7 @@ An Xray for an object refers to the original. Any changes to the argument made i function changeMyName(user) { user.name = "Bill"; } -exportFunction(changeMyName, contentWindow, { +exportFunction(changeMyName, window, { defineAs: "changeMyName", }); ``` @@ -89,7 +89,7 @@ function logUser(user) { // console.log(user.getUser()); // error console.log(user.wrappedJSObject.getUser()); // "Bill" } -exportFunction(logUser, contentWindow, { +exportFunction(logUser, window, { defineAs: "logUser", }); ``` @@ -158,7 +158,7 @@ var salutation = "hello "; function greetme(user) { return salutation + user; } -Components.utils.exportFunction(greetme, contentWindow, { defineAs: "foo" }); +exportFunction(greetme, window, { defineAs: "foo" }); ``` Instead of using `defineAs`, the script can assign the result of `exportFunction` to an object in the target scope: @@ -169,7 +169,7 @@ var salutation = "hello "; function greetme(user) { return salutation + user; } -contentWindow.foo = Components.utils.exportFunction(greetme, contentWindow); +window.foo = exportFunction(greetme, window); ``` Either way, code running in the content window's scope can call the function: @@ -194,7 +194,7 @@ Now the extension script can attach the function to `bar`: ```js // extension-script.js -Components.utils.exportFunction(greetme, contentWindow.bar, { +exportFunction(greetme, window.bar, { defineAs: "greetme", }); ``` From e4b00ee3a08d951c09c46474d6138ea0e8d440cb Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Sun, 14 Apr 2024 15:02:34 +1200 Subject: [PATCH 10/12] casing fix --- .../add-ons/webextensions/content_scripts/cloneinto/index.md | 2 +- .../webextensions/content_scripts/exportfunction/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md index b6dec9b2f0e042e..28dbb99abe5b503 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md @@ -2,7 +2,7 @@ title: cloneInto() slug: Mozilla/Add-ons/WebExtensions/Content_scripts/cloneInto page-type: webextension-api-function -browser-compat: webextensions.api.ContentScriptGlobalScope.cloneInto +browser-compat: webextensions.api.contentScriptGlobalScope.cloneInto --- {{AddonSidebar()}} diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md index 1e2e9d58e18898e..5565a5b93dba849 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md @@ -2,7 +2,7 @@ title: exportFunction() slug: Mozilla/Add-ons/WebExtensions/Content_scripts/exportFunction page-type: webextension-api-function -browser-compat: webextensions.api.ContentScriptGlobalScope.exportFunction +browser-compat: webextensions.api.contentScriptGlobalScope.exportFunction --- {{AddonSidebar()}} From 3c7fbc5745295a555b1cf57bf0f7e7dff085810a Mon Sep 17 00:00:00 2001 From: rebloor Date: Sat, 21 Sep 2024 04:52:46 +1200 Subject: [PATCH 11/12] Apply suggestions from review Co-authored-by: Rob Wu --- .../add-ons/webextensions/content_scripts/cloneinto/index.md | 2 +- .../webextensions/content_scripts/exportfunction/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md index 28dbb99abe5b503..17702565104d016 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/cloneinto/index.md @@ -27,7 +27,7 @@ This enables privileged code, such as an extension, to share an object with less let clonedObject = cloneInto( obj, // object targetScope, // object - options // object + options // optional object ); ``` diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md index 5565a5b93dba849..b9bb2b1de2591f1 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md @@ -21,7 +21,7 @@ See [Exporting functions that take arguments](#Exporting_functions_that_take_arg let exportFunctionuating = exportFunction( func, // function targetScope, // object - options // object + options // optional object ); ``` From c69abf58bbdb742a1988826da92baf2128402a8a Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Sat, 21 Sep 2024 04:57:25 +1200 Subject: [PATCH 12/12] Remove spurious ad// --- .../content_scripts/exportfunction/index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md index b9bb2b1de2591f1..967e7ac1f7bf8ae 100644 --- a/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/content_scripts/exportfunction/index.md @@ -53,7 +53,7 @@ Any arguments passed into the function are not cloned. Instead, they are passed An Xray for an object refers to the original. Any changes to the argument made in the exported function affect the original object passed in. For example: ```js -// ad// privileged scope: for example, a content script +// privileged scope: for example, a content script function changeMyName(user) { user.name = "Bill"; } @@ -63,7 +63,7 @@ exportFunction(changeMyName, window, { ``` ```js -// ad// less-privileged scope: for example, a page script +// less-privileged scope: for example, a page script var user = { name: "Jim" }; var test = document.getElementById("test"); test.addEventListener( @@ -84,7 +84,7 @@ This behavior is subject to the normal rules of Xrays. For example, an expando p Xrays provide a filtered view of the original object. For example, functions aren't visible in the Xrays of JavaScript [`Object`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) types. If you need unfiltered access to the original, you can [waive Xrays](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xray_vision.html#waiving-xray-vision): ```js -// ad// privileged scope: for example, a content script +// privileged scope: for example, a content script function logUser(user) { // console.log(user.getUser()); // error console.log(user.wrappedJSObject.getUser()); // "Bill" @@ -95,7 +95,7 @@ exportFunction(logUser, window, { ``` ```js -// ad// less-privileged scope: for example, a page script +// less-privileged scope: for example, a page script var user = { getUser: function () { return "Bill"; @@ -118,7 +118,7 @@ See [Xray vision](https://firefox-source-docs.mozilla.org/dom/scriptSecurity/xra If functions are given as arguments, these are also passed as Xrays. As you can call `Function` Xrays like normal functions, this means that passing callbacks into the exported function works: ```js -// ad// privileged scope: for example, a content script +// privileged scope: for example, a content script function logUser(getUser) { console.log(getUser()); // "Bill" } @@ -128,7 +128,7 @@ exportFunction(logUser, unsafeWindow, { ``` ```js -// ad// less-privileged scope: for example, a page script +// less-privileged scope: for example, a page script function getUser() { return "Bill"; }