From 78fb968f6353b71f7af97e154456443ce96eab38 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Thu, 31 Oct 2024 14:36:27 +1300 Subject: [PATCH 1/3] Note re exception from storage.managed.get --- .../api/storage/storagearea/get/index.md | 20 ++++++++----------- 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md index fc15cc8ca26d1be..de92aea8f41b7d5 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md @@ -28,22 +28,14 @@ Where `` is one of the storage types — {{WebExtAPIRef("storage.sy ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to a `results` object, containing every object in `keys` that was found in the storage area. If `keys` is an object, keys that are not found in the storage area will have their values given by the `keys` object. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to a `results` object, containing every object in `keys` found in the storage area. If `keys` is an object, keys that are not found in the storage area have their values given by the `keys` object. -If the operation failed, the promise is rejected with an error message. +If the operation fails, the promise is rejected with an error message. -If managed storage is not set, `undefined` will be returned. +If managed storage is not set, `undefined` is returned. > [!WARNING] -> When used within a content script in Firefox versions prior to 52, the Promise returned by `browser.storage.local.get()` is fulfilled with an Array containing one Object. The Object in the Array contains the `keys` found in the storage area, as described above. -> -> The Promise is correctly fulfilled with an Object when used in the background context (background scripts, popups, options pages, etc.). -> -> When this API is used as `chrome.storage.local.get()`, it correctly passes an Object to the callback function. - -## Browser compatibility - -{{Compat}} +> In Firefox, if the managed storage manifest is missing, an exception is thrown when using this function to access managed storage (see [Firefox bug 1868153](https://bugzil.la/1868153)). This issue can be avoided by catching the error. This issue is related to the lack of support for the [`storage.managed_schema`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/storage) manifest key (see [Firefox bug 1771731](https://bugzil.la/1771731)). `storage.managed_schema` provides a fallback managed storage manifest definition on other browsers. ## Examples @@ -145,5 +137,9 @@ let gettingItem = new Promise((resolve) => gettingItem.then(onGot); // -> Object { kitten: Object } ``` +## Browser compatibility + +{{Compat}} + > [!NOTE] > This API is based on Chromium's [`chrome.storage`](https://developer.chrome.com/docs/extensions/reference/api/storage) API. This documentation is derived from [`storage.json`](https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/storage.json) in the Chromium code. From 13c067c1831702e59c9193aa6cba363de1cd82e1 Mon Sep 17 00:00:00 2001 From: rebloor Date: Fri, 1 Nov 2024 15:09:00 +1300 Subject: [PATCH 2/3] Apply suggestions from review Co-authored-by: Simeon Vincent --- .../webextensions/api/storage/storagearea/get/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md index de92aea8f41b7d5..ad41080eb3d5a42 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md @@ -28,14 +28,14 @@ Where `` is one of the storage types — {{WebExtAPIRef("storage.sy ### Return value -A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to a `results` object, containing every object in `keys` found in the storage area. If `keys` is an object, keys that are not found in the storage area have their values given by the `keys` object. +A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that resolves to a `results` object, containing a key-value pair for every key in `keys` found in the storage area. When `keys` is an object, any key that isn't found in storage takes the default value from the `keys` object. If the operation fails, the promise is rejected with an error message. If managed storage is not set, `undefined` is returned. > [!WARNING] -> In Firefox, if the managed storage manifest is missing, an exception is thrown when using this function to access managed storage (see [Firefox bug 1868153](https://bugzil.la/1868153)). This issue can be avoided by catching the error. This issue is related to the lack of support for the [`storage.managed_schema`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/storage) manifest key (see [Firefox bug 1771731](https://bugzil.la/1771731)). `storage.managed_schema` provides a fallback managed storage manifest definition on other browsers. +> In Firefox, if an extension's managed storage has not been configured with a native manifest or using the [`3rdparty` enterprise policy](https://mozilla.github.io/policy-templates/#3rdparty), an exception is thrown when using this function to access managed storage (see [Firefox bug 1868153](https://bugzil.la/1868153)). This issue can be avoided by catching the error. This issue is related to the lack of support for the [`storage.managed_schema`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/storage) manifest key (see [Firefox bug 1771731](https://bugzil.la/1771731)). ## Examples From af8cb028c656463f215c4fbf88f31c6c75984b69 Mon Sep 17 00:00:00 2001 From: Richard Bloor Date: Fri, 1 Nov 2024 15:46:17 +1300 Subject: [PATCH 3/3] Feedback related updates --- .../add-ons/webextensions/api/storage/managed/index.md | 4 ++-- .../webextensions/api/storage/storagearea/get/index.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/managed/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/managed/index.md index f3bd3d3c083355b..6ec199fa2f64efa 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/managed/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/managed/index.md @@ -13,9 +13,9 @@ A {{WebExtAPIRef("storage.StorageArea")}} object that represents the `managed` s The procedure for provisioning managed storage varies between browsers. For Chrome instructions, see the ["Manifest for storage areas"](https://developer.chrome.com/docs/extensions/reference/manifest/storage) article. -For Firefox, you need to create a JSON manifest file in a specific format and location. For the details of manifest syntax and location, see [Native manifests](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests). +For Firefox, you need to create a [JSON manifest (native manifest) file in a specific format and location](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#managed_storage_manifests) or use the [`3rdparty` enterprise policy](https://mozilla.github.io/policy-templates/#3rdparty). -Here's an example manifest: +Here's an example native manifest: ```json { diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md index ad41080eb3d5a42..b85486d55dd8d34 100644 --- a/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md +++ b/files/en-us/mozilla/add-ons/webextensions/api/storage/storagearea/get/index.md @@ -35,7 +35,7 @@ If the operation fails, the promise is rejected with an error message. If managed storage is not set, `undefined` is returned. > [!WARNING] -> In Firefox, if an extension's managed storage has not been configured with a native manifest or using the [`3rdparty` enterprise policy](https://mozilla.github.io/policy-templates/#3rdparty), an exception is thrown when using this function to access managed storage (see [Firefox bug 1868153](https://bugzil.la/1868153)). This issue can be avoided by catching the error. This issue is related to the lack of support for the [`storage.managed_schema`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/storage) manifest key (see [Firefox bug 1771731](https://bugzil.la/1771731)). +> In Firefox, if an extension's managed storage has not been configured with a [native manifest](/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_manifests#managed_storage_manifests) or using the [`3rdparty` enterprise policy](https://mozilla.github.io/policy-templates/#3rdparty), an exception is thrown when using this function to access managed storage (see [Firefox bug 1868153](https://bugzil.la/1868153)). This issue can be avoided by catching the error. This issue is related to the lack of support for the [`storage.managed_schema`](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/storage) manifest key (see [Firefox bug 1771731](https://bugzil.la/1771731)). ## Examples