recursal/MDN huggingface dataset:
bookmarks.getSubTree()
======================

The **`bookmarks.getSubTree()`** method asynchronously retrieves a `bookmarks.BookmarkTreeNode`, given its ID.

If the item is a folder, you can access all its descendants recursively using its `children` property and the `children` property of its descendants, if they are themselves folders.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingSubTree = browser.bookmarks.getSubTree(
  id                     // string
)
```

### Parameters

`id`

A `string` specifying the ID of the root of the subtree to retrieve.

### Return value

A `Promise` that is fulfilled with an array containing an object, a `bookmarks.BookmarkTreeNode` object, representing the item with the given ID.

If a node corresponding to `id` could not be found, the promise will be rejected with an error message.

Examples
--------

This example recursively prints out the subtree under a given node:


```js
function makeIndent(indentLength) {
  return ".".repeat(indentLength);
}

function logItems(bookmarkItem, indent) {
  if (bookmarkItem.url) {
    console.log(makeIndent(indent) + bookmarkItem.url);
  } else {
    console.log(`${makeIndent(indent)}Folder: ${bookmarkItem.id}`);
    indent++;
  }
  if (bookmarkItem.children) {
    for (const child of bookmarkItem.children) {
      logItems(child, indent);
    }
  }
}

function logSubTree(bookmarkItems) {
  logItems(bookmarkItems[0], 0);
}

function onRejected(error) {
  console.log(`An error: ${error}`);
}

let subTreeID = "root\_\_\_\_\_";

browser.bookmarks.getSubTree(subTreeID).then(logSubTree, onRejected);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.json` in the Chromium code.
bookmarks.onMoved
=================

Fired when a bookmark or folder is moved to a different parent folder or position within a folder.

**Note:** If you're moving multiple bookmarks, because this API is asynchronous, the move calls may get processed in any order. Consequently, the value of each bookmark's index may change or be unknown until all the move calls are completed. If the index associated with a bookmark matters to your extension, then – when moving multiple bookmarks – the extension should wait for each `bookmarks.move` call to complete before moving the next bookmark. Waiting ensures that the index associated with each bookmark is not affected by a move call executing concurrently while the original call is in progress.

Syntax
------


```js
browser.bookmarks.onMoved.addListener(listener)
browser.bookmarks.onMoved.removeListener(listener)
browser.bookmarks.onMoved.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`id`

`string`. ID of the item that was moved.

`moveInfo`

`object`. Object containing more details about the move. See the moveInfo section for more details.


Additional objects
------------------

### moveInfo

`parentId`

`string`. The new parent folder.

`index`

`integer`. The new index of this item in its parent.

`oldParentId`

`string`. The old parent folder.

`oldIndex`

`integer`. The old index of the item in its parent.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function handleMoved(id, moveInfo) {
  console.log(`Item: ${id} moved`);
  console.log(`Old index: ${moveInfo.oldIndex}`);
  console.log(`New index: ${moveInfo.index}`);
  console.log(`Old folder: ${moveInfo.oldParentId}`);
  console.log(`New folder: ${moveInfo.parentId}`);
}

function handleClick() {
  browser.bookmarks.onMoved.addListener(handleMoved);
}

browser.browserAction.onClicked.addListener(handleClick);
```


**Note:** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.json` in the Chromium code.
bookmarks.remove()
==================

The **`bookmarks.remove()`** method removes a single bookmark or an empty bookmark folder.

**Warning:** If your extension attempts to remove a bookmark from the bookmarks tree root node, the call will raise an error with the message: "The bookmark root cannot be modified" and the bookmark won't be removed.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let removingBookmark = browser.bookmarks.remove(
  id                 // string
)
```

### Parameters

`id`

A `string` specifying the ID of the bookmark or empty folder to remove.

### Return value

A `Promise` that will be fulfilled with no arguments.

If the node corresponding to the `id` parameter can't be found or was a non-empty folder, the promise is rejected with an error message.

Examples
--------


```js
function onRemoved() {
  console.log("Removed!");
}

function onRejected(error) {
  console.log(`An error: ${error}`);
}

let bookmarkId = "abcdefghijkl";

let removingBookmark = browser.bookmarks.remove(bookmarkId);
removingBookmark.then(onRemoved, onRejected);
```

### Example extensions

* bookmark-it
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.json` in the Chromium code.
bookmarks.getChildren()
=======================

**`bookmarks.getChildren()`** retrieves all the immediate children of a bookmark folder, identified as a `BookmarkTreeNode` ID.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingChildren = browser.bookmarks.getChildren(
  id                     // string
)
```

### Parameters

`id`

A `string` that specifies the ID of the folder whose children are to be retrieved.

### Return value

A `Promise` that is fulfilled with an array of `BookmarkTreeNode` objects. Each entry represents a child node. The list is in the same order as the bookmarks appear in the user interface. Separators are included in the results. The list includes subfolders but does not include any children contained in subfolders.

If the specified node has no children, the array is empty.

If the node identified by `id` is not found, the promise is rejected with an error message.

Examples
--------


```js
function onFulfilled(children) {
  for (child of children) {
    console.log(child.id);
  }
}

function onRejected(error) {
  console.log(`An error: ${error}`);
}

let gettingChildren = browser.bookmarks.getChildren("unfiled\_\_\_\_\_");
gettingChildren.then(onFulfilled, onRejected);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.json` in the Chromium code.
bookmarks.BookmarkTreeNode
==========================

An object of type `bookmarks.BookmarkTreeNode` represents a node in the bookmark tree, where each node is a bookmark, a bookmark folder, or a separator. Child nodes are ordered by an `index` within their respective parent folders.

Type
----

An `object` with the following properties:

`children` Optional

An `array` of `bookmarks.BookmarkTreeNode` objects which represent the node's children. The list is ordered in the list in which the children appear in the user interface. This field is omitted if the node isn't a folder.

`dateAdded` Optional

A number representing the creation date of the node in milliseconds since the epoch.

`dateGroupModified` Optional

A number representing the date and time the contents of this folder last changed, in milliseconds since the epoch.

`id`

A `string` which uniquely identifies the node. Each ID is unique within the user's profile and remains unchanged across browser restarts.

`index` Optional

A number which represents the zero-based position of this node within its parent folder, where zero represents the first entry.

**Note:** If you create or move multiple bookmarks, because the `bookmarks.create()` and `bookmarks.move()` methods are asynchronous, the requests may get processed in any order. Consequently, the value of each bookmark's index may change or be unknown until all the requests are completed. If the index associated with a bookmark matters to your extension, then – when creating or moving multiple bookmarks – the extension should wait for each `bookmarks.create` or `bookmarks.move` call to complete before creating or moving the next bookmark. Waiting ensures that the index associated with each bookmark is not affected by a create or move call executing concurrently while the original call is in progress.

`parentId` Optional

A `string` which specifies the ID of the parent folder. This property is not present in the root node.

`title`

A `string` which contains the text displayed for the node in menus and lists of bookmarks.

`type` Optional

A `bookmarks.BookmarkTreeNodeType` object indicating whether this is a bookmark, a folder, or a separator. Defaults to `"bookmark"` unless `url` is omitted, in which case it defaults to `"folder"`.

`unmodifiable` Optional

A `string` as described by the type `bookmarks.BookmarkTreeNodeUnmodifiable`. Represents the reason that the node can't be changed. If the node can be changed, this is omitted.

`url` Optional

A `string` which represents the URL for the bookmark. If the node represents a folder, this property is omitted.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.json` in the Chromium code.
bookmarks.create()
==================

Creates a bookmark or folder as a child of the `BookmarkTreeNode` with the specified `parentId`. To create a folder, omit or leave empty the `CreateDetails.url` parameter.

**Warning:** If your extension tries to create a new bookmark in the bookmark tree's root node, it raises an error: "*The bookmark root cannot be modified*" and the bookmark won't be created.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let createBookmark = browser.bookmarks.create(
  bookmark                  // CreateDetails object
)
```

### Parameters

`bookmark`

A `bookmarks.CreateDetails` object.

### Return value

A `Promise` that will be fulfilled with a `BookmarkTreeNode` that describes the new bookmark node.

**Note:** If you create multiple bookmarks, because this API is asynchronous, the create calls may get processed in any order. Consequently, the value of each bookmark's index returned in `BookmarkTreeNode` may change or be unknown until all the create calls are completed. If the index associated with a bookmark matters to your extension, then – when creating multiple bookmarks – the extension should wait for each `bookmarks.create` call to complete before creating the next bookmark. Waiting ensures that the index associated with each bookmark is not affected by a create call executing concurrently while the original call is in progress.

Examples
--------

This example creates a bookmark for this page, placing it in the default folder ("Other Bookmarks" in Firefox and Chrome).


```js
function onCreated(node) {
  console.log(node);
}

let createBookmark = browser.bookmarks.create({
  title: "bookmarks.create() on MDN",
  url: "https://developer.mozilla.org/Add-ons/WebExtensions/API/bookmarks/create",
});

createBookmark.then(onCreated);
```

### Example extensions

* bookmark-it
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.json` in the Chromium code.
bookmarks.get()
===============

Given the ID of a `bookmarks.BookmarkTreeNode` or an array of such IDs, the **`bookmarks.get()`** method retrieves the matching nodes.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let getBookmarks = browser.bookmarks.get(
  idOrIdList                // string or string array
)
```

### Parameters

`idOrIdList`

`string` A `string` or `array` of strings specifying the IDs of one or more `BookmarkTreeNode` objects to retrieve.

### Return value

A `Promise` that will be fulfilled with an array of `BookmarkTreeNode`, one for each matching node. Separators are not included in the results. If no nodes could be found, the promise will be rejected with an error message.

Examples
--------

This example tries to get the bookmark whose ID is `bookmarkAAAA`. If no bookmark with this ID exists, `onRejected` is called:


```js
function onFulfilled(bookmarks) {
  console.log(bookmarks);
}

function onRejected(error) {
  console.log(`An error: ${error}`);
}

let gettingBookmarks = browser.bookmarks.get("bookmarkAAAA");
gettingBookmarks.then(onFulfilled, onRejected);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.json` in the Chromium code.
bookmarks.onChanged
===================

Fired when there is a change to:

* the title or URL of a bookmark
* the name of a folder.
Syntax
------


```js
browser.bookmarks.onChanged.addListener(listener)
browser.bookmarks.onChanged.removeListener(listener)
browser.bookmarks.onChanged.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`id`

`string`. ID of the item that changed.

`changeInfo`

`object`. Object containing two properties: `title`, a string containing the item's title, and `url`, a string containing the item's URL. If the item is a folder, `url` is omitted.


**Note:** Multiple events may occur when a bookmark changes, and that changeInfo object may contain only the data that has changed, rather than all the data for the bookmark. In other words, if the `url` for a bookmark changes, the changeInfo may only contain the new `url` information.

Examples
--------


```js
function handleChanged(id, changeInfo) {
  console.log(`Item: ${id} changed`);
  console.log(`Title: ${changeInfo.title}`);
  console.log(`Url: ${changeInfo.url}`);
}

function handleClick() {
  browser.bookmarks.onChanged.addListener(handleChanged);
}

browser.browserAction.onClicked.addListener(handleClick);
```

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.json` in the Chromium code.
bookmarks.onChildrenReordered
=============================

Fired when the children of a folder have changed their order due to the order being sorted in the UI. This is not called as a result of a call to `bookmarks.move()` or a drag operation in the UI.

Syntax
------


```js
browser.bookmarks.onChildrenReordered.addListener(listener)
browser.bookmarks.onChildrenReordered.removeListener(listener)
browser.bookmarks.onChildrenReordered.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed these arguments:

`id`

`string`. ID of the folder whose children were reordered.

`reorderInfo`

`object`. Object containing Additional objects. See the reorderInfo section for more details.


Additional objects
------------------

### reorderInfo

`childIds`

`array` of `string`. Array containing the IDs of all the bookmark items in this folder, in the order they now appear in the UI.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function handleChildrenReordered(id, reorderInfo) {
  console.log(`Item: ${id} children reordered`);
  console.log(`Children: ${reorderInfo.childIds}`);
}

function handleClick() {
  browser.bookmarks.onChildrenReordered.addListener(handleChildrenReordered);
}

browser.browserAction.onClicked.addListener(handleClick);
```


**Note:** This API is based on Chromium's `chrome.bookmarks` API. This documentation is derived from `bookmarks.json` in the Chromium code.
idle.IdleState
==============

String describing the device's idle state.

Type
----

Values of this type are strings. Possible values are: `"active"`, `"idle"`, `"locked"`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.idle` API. This documentation is derived from `idle.json` in the Chromium code.
idle.queryState()
=================

Returns `"locked"` if the system is locked, `"idle"` if the user has not generated any input for a specified number of seconds, or `"active"` otherwise.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let querying = browser.idle.queryState(
  detectionIntervalInSeconds // integer
)
```

### Parameters

`detectionIntervalInSeconds`

`integer`. The system is considered idle if `detectionIntervalInSeconds` seconds have elapsed since the last user input detected.

### Return value

A `Promise` that will be fulfilled with an `idle.IdleState` string, indicating the current state.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

In this simple snippet, we call `queryState()` and then check if the returned `newState` is `idle` or `active`, logging a message as appropriate. Because we have specified a `detectionIntervalInSeconds` of 15, an `idle` state will only be reported if there has been no user activity for at least 15 seconds


```js
function onGot(newState) {
  if (newState === "idle") {
    console.log("Please come back — we miss you!");
  } else if (newState === "active") {
    console.log("Glad to still have you with us!");
  }
}

let querying = browser.idle.queryState(15);
querying.then(onGot);
```


**Note:** This API is based on Chromium's `chrome.idle` API. This documentation is derived from `idle.json` in the Chromium code.
idle.setDetectionInterval()
===========================

Sets the interval, in seconds, used to determine when the system is in an idle state for `idle.onStateChanged` events. The default interval is 60 seconds.

The detection interval is specific to the extension that calls the method. Changing the interval in one extension will not affect the detection interval in another extension.

Syntax
------


```js
browser.idle.setDetectionInterval(
  intervalInSeconds // integer
)
```

### Parameters

`intervalInSeconds`

`integer`. Threshold, in seconds, used to determine when the system is in an idle state. The minimum value you can supply here is 15.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
browser.idle.setDetectionInterval(15);
```


**Note:** This API is based on Chromium's `chrome.idle` API. This documentation is derived from `idle.json` in the Chromium code.
idle.onStateChanged
===================

Fired when the system changes to an active, idle or locked state. The event listener is passed a string that has one of three values:

* "locked" if the screen is locked or the screensaver activates
* "idle" if the system is unlocked and the user has not generated any input for a specified number of seconds. This number defaults to 60, but can be set using `idle.setDetectionInterval()`.
* "active" when the user generates input on an idle system.
Syntax
------


```js
browser.idle.onStateChanged.addListener(listener)
browser.idle.onStateChanged.removeListener(listener)
browser.idle.onStateChanged.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`newState`

`idle.IdleState`. The new idle state.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function newState(state) {
  console.log(`New state: ${state}`);
}

browser.idle.onStateChanged.addListener(newState);
```


**Note:** This API is based on Chromium's `chrome.idle` API. This documentation is derived from `idle.json` in the Chromium code.
webNavigation.onTabReplaced
===========================

Fired when the contents of the tab is replaced by a different (usually previously pre-rendered) tab.

Syntax
------


```js
browser.webNavigation.onTabReplaced.addListener(
  listener,                   // function
  filter                      // optional object
);
browser.webNavigation.onTabReplaced.removeListener(listener)
browser.webNavigation.onTabReplaced.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. The function is passed this argument:

`details`

`object`. See the details section for more information.


Additional objects
------------------

### details

`replacedTabId`

`integer`. The ID of the tab that was replaced.

`tabId`

`integer`. The ID of the tab that replaced the old tab.

`timeStamp`

`number`. The time when the replacement happened, in milliseconds since the epoch.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function logOnTabReplaced(details) {
  console.log(`onTabReplaced ${details}`);
}

browser.webNavigation.onTabReplaced.addListener(logOnTabReplaced);
```


**Note:** This API is based on Chromium's `chrome.webNavigation` API. This documentation is derived from `web_navigation.json` in the Chromium code.