Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

onChanged callback object content clarification #31227

Merged
merged 8 commits into from
Mar 4, 2024
Merged

onChanged callback object content clarification #31227

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
033a77c
onChanged callback object content clarification
rebloor Dec 22, 2023
21b00a0
Revert "onChanged callback object content clarification"
rebloor Dec 23, 2023
4912001
Revised change
rebloor Dec 23, 2023
3a210a5
Further clarification and bug information
rebloor Dec 25, 2023
8b255a7
Apply suggestions from review
rebloor Mar 1, 2024
7f7e0b8
Merge branch 'main' into onChanged-object-content-clarification
rebloor Mar 1, 2024
cc2beb7
Apply suggestions from review
rebloor Mar 4, 2024
e3933a6
Merge branch 'main' into onChanged-object-content-clarification
rebloor Mar 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions files/en-us/mozilla/add-ons/webextensions/api/storage/onchanged/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ browser-compat: webextensions.api.storage.onChanged

{{AddonSidebar}}

Fired when {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}}, {{WebExtAPIRef('storage.StorageArea.remove','storageArea.remove')}}, or {{WebExtAPIRef('storage.StorageArea.clear','storageArea.clear')}} executes against a storage area.
Fired when {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}}, {{WebExtAPIRef('storage.StorageArea.remove','storageArea.remove')}}, or {{WebExtAPIRef('storage.StorageArea.clear','storageArea.clear')}} executes against a storage area, returning details of the changed keys. A callback is called only when there are changes to the underlying data.
rebloor marked this conversation as resolved.
Show resolved Hide resolved

When this event is triggered by {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}}, it's possible to receive a callback when there is no change to the underlying data. Also, the information returned includes all keys within the storage area {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}} ran against. The extension can determine the changes that occurred by examining the content of the `changes` argument received by the `onChanged` listeners.
> **Note:** In Firefox, the information returned includes all keys within the storage area {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}} ran against. Also, a callback may be invoked when there is no change to the underlying data. Details of the changed items are found by examining each returned key's {{WebExtAPIRef('storage.StorageChange')}} object. See [Firefox bug 1833153](https://bugzil.la/1833153).
rebloor marked this conversation as resolved.
Show resolved Hide resolved

## Syntax

Expand Down Expand Up @@ -37,7 +37,7 @@ Events have three functions:
- : The function called when this event occurs. The function is passed these arguments:

- `changes`
- : `object`. Object describing the change. This object contains properties for all the keys in the storage area included in the {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}} call, even if key values are unchanged. The name of each property is the name of each key. The value of each key is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.
- : `object`. Object describing the change. The name of each property is the name of each key. The value of each key is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.
- `areaName`
- : `string`. The name of the storage area (`"sync"`, `"local"`, or `"managed"`) to which the changes were made.

Expand Down
6 changes: 4 additions & 2 deletions .../en-us/mozilla/add-ons/webextensions/api/storage/storagearea/onchanged/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ browser-compat: webextensions.api.storage.StorageArea.onChanged

{{AddonSidebar}}

Fires when one or more items in a storage area change. Compared to {{WebExtAPIRef("storage.onChanged")}}, this event enables you to listen for changes in one of the storage areas: `local`, `managed`, `session`, and `sync`.
Fires when one or more items in a storage area change, returning details for the keys that changed. Compared to {{WebExtAPIRef("storage.onChanged")}}, this event enables you to listen for changes in one of the storage areas: `local`, `managed`, `session`, and `sync`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, Firefox can pass changes for multiple areas, but everyone else only does one at a time? Do I understand this correctly?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jpmedley, as I understand it, the difference is that Firefox returns all the keys from the storage area, whereas other browsers only return the changed ones only.


> **Note:** In Firefox, the information returned includes all keys within the storage area. Also, the callback may be invoked when there is no change to the underlying data. Details of the changed items are found by examining each returned key's {{WebExtAPIRef('storage.StorageChange')}} object. See [Firefox bug 1833153](https://bugzil.la/1833153).

## Syntax

Expand Down Expand Up @@ -36,7 +38,7 @@ Events have three functions:
- : The function called when this event occurs. The function is passed this argument:

- `changes`
- : `object`. Object describing the change. This contains one property for each key that changed. The name of the property is the name of the key that changed, and its value is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.
- : `object`. Object describing the change. This contains one property for each key that changed. The property name is the name of the key that changed, and its value is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.

## Examples

Expand Down
Loading