Skip to content

Commit

Permalink
browser.tab.onUpdated.addListener clarifications & edits (mdn#20774)
Browse files Browse the repository at this point in the history
  • Loading branch information
@rebloor
rebloor committed Sep 22, 2022
1 parent 6b4bbc0 commit fc88cd9
Showing 1 changed file with 20 additions and 28 deletions.
48 changes: 20 additions & 28 deletions files/en-us/mozilla/add-ons/webextensions/api/tabs/onupdated/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,11 @@ browser-compat: webextensions.api.tabs.onUpdated

Fired when a tab is updated.

When the user navigates to a new URL in a tab, this will typically generate several `onUpdated` events as various properties of the {{WebExtAPIRef("tabs.Tab")}} object are updated. This includes the `url`, but also potentially the `title` and `favIconUrl` properties. The `status` property will cycle through `"loading"` and `"complete"`.
When the user navigates to a new URL in a tab, this typically generates several `onUpdated` events as various properties of the {{WebExtAPIRef("tabs.Tab")}} object are updated. This includes the `url`, but also potentially the `title` and `favIconUrl` properties. The `status` property will cycle through `"loading"` and `"complete"`.

This event will also be fired for changes to a tab's properties that don't involve navigation, like pinning and unpinning (which updates the `pinned` property) and muting or unmuting (which updates the `audible` and `mutedInfo` properties).
This event also fires for changes to a tab's properties that don't involve navigation, such as pinning and unpinning (which updates the `pinned` property) and muting or unmuting (which updates the `audible` and `mutedInfo` properties).

You can filter this event, making it only fire for tabs whose URLs match specific [patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns), or for changes to specific properties, or for changes to a specific tab or window, or any combinations of these restrictions.
You can filter this event, making it only fire for tabs whose URLs match specific [patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns), changes to particular properties, changes to a tab or window, or any combinations of these restrictions.

## Syntax

Expand All @@ -45,24 +45,24 @@ Events have three functions:

- `callback`

- : Function that will be called when this event occurs. The function will be passed the following arguments:
- : The function called when this event occurs. The function is passed these arguments:

- `tabId`
- : `integer`. ID of the tab that was updated.
- : `integer`. The ID of the updated tab.
- `changeInfo`
- : [`object`](#changeinfo). Contains properties for the tab properties that have changed. See [`changeInfo`](#changeinfo_2) below.
- : [`object`](#changeinfo). Properties of the tab that changed. See [`changeInfo`](#changeinfo_2) below.
- `tab`
- : {{WebExtAPIRef('tabs.Tab')}}. The new state of the tab.

- `extraParameters` {{optional_inline}}

- : `object`. A set of filters that restricts the events that will be sent to this listener. This is an object which may have one or more of the following properties. Events will only be sent if they satisfy all the filters given.
- : `object`. A set of filters that restrict the events sent to this listener. This object can have one or more of these properties. Events are only sent if they satisfy all the filters provided.

- `urls`
- : `Array`. An array of [match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns). Fire the event only for tabs whose current `url` property matches any one of the patterns.
- : `Array`. An array of [match patterns](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns). Fires the event only for tabs whose current `url` property matches any one of the patterns.
- `properties`

- : `Array`. An array of strings, which are the names of properties of the {{WebExtAPIRef("tabs.Tab")}} object. Fire this event only for changes to one of the properties named in this array. The following properties may be listed here:
- : `Array`. An array of strings consisting of supported {{WebExtAPIRef("tabs.Tab")}} object property names. Fires the event only for changes to one of the properties named in the array. These properties can be used:

- "attention"
- "audible"
Expand All @@ -72,32 +72,31 @@ Events have three functions:
- "isArticle"
- "mutedInfo"
- "pinned"
- "sharingState"
- "status"
- "title"
- "url"

> **Note:** The "url" value is supported since Firefox 88. In Firefox 87 and earlier, "url" changes can be observed by filtering by "status".
> **Note:** The "url" value has been supported since Firefox 88. In Firefox 87 and earlier, "url" changes can be observed by filtering by "status".
- `tabId`
- : `Integer`. Fire this event only for the tab identified by this ID.
- : `Integer`. Fires this event only for the tab identified by this ID.
- `windowId`
- : `Integer`. Fire this event only for tabs which are currently in the window identified by this ID.
- : `Integer`. Fires this event only for tabs in the window identified by this ID.

## Additional objects

### changeInfo

Lists the changes to the state of the tab that was updated. To learn more about these properties, see the {{WebExtAPIRef("tabs.Tab")}} documentation.
Lists the changes to the state of the tab that is updated. To learn more about these properties, see the {{WebExtAPIRef("tabs.Tab")}} documentation. Note that not all {{WebExtAPIRef("tabs.Tab")}} properties are supported.

- `attention` {{optional_inline}}
- : `boolean`. Indicates whether the tab is drawing attention. For example, when the tab displays a modal dialog, `attention` will be `true`.
- : `boolean`. Indicates whether the tab is drawing attention. For example, `attention` is `true` when the tab displays a modal dialog.
- `audible` {{optional_inline}}
- : `boolean`. The tab's new audible state.
- `discarded` {{optional_inline}}
- : `boolean`. Whether the tab is discarded. A discarded tab is one whose content has been unloaded from memory, but is still visible in the tab strip. Its content gets reloaded the next time it's activated.
- : `boolean`. Whether the tab is discarded. A discarded tab is one whose content has been unloaded from memory but is visible in the tab strip. Its content gets reloaded the next time it's activated.
- `favIconUrl` {{optional_inline}}
- : `string`. The tab's new favicon URL. Not included when a tab loses its favicon (navigating from a page with a favicon to a page that without one), please check `favIconUrl` in [tab](#tab) instead.
- : `string`. The tab's new favicon URL. Not included when a tab loses its favicon (navigating from a page with a favicon to a page without one). Check `favIconUrl` in [tab](#tab) instead.
- `hidden` {{optional_inline}}
- : `boolean`. True if the tab is {{WebExtAPIRef("tabs.hide()", "hidden")}}.
- `isArticle` {{optional_inline}}
Expand All @@ -111,7 +110,7 @@ Lists the changes to the state of the tab that was updated. To learn more about
- `title` {{optional_inline}}
- : `string`. The tab's new title.
- `url` {{optional_inline}}
- : `string`. The tab's URL if it has changed.
- : `string`. The tab's URL, if it has changed.

## Examples

Expand Down Expand Up @@ -160,7 +159,7 @@ function handleUpdated(tabId, changeInfo, tabInfo) {
browser.tabs.onUpdated.addListener(handleUpdated, filter);
```

Log changes only to the `pinned` property of tabs (i.e. pin and unpin actions):
Log changes only to the `pinned` property of tabs (that is, pin and unpin actions):

```js
const filter = {
Expand All @@ -176,10 +175,7 @@ function handleUpdated(tabId, changeInfo, tabInfo) {
browser.tabs.onUpdated.addListener(handleUpdated, filter);
```

Combine both the previous filters: log changes only:

- to the `pinned` property of tabs
- whose `url` property is [matched](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) by `https://developer.mozilla.org/*` or `https://twitter.com/mozdevnet`:
Combine both the previous filters, log only when the `pinned` property of tabs changes for tabs whose `url` property is [matched](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) by `https://developer.mozilla.org/*` or `https://twitter.com/mozdevnet`:

```js
const pattern1 = "https://developer.mozilla.org/*";
Expand All @@ -201,11 +197,7 @@ browser.tabs.onUpdated.addListener(
filter);
```

Log changes only:

- to the `pinned` property of tabs
- whose `url` property is [matched](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) by `https://developer.mozilla.org/*` or `https://twitter.com/mozdevnet`
- and which are part of the current browser window at the time the update event is fired:
Log changes only when the `pinned` property of tabs changes for tabs whose `url` property is [matched](/en-US/docs/Mozilla/Add-ons/WebExtensions/Match_patterns) by `https://developer.mozilla.org/*` or `https://twitter.com/mozdevnet` where the tab was part of the current browser window when the update event fired:

```js
const pattern1 = "https://developer.mozilla.org/*";
Expand Down

0 comments on commit fc88cd9

Please sign in to comment.