From 7d07889272ea94fe5154568a29809c50581e82fa Mon Sep 17 00:00:00 2001 From: rebloor Date: Sat, 6 Jan 2024 06:03:20 +1300 Subject: [PATCH] Add contextualIdentities.move (#31191) * Add contextualIdentities.move * typo * Apply suggestions from review * Examples update * Apply suggestions from review Co-authored-by: Rob Wu --------- Co-authored-by: Rob Wu --- .../api/contextualidentities/index.md | 4 +- .../api/contextualidentities/move/index.md | 94 +++++++++++++++++++ .../mozilla/firefox/releases/123/index.md | 2 + 3 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 files/en-us/mozilla/add-ons/webextensions/api/contextualidentities/move/index.md diff --git a/files/en-us/mozilla/add-ons/webextensions/api/contextualidentities/index.md b/files/en-us/mozilla/add-ons/webextensions/api/contextualidentities/index.md index d854243ce505efb0..55efc4999ad5a7d4 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/contextualidentities/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/contextualidentities/index.md @@ -35,7 +35,9 @@ To use this API you need to include the "contextualIdentities" and "cookies" [pe - {{WebExtAPIRef("contextualIdentities.create()")}} - : Creates a new contextual identity. - {{WebExtAPIRef("contextualIdentities.get()")}} - - : Retrieves a single contextual identity, given its cookie store ID. + - : Retrieves a contextual identity, given its cookie store ID. +- {{WebExtAPIRef("contextualIdentities.move()")}} + - : Moves one or more contextual identities within the list of contextual identities. - {{WebExtAPIRef("contextualIdentities.query()")}} - : Retrieves all contextual identities, or all contextual identities with a particular name. - {{WebExtAPIRef("contextualIdentities.update()")}} diff --git a/files/en-us/mozilla/add-ons/webextensions/api/contextualidentities/move/index.md b/files/en-us/mozilla/add-ons/webextensions/api/contextualidentities/move/index.md new file mode 100644 index 0000000000000000..12ec910109c1f1bc --- /dev/null +++ b/files/en-us/mozilla/add-ons/webextensions/api/contextualidentities/move/index.md @@ -0,0 +1,94 @@ +--- +title: contextualIdentities.move() +slug: Mozilla/Add-ons/WebExtensions/API/contextualIdentities/move +page-type: webextension-api-function +browser-compat: webextensions.api.contextualIdentities.move +--- + +{{AddonSidebar()}} + +Moves one or more contextual identities to a new position within the list of contextual identities. + +This is an asynchronous function that returns a [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +## Syntax + +```js-nolint +let moveContainers = browser.contextualIdentities.move( + cookieStoreIds, // string or array of string + position // integer +) +``` + +### Parameters + +- `cookieStoreIds` + - : `string` or `array` of `string`. An ordered list of the contextual identity cookie store IDs to move. +- `position` + - : `integer`. The position to move `cookieStoreIds` to in the list of contextual identities. Zero-based; `0` indicates the first position. `-1` indicates that the items are moved to the end of the list. + +### Return value + +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that is fulfilled when the contextual identities are reordered. The promise is rejected if the request is for an invalid move or the contextual identities feature is not enabled. + +## Examples + +This example moves the first identity to the end and then back to the start. + +```js +let identities = await browser.contextualIdentities.query({}); +let firstId = identities[0].cookieStoreId; + +// Moves first identity to the end. +await browser.contextualIdentities.move(firstId, -1); + +// Move identity to the start again. +await browser.contextualIdentities.move(firstId, 0); +``` + +Another way of moving the first identity to the end is by moving all other identities to the start. + +```js +let identities = await browser.contextualIdentities.query({}); +let ids = identities.map((identity) => identity.cookieStoreId); +// Create an array without the first item: +let otherIds = ids.slice(1); + +// Move other identities to the start, +// effectively putting the first identity at the end. +await browser.contextualIdentities.move(otherIds, 0); +``` + +This example moves the "Personal" identity to before "Work". The example assumes containers with these names to exist. This may not be the case in customized or localized (non-English) Firefox instances. + +```js +let identities = await browser.contextualIdentities.query({}); + +// Find the index and ID of the container with the name "Personal". +let personalIndex = identities.findIndex((ci) => ci.name === "Personal"); +if (personalIndex === -1) { + throw new Error("Personal container not found"); +} +let personalId = identities[personalIndex].cookieStoreId; + +// Find the index of the container with the name "Work". +let workIndex = identities.findIndex((identity) => identity.name === "Work"); +if (workIndex === -1) { + throw new Error("Work container not found!"); +} + +if (personalIndex < workIndex) { + // When the Personal identity moves, all following + // identities shift to the left by one. To place + // the Personal identity before the Work identity, + // we should therefore subtract one. + workIndex--; +} +await browser.contextualIdentities.move(personalId, workIndex); +``` + +{{WebExtExamples}} + +## Browser compatibility + +{{Compat}} diff --git a/files/en-us/mozilla/firefox/releases/123/index.md b/files/en-us/mozilla/firefox/releases/123/index.md index 4c9da87c1f530ba3..6db537a1a42e6120 100644 --- a/files/en-us/mozilla/firefox/releases/123/index.md +++ b/files/en-us/mozilla/firefox/releases/123/index.md @@ -56,6 +56,8 @@ This article provides information about the changes in Firefox 123 that affect d ## Changes for add-on developers +- Addition of fhe {{WebExtAPIRef("contextualIdentities.move")}} function enables items to be moved in the list of contextual identities. This function enables extensions to customize the order in which contextual identities display in the UI ([Firefox bug 1333395](https://bugzil.la/1333395)). + ### Removals ### Other