recursal/MDN huggingface dataset:
sidebarAction.setPanel()
========================

Sets the sidebar's panel: that is, the HTML document that defines the content of this sidebar.

Types of panel
--------------

Sidebars always have a *"manifest panel"*, which is the panel defined in the `sidebar_action` manifest key.

If you set a new panel using `setPanel()`, and include the `tabId` option, then the panel is set only for the given tab. This panel is referred to as the *"tab-specific panel"*.

If you set a new panel using `setPanel()`, and include the `windowId` option, then the panel is set only for the given window. This panel is referred to as the *"window-specific panel"*, and will appear in all tabs of that window that do not have a tab-specific panel set.

If you set a new panel using `setPanel()`, and omit both the `tabId` and `windowId` options, then this sets the *"global panel"*. The global panel will then appear in all tabs that do not have a tab-specific panel set and whose window does not have a window-specific panel.

Syntax
------


```js
browser.sidebarAction.setPanel(
  details // object
)
```

### Parameters

`details`

`object`. An object with the following properties:

`panel`

`string` or `null`. The panel to load into the sidebar, specified as a URL pointing to an HTML document, or `null`, or an empty string.

This can point to a file packaged within the extension (for example, created using `runtime.getURL`), or a remote document (e.g. `https://example.org/`). It must be a valid URL.

If `panel` is `null` or `""`, then a previously set panel will be removed, so that:

* If `tabId` is specified, and the tab has a tab-specific panel set, then the tab will inherit the panel from the window it belongs to.
* If `windowId` is specified, and the window has a window-specific panel set, then the window will inherit the global panel.
* Otherwise, the global panel will be reset to the manifest panel.

`tabId` Optional

`integer`. Sets the panel only for the given tab.

`windowId` Optional

`integer`. Sets the panel only for the given window.



* If `windowId` and `tabId` are both specified, the function fails and the panel is not set.
* If `windowId` and `tabId` are both omitted, the global panel is set.
Examples
--------

This code toggles the sidebar document when the user clicks a browser action:


```js
let thisPanel = browser.runtime.getURL("/this.html");
let thatPanel = browser.runtime.getURL("/that.html");

function toggle(panel) {
  if (panel === thisPanel) {
    browser.sidebarAction.setPanel({ panel: thatPanel });
  } else {
    browser.sidebarAction.setPanel({ panel: thisPanel });
  }
}

browser.browserAction.onClicked.addListener(() => {
  browser.sidebarAction.getPanel({}).then(toggle);
});
```

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

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

**Note:** This API is based on Opera's `chrome.sidebarAction` API.
sidebarAction.open()
====================

Open the sidebar in the active window.

You can only call this function from inside the handler for a user action.

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

Syntax
------


```js
browser.sidebarAction.open()
```

### Parameters

None.

### Return value

A `Promise` that is resolved with no arguments.

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

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

Examples
--------

Open the sidebar when the user selects a context menu item:


```js
browser.menus.create({
  id: "open-sidebar",
  title: "open sidebar",
  contexts: ["all"],
});

browser.menus.onClicked.addListener(() => {
  browser.sidebarAction.open();
});
```
sidebarAction.ImageDataType
===========================

Pixel data for an image. Must be an `ImageData` object (for example, from a `<canvas>` element).

Type
----

An `ImageData` object.

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

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

**Note:** This API is based on Opera's `chrome.sidebarAction` API.
bookmarks.removeTree()
======================

The **`bookmarks.removeTree()`** method recursively removes a bookmark folder and all of its contents.

**Warning:** If your extension attempts to remove a bookmark tree 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 removingTree = browser.bookmarks.removeTree(
  id                // string
)
```

### Parameters

`id`

A `string` specifying the ID of the folder node to be deleted along with its descendants.

### Return value

A `Promise` that will be fulfilled with no arguments when the tree has been removed.

If the node corresponding to the `id` parameter can't be found, the promise is rejected with an error message.

Examples
--------

This example locates a bookmark folder named "MDN" and deletes it along with all of its contents.


```js
function onRemoved() {
  console.log("bookmark item removed!");
}

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

function removeMDN(searchResults) {
  if (searchResults.length) {
    let removing = browser.bookmarks.removeTree(searchResults[0].id);
    removing.then(onRemoved, onRejected);
  }
}

let searchingBookmarks = browser.bookmarks.search({ title: "MDN" });
searchingBookmarks.then(removeMDN, 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.onImportBegan
=======================

Fired when the browser has started importing a set of bookmarks.

While a set of bookmarks is being imported, `onCreated` may fire a lot of times. If your extension is listening to `onCreated`, and the listener is expensive, you should also listen for `onImportBegan` and `onImportEnded`. When you receive `onImportBegan`, ignore `onCreated` until you receive `onImportEnded`. You can handle all other notifications as usual.

Syntax
------


```js
browser.bookmarks.onImportBegan.addListener(listener)
browser.bookmarks.onImportBegan.removeListener(listener)
browser.bookmarks.onImportBegan.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. It's passed no parameters.

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

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

Examples
--------


```js
function handleImportBegan() {
  console.log("Importing…");
}

function handleImportEnded() {
  console.log("Import finished.");
}

function handleClick() {
  browser.bookmarks.onImportBegan.addListener(handleImportBegan);
  browser.bookmarks.onImportEnded.addListener(handleImportEnded);
}

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.getRecent()
=====================

The `bookmarks.getRecent()` method retrieves a specified number of the most recently added bookmarks as an array of `BookmarkTreeNode` objects.

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

Syntax
------


```js
let gettingRecent = browser.bookmarks.getRecent(
  numberOfItems          // integer
)
```

### Parameters

`numberOfItems`

A number representing the maximum number of items to return. The returned list will contain up to this many of the most recently added items. The minimum allowed value here is 1. If you pass 0 or less, the function will throw an error.

### Return value

A `Promise` that will be fulfilled with an array of `BookmarkTreeNode` objects.

Examples
--------

This example logs the URL for the most recently added bookmark:


```js
function onFulfilled(bookmarks) {
  for (const bookmark of bookmarks) {
    console.log(bookmark.url);
  }
}

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

browser.bookmarks.getRecent(1).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.onCreated
===================

Fired when a bookmark item (a bookmark or a folder) is created.

Syntax
------


```js
browser.bookmarks.onCreated.addListener(listener)
browser.bookmarks.onCreated.removeListener(listener)
browser.bookmarks.onCreated.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`. The new bookmark item's ID.

`bookmark`

`bookmarks.BookmarkTreeNode`. Information about the new bookmark item.


Examples
--------


```js
function handleCreated(id, bookmarkInfo) {
  console.log(`New bookmark ID: ${id}`);
  console.log(`New bookmark URL: ${bookmarkInfo.url}`);
}

browser.bookmarks.onCreated.addListener(handleCreated);
```

### 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.onImportEnded
=======================

Fired when the browser has finished importing a set of bookmarks.

See `bookmarks.onImportBegan`.

Syntax
------


```js
browser.bookmarks.onImportEnded.addListener(listener)
browser.bookmarks.onImportEnded.removeListener(listener)
browser.bookmarks.onImportEnded.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. It's passed no parameters.

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

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

Examples
--------


```js
function handleImportBegan() {
  console.log("Importing…");
}

function handleImportEnded() {
  console.log("Import finished.");
}

function handleClick() {
  browser.bookmarks.onImportBegan.addListener(handleImportBegan);
  browser.bookmarks.onImportEnded.addListener(handleImportEnded);
}

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.CreateDetails
=======================

The `CreateDetails` type is used to describe the properties of a new, bookmark, bookmark folder, or separator when calling the `bookmarks.create()` method.

Type
----

An `object` containing some combination of the following fields:

`index` Optional

An integer `Number` which specifies the position at which to place the new bookmark under its parent. A value of 0 will put it at the top of the list.

`parentId` Optional

A `string` which indicates the ID of the parent folder into which to place the new bookmark or bookmark folder. On Chrome and Firefox, the default is the "Other Bookmarks" folder on the Bookmarks menu.

`title` Optional

A `string` which specifies the title for the bookmark or the name of the folder to be created. If this isn't specified, the title is `""`.

`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"`.

`url` Optional

`string`. A `string` which specifies the URL of the page to bookmark. If this is omitted or is `null`, a folder is created instead of a bookmark.

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.BookmarkTreeNodeUnmodifiable
======================================

The **`bookmarks.BookmarkTreeNodeUnmodifiable`** type is used to indicate the reason that a node in the bookmark tree (where each node is either a bookmark or a bookmark folder) cannot be changed. This is used as the value of the `bookmarks.BookmarkTreeNode.unmodifiable.unmodifiable` field on bookmark nodes.

Type
----

`bookmarks.BookmarkTreeNodeUnmodifiable` is a `string` which can currently have only one value: `"managed"`. This indicates that the bookmark node was configured by an administrator or by the custodian of a supervised user (such as a parent, in the case of parental controls).

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.move()
================

The **`bookmarks.move()`** method moves the specified `BookmarkTreeNode` to the specified destination within the tree of bookmarks. This lets you move a bookmark to a new folder and/or position within the folder.

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

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

Syntax
------


```js
let movingBookmark = browser.bookmarks.move(
  id,                    // string
  destination           // object
)
```

### Parameters

`id`

A `string` containing the ID of the bookmark or folder to move.

`destination`

An `object` which specifies the destination for the bookmark. This object must contain one or both of the following fields:

`parentId` Optional

A `string` which specifies the ID of the destination folder. If this value is left out, the bookmark is moved to a new location within its current folder.

`index` Optional

A 0-based index specifying the position within the folder to which to move the bookmark. A value of 0 moves the bookmark to the top of the folder. If this value is omitted, the bookmark is placed at the end of the new parent folder.


### Return value

A `Promise` that will be fulfilled with a single `bookmarks.BookmarkTreeNode` object, describing the moved node.

If the node corresponding to the `id` parameter can't be found, the promise is rejected with an error message.

**Note:** If you move multiple bookmarks, because this API is asynchronous, the move 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 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.

Examples
--------

This example moves a bookmark so that it's the first bookmark in its current folder.


```js
function onMoved(bookmarkItem) {
  console.log(bookmarkItem.index);
}

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

let bookmarkId = "abcdefghijkl";

let movingBookmark = browser.bookmarks.move(bookmarkId, { index: 0 });
movingBookmark.then(onMoved, 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.BookmarkTreeNodeType
==============================

The **`bookmarks.BookmarkTreeNodeType`** type is used to describe whether a node in the bookmark tree is a bookmark, a folder, or a separator.

Type
----

`bookmarks.BookmarkTreeNodeType` is a `string` which can have one of the following three values:

* `"bookmark"`: the node is a bookmark.
* `"folder"`: the node is a folder.
* `"separator"`: the node is a separator.
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.
bookmarks.getTree()
===================

**`bookmarks.getTree()`** returns an array containing the root of the bookmarks tree as a `bookmarks.BookmarkTreeNode` object.

You can access the entire tree 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 gettingTree = browser.bookmarks.getTree()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an array containing one object, a `bookmarks.BookmarkTreeNode` object representing the root node.

Examples
--------

This example prints out the entire bookmarks tree:


```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`);
    indent++;
  }
  if (bookmarkItem.children) {
    for (const child of bookmarkItem.children) {
      logItems(child, indent);
    }
  }
  indent--;
}

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

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

let gettingTree = browser.bookmarks.getTree();
gettingTree.then(logTree, 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.onRemoved
===================

Fired when a bookmark or folder is removed. When a folder is removed recursively, a single notification is fired for the folder, and none for its contents.

Syntax
------


```js
browser.bookmarks.onRemoved.addListener(listener)
browser.bookmarks.onRemoved.removeListener(listener)
browser.bookmarks.onRemoved.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 removed.

`removeInfo`

`object`. More details about the removed item. See the removeInfo section for more details.


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

### removeInfo

`parentId`

`string`. ID of the item's parent in the tree.

`index`

`integer`. Zero-based index position of this item in its parent.

`node`

`bookmarks.BookmarkTreeNode`. Detailed information about the item that was removed.

Examples
--------


```js
function handleRemoved(id, removeInfo) {
  console.log(`Item: ${id} removed`);
  console.log(`Title: ${removeInfo.node.title}`);
  console.log(`Url: ${removeInfo.node.url}`);
}

function handleClick() {
  browser.bookmarks.onRemoved.addListener(handleRemoved);
}

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

### 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.update()
==================

**`bookmarks.update()`** updates the title and/or URL of a bookmark, or the name of a bookmark folder.

**Warning:** If your extension attempts to update a bookmark in 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 updated.

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

Syntax
------


```js
let updating = browser.bookmarks.update(
  id,                    // string
  changes                // object
)
```

### Parameters

`id`

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

`changes`

An `object` specifying the changes to apply, with some combination of the following fields. Any items not specified aren't changed in the referenced bookmark or folder:

`title` Optional

A `string` containing the new title of the bookmark, or the new name of the folder if `id` refers to a folder.

`url` Optional

A `string` providing a new URL for the bookmark.


### Return value

A `Promise` that will be fulfilled with a single `bookmarks.BookmarkTreeNode` object, representing the updated bookmark. If the bookmark item corresponding to the `id` parameter can't be found, the promise is rejected.

Examples
--------

This example renames all folders named "MDN" to "Mozilla Developer Network (MDN)".


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

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

function updateFolders(items) {
  for (const item of items) {
    // only folders, so skip items with a `url`
    if (!item.url) {
      browser.bookmarks
        .update(item.id, {
          title: "Mozilla Developer Network (MDN)",
        })
        .then(onFulfilled, onRejected);
    }
  }
}

browser.bookmarks.search({ title: "MDN" }).then(updateFolders, 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.