recursal/MDN huggingface dataset:
Notifications
=============

Notifications allow you to communicate information about your extension or its content using the underlying operating system's notification service.

![Click notification in the top right corner of the browser window.](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Notifications/notify-shadowed.png)

Notifications can include a call to action for the user, and your add-on can listen for the user clicking the notification or the notification closing.

Specifying notifications
------------------------

You manage notifications programmatically, using the `notifications` API. To use this API you must request the `notifications` permission in your manifest.json:


```json
"permissions": ["notifications"]
```


You then use `notifications.create` to create your notifications, as in this example from notify-link-clicks-i18n:


```js
const title = browser.i18n.getMessage("notificationTitle");
const content = browser.i18n.getMessage("notificationContent", message.url);
browser.notifications.create({
  type: "basic",
  iconUrl: browser.extension.getURL("icons/link-48.png"),
  title,
  message: content,
});
```


This code creates a notification with an icon, title, and message.

If the notification includes a call to action, you can listen for the user clicking the notification to call the function to handle the action:


```js
browser.notifications.onClicked.addListener(handleClick);
```


If you are issuing calls to action through notifications, you will also want to define the optional notification `id`, so you can figure out which call to action the user has selected.

Icons
-----

For details on how to create icons to use with your notification, see Iconography in the Acorn Design System documentation.

Examples
--------

The webextensions-examples repository on GitHub includes the notify-link-clicks-i18n example which implements notifications.
devtools panels
===============

**Note:** This feature is available since Firefox 54.

When an extension provides tools that are of use to developers, it's possible to add a UI for them to the browser's developer tools as a new panel.

![Simple example showing the addition of "My panel" to the Developer Tools tabs.](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/devtools_panels/developer_panel_tab.png)

Specifying a developer tools panel
----------------------------------

A developer tools panel is added using the `devtools.panels` API, which in turn needs to be run from a special devtools page.

Add the devtools page by including the `devtools_page` key in extension's manifest.json and provide the location of the page's HTML file in the extension:


```json
"devtools\_page": "devtools-page.html"
```


From the devtools page, call a script that will add the devtools panel:


```html
<body>
  <script src="devtools.js"></script>
</body>
```


In the script, create the devtools panel by specifying the panel's title, icon, and HTML file that provides the panel's content:


```js
function handleShown() {
  console.log("panel is being shown");
}

function handleHidden() {
  console.log("panel is being hidden");
}

browser.devtools.panels
  .create(
    "My Panel", // title
    "icons/star.png", // icon
    "devtools/panel/panel.html", // content
  )
  .then((newPanel) => {
    newPanel.onShown.addListener(handleShown);
    newPanel.onHidden.addListener(handleHidden);
  });
```


The extension can now run code in the inspected window using `devtools.inspectedWindow.eval()` or by injecting a content script via the background script by passing a message. You can find more details on how to do this in Extending the developer tools.

Developer panel design
----------------------

For details on how to design your developer panel's web page to match the style of Firefox, see the Acorn Design System documentation.

Icons
-----

For details on how to create icons to use with your developer tools panel, see Iconography in the Acorn Design System documentation.

Examples
--------

The webextensions-examples repository on GitHub includes the devtools-panels example which implements a devtools panel.
Extension pages
===============

You can include HTML pages in your extension to provide forms, help, or any other content your extension needs.

![Example of a simple bundled page displayed as a detached panel.](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Extension_pages/bundled_page_as_panel_small.png)

These pages also get access to the same privileged JavaScript APIs that are available to your extension's background scripts. However, they are in their own tab, with their own JavaScript event queue, their own globals, etc.

Think of the background page as a "hidden extension page".

Specifying extension pages
--------------------------

You can include HTML files—and associated CSS or JavaScript files—in your extension. The files can be included in the root or organized within meaningful sub-folders.
```

/my-extension
    /manifest.json
    /my-page.html
    /my-page.js
```

Displaying extension pages
--------------------------

There are two options for displaying extension pages: `windows.create()` and `tabs.create()`.

Using `windows.create()`, for example, you can open an HTML page into a detached panel (a window without the normal browser UI of address bar, bookmark bar, and alike) to create a dialog-like user experience:


```js
let createData = {
  type: "detached\_panel",
  url: "my-page.html",
  width: 250,
  height: 100,
};
let creating = browser.windows.create(createData);
```


When the window is no longer needed, it can be closed programmatically.

For example, after the user clicks a button, you may pass the current window's id to `windows.remove()`:


```js
document.getElementById("closeme").addEventListener("click", () => {
  let winId = browser.windows.WINDOW\_ID\_CURRENT;
  let removing = browser.windows.remove(winId);
});
```

Extension pages and history
---------------------------

By default, pages you open in this way will be stored in the user's history, just like normal web pages. If you don't want to have this behavior, use `history.deleteUrl()` to remove the browser's record:


```js
function onVisited(historyItem) {
  if (historyItem.url === browser.extension.getURL(myPage)) {
    browser.history.deleteUrl({ url: historyItem.url });
  }
}

browser.history.onVisited.addListener(onVisited);
```


To use the history API, you must request the "`history`" permission in your `manifest.json` file.

Web page design
---------------

For details on how to design your web page's to match the style of Firefox, see the Acorn Design System.

Examples
--------

The webextensions-examples repository on GitHub includes the window-manipulator example, which implements several of the options for creating windows.
Options page
============

An Options page enables you to define preferences for your extension that your users can change. Users can access the options page for an extension from the browser's add-ons manager:

The way users access the page, and the way it's integrated into the browser's user interface, will vary from one browser to another.

You can open the page programmatically by calling `runtime.openOptionsPage()`.

Options pages have a Content Security Policy that restricts the sources from which they can load resources, and disallows some unsafe practices such as the use of `eval()`. See Content Security Policy for more details.

Specifying the options page
---------------------------

To create an options page, write an HTML file defining the page. This page can include CSS and JavaScript files, like a normal web page. This page, from the favourite-color example, includes a JavaScript file:


```html
<!doctype html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
  </head>

  <body>
    <form>
      <label for="color">Favorite color</label>
      <input type="text" id="color" name="color" />
      <button type="submit">Save</button>
    </form>
    <script src="options.js"></script>
  </body>
</html>
```


JavaScript running in the page can use all the WebExtension APIs that the add-on has permissions for. In particular, you can use the `storage` API to persist preferences.

Package the page's files in your extension.

You also need to include the `options_ui` key in your manifest.json file, giving it the URL to the page.


```json
"options\_ui": {
  "page": "options.html"
},
```


See the `options_ui` page for **sharing options** between your options page and background or content scripts.

Options content design
----------------------

For details on how to design your options content to match the style of Firefox, see the Acorn Design System.

Examples
--------

The webextensions-examples repository on GitHub includes the favourite-color example which implements options page features.
Address bar suggestions
=======================

Using the `omnibox` API, extensions can customize the suggestions offered in the browser address bar's drop-down when the user enters a keyword.

![Example showing the result of the firefox_code_search WebExtension's customization of the address bar suggestions.](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Omnibox/omnibox_example_small.png)

This enables your extension to, for example, search a library of free ebooks or, as in the example above, a repository of code examples.

Specifying the omnibox customization
------------------------------------

You tell your extension that it is going to customize the address bar suggestions by including the omnibox key and definition of the trigger keyword in its manifest.json file:


```json
  "omnibox": { "keyword" : "cs" }
```


In the extension's background JavaScript file, using `omnibox.setDefaultSuggestion()`, you can optionally define the first suggestion to be displayed in the address bar drop-down. Use this to provide a hint on how to use the feature:


```js
browser.omnibox.setDefaultSuggestion({
  description: `Search the Firefox codebase
 (e.g. "hello world" | "path:omnibox.js onInputChanged")`,
});
```


You can then add the code to provide the customized content by listening for `omnibox.onInputStarted`, which is dispatched when the user has typed the keyword and a space, and `omnibox.onInputChanged`, which is dispatched whenever the user updates the address bar entry. You can then populate the suggestions, in this case building a search of mozilla-central using the term entered by the user:


```js
browser.omnibox.onInputChanged.addListener((text, addSuggestions) => {
  let headers = new Headers({ Accept: "application/json" });
  let init = { method: "GET", headers };
  let url = buildSearchURL(text);
  let request = new Request(url, init);

  fetch(request).then(createSuggestionsFromResponse).then(addSuggestions);
});
```


If the extension set a default suggestion using `omnibox.setDefaultSuggestion()`, then this will appear first in the drop-down.

The extension can then listen for the user clicking one of the suggestions, using `omnibox.onInputEntered`. If the default suggestion is clicked the user's custom term is returned, otherwise the suggestion's string is returned. This also passes information on the user's browser preferences for handling new links. In the code below the user's custom term is used to create a search, otherwise the suggested URL is opened:


```js
browser.omnibox.onInputEntered.addListener((text, disposition) => {
  let url = text;
  if (!text.startsWith(SOURCE\_URL)) {
    // Update the URL if the user clicks on the default suggestion.
    url = `${SEARCH\_URL}?q=${text}`;
  }
  switch (disposition) {
    case "currentTab":
      browser.tabs.update({ url });
      break;
    case "newForegroundTab":
      browser.tabs.create({ url });
      break;
    case "newBackgroundTab":
      browser.tabs.create({ url, active: false });
      break;
  }
});
```

Examples
--------

The webextensions-examples repository on GitHub includes the firefox-code-search example which customizes the search bar.
Toolbar button
==============

 Commonly referred to as a browser action, this user interface option is a button added to the browser toolbar. Users click the button to interact with your extension.

 ![A custom browser action icon it the browser tool bar that looks like paw print.](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Toolbar_button/toolbar_button.png)

The toolbar button (browser action) is very like the address bar button (page action). For the differences, and guidance on when to use what, see Page actions and browser actions.

Specifying the browser action
-----------------------------

You define the browser action's properties using the `"browser_action"` key in manifest.json:


```json
"browser\_action": {
  "default\_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  },
  "default\_title": "Whereami?"
}
```


There are no mandatory properties for this key. If you don't specify `"default_icon"` the extension icon is used, and the default web extension puzzle pace icon is used if the extension doesn't specify an icon. If `"default_title"` isn't specified, the extension name is used.

There are two ways to specify a browser action: with or without a popup. If you don't specify a popup, when the user clicks the button an event is dispatched to the extension, which the extension listens for using `browserAction.onClicked`:


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


If you specify a popup, the click event is not dispatched: instead, the popup is shown when the user clicks the button. The user can interact with the popup, which closes automatically when the user clicks outside it. See the Popup article for more details on creating and managing popups.

Note that your extension can have only one browser action.

You can change many of the browser action properties programmatically using the `browserAction` API.

Icons
-----

For details on how to create icons to use with your browser action, see Iconography in the Acorn Design System documentation.

Examples
--------

The `webextensions-examples` repository on GitHub contains two examples of extensions that implement browser actions:

* bookmark-it uses a browser action without a popup
* beastify uses a browser action with a popup
Address bar button
==================

Commonly referred to as a page action button, this user interface option is a button added to the browser address bar. Users click the button to interact with extensions.

![Page action button is an icon of a dog paw print](/en-US/docs/Mozilla/Add-ons/WebExtensions/user_interface/Page_actions/address_bar_button.png)

Page actions and browser actions
--------------------------------

The address bar button (or page action) is similar to the toolbar button (or browser action).

The differences are:

* **The button's location:**
    + The page action is displayed inside the browser address bar.
    + The browser action is displayed outside the address bar, in the browser toolbar.
* **The button's visibility:**
    + The page action is hidden by default (although this default can be changed via the `show_matches` and `hide_matches` manifest key properties), and you call `pageAction.show()` and `pageAction.hide()` to show or hide it in specific tabs.
    + The browser action is always displayed.

Use a page action when the action relates to the current page. Use a browser action when the action relates to the browser as a whole or to many pages. For example:

| Type | Bookmarks action | Content action | Tabs operation |
| --- | --- | --- | --- |
| page action | Bookmark this page | Reddit enhancement | Send tab |
| browser action | Show all bookmarks | Enable ad-blocking | Sync all open tabs |

Specifying the page action
--------------------------

You define the page action's properties using the `page_action` key in manifest.json:


```json
"page\_action": {
  "default\_icon": {
    "19": "button/geo-19.png",
    "38": "button/geo-38.png"
  },
  "default\_title": "Whereami?"
}
```


The only mandatory key is `default_icon`.

There are two ways to specify a page action: with or without a popup.

* **Without a popup:** When the user clicks the button, an event is dispatched to the extension, which the extension listens for using `pageAction.onClicked`:

```js
browser.pageAction.onClicked.addListener(handleClick);
```

* **With a popup:** the `click` event is not dispatched. Instead, the popup appears when the user clicks the button. The user then interacts with the popup. When the user clicks outside of the popup, it closes automatically. See the Popup article for more details on creating and managing popups.

Note that your extension can have just one page action.

You can change any of the page action properties programmatically using the `pageAction` API.

Icons
-----

For details on how to create icons to use with your page action, see Iconography in the Acorn Design System documentation.

Examples
--------

The webextensions-examples repository on GitHub includes the chill-out example which implements a page action without a popup.
WebAssembly instruction reference
=================================

* `Numeric instructions`
* `Vector/SIMD instructions`
* `Reference instructions`
* `Variable instructions`
* `Table instructions`
* `Memory instructions`
* `Control flow instructions`
WebAssembly control flow instructions
=====================================

WebAssembly control flow instructions.

`block`

Creates a label that can later be branched out of with a `br`.

`br`

Branches to a loop or block.

`call`

Calls a function.

`drop`

Pops a value from the stack, and discards it.

`end`

Can be used to end a `block`, `loop`, `if`, or `else`.

`if...else`

Executes a statement if the last item on the stack is true (`1`).

`loop`

Creates a label that can later be branched to with a `br`.

`nop`

Does nothing.

`return`

Returns from a function.

`select`

Selects one of its first two operands based on a boolean condition.

`unreachable`

Denotes a point in code that should not be reachable.
WebAssembly variable instructions
=================================

WebAssembly variable instructions.

`Declare local`

Declare a new local variable.

`Get local`

Load the value of a local variable onto the stack.

`Set local`

Set the value of a local variable.

`Tee local`

Set the value of a local variable and keep the value on the stack.

`Declare global`

Declare a new global variable.

`Get global`

Load the value of a global variable onto the stack.

`Set global`

Set the value of a global variable.
WebAssembly memory instructions
===============================

WebAssembly memory instructions.

`Grow`

Increase the size of the memory instance.

`Size`

Get the size of the memory instance.

`Load`

Load a number from memory.

`Store`

Store a number in memory.
WebAssembly numeric instructions
================================

WebAssembly numeric instructions.

Constants
---------

`Const`

Declare a constant numbers.

Comparison
----------

`Equal`

Check if two numbers are equal.

`Not equal`

Check if two numbers are not equal.

`Greater than`

Check if a number is greater than another number.

`Less than`

Check if a number is less than another number.

`Greater or equal`

Check if a number is greater than or equal to another number.

`Less or equal`

Check if a number is less than or equal to another number.

Arithmetic
----------

`Addition`

Add up two numbers.

`Subtraction`

Subtract one number from another number.

`Multiplication`

Multiply one number by another number.

`Division`

Divide one number by another number.

`Remainder`

Calculate the remainder left over when one integer is divided by another integer.

Conversion
----------

`Extend`

Convert (extend) `i32` to `i64`.

`Wrap`

Convert (wrap) `i64` to `i32`.

`Promote`

Convert (promote) `f32` to `f64`.

`Demote`

Convert (demote) `f64` to `f32`.

`Convert`

Convert integers to floating points.

`Truncate (float to int)`

Convert (truncate fractional part) floating points to integers.

`Reinterpret`

Reinterpret the bytes of integers as floating points and vice versa.

Floating point specific instructions
------------------------------------

`Min`

Get the lower of two numbers.

`Max`

Get the higher of two numbers.

`Nearest`

Round a number to the nearest integer.

`Ceil`

Round up a number.

`Floor`

Round down a number.

`Truncate (float to float)`

Discard the fractional part of a number.

`Absolute`

Get the absolute value of a number.

`Negate`

Negate a number.

`Square root`

Get the square root of a number.

`Copy sign`

Copy just the sign bit from one number to another.

Bitwise
-------

`AND`

Used for performing a bitwise AND.

`OR`

Used for performing a bitwise OR.

`XOR`

Used for performing a bitwise XOR.

`Left shift`

Used for performing a bitwise left-shift.

`Right shift`

Used for performing a bitwise right-shift.

`Left rotate`

Used for performing a bitwise left-rotate.

`Right rotate`

Used for performing a bitwise right-rotate.

`Count leading zeros`

Count the amount of leading zeros in a numbers binary representation.

`Count trailing zeros`

Count the amount of trailing zeros in a numbers binary representation.

`Population count`

Count the total amount of 1s in a numbers binary representation.
unreachable
===========

**`unreachable`** is used to denote a point in code that should not be reachable. `unreachable` is an unconditional trap: in the case where an `unreachable` is reached and executed, the instruction traps.

Try it
------

Syntax
------


```wasm
unreachable
```


| Instruction | Binary opcode |
| --- | --- |
| `unreachable` | `0x00` |
if...else
=========

The **`if`** statement executes a statement if the last item on the stack is true (1). If the condition is false (0), another statement can be executed

Try it
------

Syntax
------


```wasm
i32.const 0
(if
  (then
    ;; do something
  )
  (else
    ;; do something else
  )
)
```


| Instruction | Binary opcode |
| --- | --- |
| `if` | `0x04` |
| `else` | `0x05` |
block
=====

The **`block`** statement creates a label that can later be branched out of with a `br`.

The **`loop`** statement is the opposite of the `block` statement, in the sense that while branching to a `loop` jumps to the beginning of the loop, branching to a `block` jumps to the end of the block; that is, out of the block.

Try it
------

Syntax
------


```wasm
;; label the block so that it can be branched to.
(block $my\_block

  ;; branch to the block.
  ;; most of the time you'll want to put this in an if statement and only branch on condition,
  ;; otherwise the following control flow are unreachable.
  br $my\_block

  ;; this will never be reached, since the br jumped out of the block already.
  unreachable

)
```


| Instruction | Binary opcode |
| --- | --- |
| `block` | `0x02` |
call
====

**`call`** calls a function, `return_call` being the tail-call version of it. `call_indirect` calls a function in a table with the `return_call_indirect` tail-call version as well.

Try it
------

Syntax
------


```wasm
call $greet
```


| Instruction | Binary opcode |
| --- | --- |
| `call` | `0x10` |
| `call_indirect` | `0x11` |
| `return_call` | `0x12` |
| `return_call_indirect` | `0x13` |

See also
--------

* Tail Call Extension proposal overview
* V8 on WebAssembly tail calls support
return
======

**`return`** returns from a function.

* If there are no values left on the stack, it returns nothing/void.
* If there are the same amount of values left on the stack as specified in the function's type signature, it returns those values.
* If there are more values that the function's return type specifies, then the excess values are popped from the stack and discarded, and the last N values are returned.
Try it
------

Syntax
------


```wasm
f32.const 4.3
return
```



```wasm
i32.const 7
f32.const 4.3
return
```


| Instruction | Binary opcode |
| --- | --- |
| `return` | `0x0f` |