recursal/MDN huggingface dataset:
extensionTypes.RunAt
====================

The soonest that the JavaScript or CSS will be injected into the tab.

Type
----

Values of this type are strings. Possible values are: `"document_start"`, `"document_end"`, `"document_idle"`.

* `"document_start"`: corresponds to `loading`. The DOM is still loading.
* `"document_end"`: corresponds to `interactive`. The DOM has finished loading, but resources such as scripts and images may still be loading.
* `"document_idle"`: corresponds to `complete`. The document and all its resources have finished loading.

The default value is `"document_idle"`.

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.extensionTypes` API. This documentation is derived from `extension_types.json` in the Chromium code.
extensionTypes.InjectDetails
============================

This type is given as a parameter to the `tabs.executeScript()`, `tabs.insertCSS()`, and `tabs.removeCSS()` methods. For the details of its properties and what they are used for, see the documentation pages for those methods:

* `tabs.executeScript()`
* `tabs.insertCSS()`
* `tabs.removeCSS()`
contentScripts.RegisteredContentScript
======================================

A `RegisteredContentScript` is returned by a call to `contentScripts.register()` and represents the content scripts registered in that call.

It defines a single function `unregister()`, which can be used to unregister the content scripts.

**Note:** If this object is destroyed (for example because it goes out of scope) then the content scripts will be unregistered automatically, so you should keep a reference to this object for as long as you want the content scripts to stay registered.

Methods
-------

`unregister()`

Unregisters the content scripts represented by this object.

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

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

Examples
--------

This code toggles a registered content script on a browser action click:


```js
let registered = null;

async function register() {
  registered = await browser.contentScripts.register({
    matches: ["\*://\*.org/\*"],
    js: [
      {
        code: "document.body.innerHTML = '<h1>This page has been eaten<h1>'",
      },
    ],
    runAt: "document\_idle",
  });
}

function toggle() {
  if (registered) {
    registered.unregister();
    registered = null;
  } else {
    register();
  }
}

browser.browserAction.onClicked.addListener(toggle);
```
contentScripts.RegisteredContentScript.unregister()
===================================================

Unregisters the content scripts represented by this `RegisteredContentScript` object.

Syntax
------


```js
registered.unregister()
```

### Parameters

None.

### Return value

None.

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

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

Examples
--------

This code toggles a registered content script on a browser action click:


```js
let registered = null;

async function register() {
  registered = await browser.contentScripts.register({
    matches: ["\*://\*.org/\*"],
    js: [
      {
        code: "document.body.innerHTML = '<h1>This page has been eaten<h1>'",
      },
    ],
    runAt: "document\_idle",
  });
}

function toggle() {
  if (registered) {
    registered.unregister();
    registered = null;
  } else {
    register();
  }
}

browser.browserAction.onClicked.addListener(toggle);
```
notifications.clear()
=====================

Clears a notification, given its ID.

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

Syntax
------


```js
let clearing = browser.notifications.clear(
  id                            // string
)
```

### Parameters

`id`

`string`. The ID of the notification to clear. This is the same as the ID passed into `notifications.create()`'s callback.

### Return value

A `Promise` that will be fulfilled with a boolean: `true` if the notification was cleared, or `false` if it was not (for example, because the notification referenced by `id` did not exist).

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

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

Examples
--------

This example shows a notification when the user clicks a browser action, unless the notification was already being shown, in which case it clears the notification:


```js
let myNotification = "my-notification";

function toggleAlarm(all) {
  if (myNotification in all) {
    browser.notifications.clear(myNotification);
  } else {
    browser.notifications.create(myNotification, {
      type: "basic",
      iconUrl: browser.runtime.getURL("icons/cake-48.png"),
      title: "Am imposing title",
      message: "Some interesting content",
    });
  }
}

function handleClick() {
  let gettingAll = browser.notifications.getAll();
  gettingAll.then(toggleAlarm);
}

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


**Note:** This API is based on Chromium's `chrome.notifications` API.
notifications.onClosed
======================

Fired when a notification is closed, either by the system or by the user.

Syntax
------


```js
browser.notifications.onClosed.addListener(listener)
browser.notifications.onClosed.removeListener(listener)
browser.notifications.onClosed.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:

`notificationId`

`string`. ID of the notification that closed.

`byUser`

`boolean`. `true` if the notification was closed by the user, or `false` if it was closed by the system. This argument is not supported in Firefox.


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

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

Examples
--------

In this simple example we add a listener to the `notifications.onClosed` event to listen for system notifications being closed. When this occurs, we log an appropriate message to the console.


```js
browser.notifications.onClosed.addListener((notificationId) => {
  console.log(`Notification ${notificationId} has closed.`);
});
```


**Note:** This API is based on Chromium's `chrome.notifications` API.
notifications.update()
======================

Updates a notification, given its ID.

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

Syntax
------


```js
let updating = browser.notifications.update(
  id,                            // string
  options                        // NotificationOptions
)
```

### Parameters

`id`

`string`. The ID of the notification to update. This is the same as the ID passed into `notifications.create()`'s callback.

`options`

`notifications.NotificationOptions`. Defines the notification's new content and behavior.

### Return value

A `Promise` that will be fulfilled with a boolean: `true` if the notification was updated, or `false` if it was not (for example, because the notification referenced by `id` did not exist).

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

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

Examples
--------

This example uses `update()` to update a progress notification. Clicking the browser action shows the notification and starts an `alarm`, which we use to update the notification's progress indicator.

Note that you'll need the "alarms" permission to create alarms (as well as the "notifications" permission to create notifications). Also note that Firefox does not support the `progress` attribute.


```js
let cakeNotification = "cake-notification";

/\*

CAKE\_INTERVAL is set to 0.3 seconds in this example.
Such a short period is chosen to make the extension's behavior
more obvious, but this is not recommended in real life.
Note that in Chrome, alarms cannot be set for less than
a minute.

\*/
let CAKE\_PREP\_INTERVAL = 0.005;

let progress = 0;

browser.alarms.onAlarm.addListener((alarm) => {
  progress += 10;
  if (progress > 100) {
    browser.notifications.clear(cakeNotification);
    browser.alarms.clear("cake-progress");
  } else {
    browser.notifications.update(cakeNotification, { progress });
  }
});

browser.browserAction.onClicked.addListener(() => {
  browser.notifications.getAll((all) => {
    if (all.length > 0) {
      browser.notifications.clear(cakeNotification);
      return;
    }
    progress = 0;
    browser.notifications.create(cakeNotification, {
      type: "progress",
      iconUrl: browser.extension.getURL("icons/cake-48.png"),
      title: "Your cake is being prepared…",
      message: "Something something cake",
      progress,
    });
    browser.alarms.create("cake-progress", {
      periodInMinutes: CAKE\_PREP\_INTERVAL,
    });
  });
});
```


**Note:** This API is based on Chromium's `chrome.notifications` API.
notifications.onButtonClicked
=============================

Fired when the user clicks one of the notification's buttons.

Syntax
------


```js
browser.notifications.onButtonClicked.addListener(listener)
browser.notifications.onButtonClicked.removeListener(listener)
browser.notifications.onButtonClicked.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:

`notificationId`

`string`. ID of the notification whose button was clicked.

`buttonIndex`

`integer`. The zero-based index of the button that was clicked.


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.notifications` API.
notifications.create()
======================

Creates and displays a notification.

Pass a `notifications.NotificationOptions` to define the notification's content and behavior.

You can optionally provide an ID for the notification. If you omit the ID, an ID will be generated. You can use the ID to `update` or `clear` the notification.

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

**Warning:** If you call `notifications.create()` more than once in rapid succession, Firefox may end up not displaying any notification at all.

Syntax
------


```js
let creating = browser.notifications.create(
  id,                   // optional string
  options               // NotificationOptions
)
```

### Parameters

`id` Optional

`string`. This is used to refer to this notification in `notifications.update()`, `notifications.clear()`, and event listeners. If you omit this argument or pass an empty string, then a new ID will be generated for this notification. If the ID you provide matches the ID of an existing notification from this extension, then the other notification will be cleared.

`options`

`notifications.NotificationOptions`. Defines the notification's content and behavior.

### Return value

A `Promise` that will be fulfilled when the notification is created and the display process has been started, which is before the notification is actually displayed to the user. It is fulfilled with a string representing the notification's ID.

Examples
--------

This example displays a notification periodically, using `alarm`. Clicking the browser action dismisses the notification. You need the "alarms" permission to create alarms (as well as the "notifications" permission to create notifications).


```js
let cakeNotification = "cake-notification";

/\*

CAKE\_INTERVAL is set to 6 seconds in this example.
Such a short period is chosen to make the extension's behavior
more obvious, but this is not recommended in real life.
Note that in Chrome, alarms cannot be set for less
than a minute.

\*/
let CAKE\_INTERVAL = 0.1;

browser.alarms.create("", { periodInMinutes: CAKE\_INTERVAL });

browser.alarms.onAlarm.addListener((alarm) => {
  browser.notifications.create(cakeNotification, {
    type: "basic",
    iconUrl: browser.runtime.getURL("icons/cake-96.png"),
    title: "Time for cake!",
    message: "Something something cake",
  });
});

browser.browserAction.onClicked.addListener(() => {
  const clearing = browser.notifications.clear(cakeNotification);
  clearing.then(() => {
    console.log("cleared");
  });
});
```

### Example extensions

* export-helpers
* forget-it
* google-userinfo
* notify-link-clicks-i18n
* runtime-examples
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.notifications` API.
notifications.onClicked
=======================

Fired when the user clicks a notification, but not on any of the notification's buttons (for that, see `notifications.onButtonClicked`).

Syntax
------


```js
browser.notifications.onClicked.addListener(listener)
browser.notifications.onClicked.removeListener(listener)
browser.notifications.onClicked.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:

`notificationId`

`string`. ID of the notification that the user clicked.


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

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

Examples
--------

In this simple example we add a listener to the `notifications.onClicked` event to listen for system notifications being clicked. When this occurs, we log an appropriate message to the console.


```js
browser.notifications.onClicked.addListener((notificationId) => {
  console.log(`Notification ${notificationId} was clicked by the user`);
});
```


**Note:** This API is based on Chromium's `chrome.notifications` API.
notifications.TemplateType
==========================

This is a string, and represents the type of notification to create. There are four types of notification: "basic", "image", "list", "progress".

This is passed into `notifications.create()` and `notifications.update()` as the `type` property of `NotificationOptions`.

Type
----

Values of this type are strings. Possible values are:

* `"basic"`: the notification includes:
    + a title (`NotificationOptions.title`)
    + a message (`NotificationOptions.message`)
    + an icon (`NotificationOptions.iconUrl`) Optional
    + an extra message (`NotificationOptions.contextMessage`) Optional
    + up to two buttons (`NotificationOptions.buttons`) Optional
* `"image"`: everything in `"basic"` and also:
    + an image (`NotificationOptions.imageUrl`)
* `"list"`: everything in `"basic"` and also:
    + a list of items (`NotificationOptions.items`)
* `"progress"`: everything in `"basic"` and also:
    + a progress indicator (`NotificationOptions.progress`)

Currently Firefox only supports "basic" here.

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.notifications` API.
notifications.getAll()
======================

Gets all currently active notifications created by the extension.

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

Syntax
------


```js
let gettingAll = browser.notifications.getAll()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with an object. Each currently active notification is a property of this object: the name of the property is the ID of the notification, and the value of the property is a `notifications.NotificationOptions` object describing that notification.

Note that you can define an ID for a notification explicitly by passing it into `notifications.create()`. If you don't do this, the browser will generate one. Explicitly-specified IDs are strings, but generated IDs are numbers.

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

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

Examples
--------

This example shows a notification when the user clicks a browser action, unless the notification was already being shown, in which case it clears the notification. It uses getAll() to figure out whether the notification is being shown:


```js
const myNotification = "my-notification";

function toggleAlarm(all) {
  const ids = Object.keys(all);
  if (ids.includes(myNotification)) {
    browser.notifications.clear(myNotification);
  } else {
    console.log("showing");

    browser.notifications.create(myNotification, {
      type: "basic",
      title: "Am imposing title",
      message: "Some interesting content",
    });
  }
}

function handleClick() {
  console.log("clicked");
  browser.notifications.getAll().then(toggleAlarm);
}

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


This example logs the title of all active notifications:


```js
function logNotifications(all) {
  for (const id in all) {
    console.log(`Title: ${all[id].title}`);
  }
}

browser.notifications.getAll().then(logNotifications);
```


**Note:** This API is based on Chromium's `chrome.notifications` API.
notifications.onShown
=====================

Fired immediately after a notification has been shown.

Syntax
------


```js
browser.notifications.onShown.addListener(listener)
browser.notifications.onShown.removeListener(listener)
browser.notifications.onShown.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:

`notificationId`

`string`. ID of the notification that has been shown.


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

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

Examples
--------

Add a listener to the `notifications.onShown` event and log its details:


```js
function logShown(itemId) {
  console.log(`shown: ${itemId}`);
  browser.notifications.getAll().then((all) => {
    console.log(all[itemId]);
  });
}

browser.notifications.onShown.addListener(logShown);
```


**Note:** This API is based on Chromium's `chrome.notifications` API.
devtools.panels
===============

**Note:** Although the APIs are based on the Chrome devtools APIs, there are still many features that are not yet implemented in Firefox, and therefore are not documented here. To see which features are currently missing please see Limitations of the devtools APIs.

The `devtools.panels` API lets a devtools extension define its user interface inside the devtools window.

The devtools window hosts a number of separate tools - the JavaScript Debugger, Network Monitor, and so on. A row of tabs across the top lets the user switch between the different tools. The window hosting each tool's user interface is called a "panel".

With the `devtools.panels` API you can create new panels in the devtools window.

Like all the `devtools` APIs, this API is only available to code running in the document defined in the devtools\_page manifest.json key, or in other devtools documents created by the extension (such as the panel's own document). See Extending the developer tools for more.

Types
-----

`devtools.panels.ElementsPanel`

Represents the HTML/CSS inspector in the browser's devtools.

`devtools.panels.ExtensionPanel`

Represents a devtools panel created by the extension.

`devtools.panels.ExtensionSidebarPane`

Represents a pane that an extension has added to the HTML/CSS inspector in the browser's devtools.

Properties
----------

`devtools.panels.elements`

A reference to an `ElementsPanel` object.

`devtools.panels.themeName`

The name of the current devtools theme.

Functions
---------

`devtools.panels.create()`

Creates a new devtools panel.

Events
------

`devtools.panels.onThemeChanged`

Fired when the devtools theme changes.

Example extensions
------------------

* devtools-panels
Browser compatibility
---------------------

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

Example extensions
------------------

* devtools-panels

**Note:** This API is based on Chromium's `chrome.devtools.panels` API.
devtools.inspectedWindow
========================

**Note:** This page describes the WebExtensions devtools APIs as they exist in Firefox 54. Although the APIs are based on the Chrome devtools APIs, there are still many features that are not yet implemented in Firefox, and therefore are not documented here. To see which features are currently missing please see Limitations of the devtools APIs.

The `devtools.inspectedWindow` API lets a devtools extension interact with the window that the developer tools are attached to.

Like all the `devtools` APIs, this API is only available to code running in the document defined in the devtools\_page manifest.json key, or in other devtools documents created by the extension (such as the document hosted by a panel the extension created). See Extending the developer tools for more.

Properties
----------

`devtools.inspectedWindow.tabId`

The ID of the window that the developer tools are attached to.

Functions
---------

`devtools.inspectedWindow.eval()`

Evaluate some JavaScript in the target window.

`devtools.inspectedWindow.reload()`

Reload the target window's document.

Example extensions
------------------

* devtools-panels
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.devtools.inspectedWindow` API.
devtools.network
================

The `devtools.network` API lets a devtools extension get information about network requests associated with the window that the devtools are attached to (the inspected window).

Like all the `devtools` APIs, this API is only available to code running in the document defined in the devtools\_page manifest.json key, or in other devtools documents created by the extension (such as the panel's own document). See Extending the developer tools for more.

Functions
---------

`devtools.network.getHAR()`

Get a HAR log for the page loaded in the current tab.

Events
------

`devtools.network.onNavigated`

Fired when the user navigates the inspected window to a new page.

`devtools.network.onRequestFinished`

Fired when the network request has finished and its details are available to the extension.

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.devtools.network` API.