Using the browser API

No estándar
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

This API is available on Firefox OS for privileged or certified applications only.

Summary

The HTML Browser API is an extension of the HTML <iframe> element that allows web apps to implement browsers or browser-like applications. This entails two major aspects:

Make the iframe appear like a top-level browser window to the embedded content. This means that window.top, window.parent, window.frameElement, etc. should not reflect the frame hierarchy. Optionally, the notion that the embedded is an Open Web App can be expressed as well.
An API to manipulate and listen for changes to the embedded content's state.

In addition to that, it's also possible to express the notion that the embedded content is an Open Web App. In that case the content is loaded within the appropriate app context (such as permissions).

Usage

An <iframe> is turned into a browser frame by setting the mozbrowser attribute:

<iframe src="https://hostname.tld" mozbrowser>

In order to embed an Open Web App, the mozapp attribute must also be supplied, with the path to the app's manifest:

<iframe src="https://hostname.tld" mozapp='https://path/to/manifest.webapp' mozbrowser>

At last the content of the <iframe> can be loaded in its own child process, separate to the page embedding this frame by using the remote attribute.

<iframe src="https://hostname.tld" mozbrowser remote>

Warning: That last attribute is necessary for security reasons if you plan to load content from an untrusted/unknown origin. If you don't use it, you take the risk of your application being compromised by a malicious web site.

Permissions

Any application that wants to embed a browser frame must have the browser permission within its app manifest.

{
  "permissions": {
    "browser": {}
  }
}

Additionally, to embed an Open Web App, the app must have the embed-apps permission.

{
  "permissions": {
    "browser": {},
    "embed-apps": {}
  }
}

Extra methods

To support the requirement of a browser <iframe>, Firefox OS extends the HTMLIFrameElement DOM interface. Those new methods gives the <iframe> some super powers:

Navigation methods

Those methods allow navigating through the browsing history of the <iframe>. They are necessary to be able to implement back, forward, stop, and reload buttons.

reload(): Allows reloading the content of the <iframe>.
stop(): Allows stopping the loading of the <iframe>'s content.
getCanGoBack(): Allows knowing if it's possible to navigate backward.
goBack(): Changes the location of the <iframe> for the previous location in its browsing history.
getCanGoForward(): Allows knowing if it's possible to navigate forward.
goForward(): Changes the location of the <iframe> for the next location in its browsing history.

Performance methods

Those methods are used to manage the resources used by a browser <iframe>. This is especially useful for implementing tabbed browser application.

setVisible(): Changes the visibility state of a browser <iframe>. This can influence resources allocation and some function usage such as requestAnimationFrame.
getVisible(): Allows knowing the current visibility state of the browser <iframe>.
purgeHistory(): Allows clearing all the resources (cookies, localStorage, cache, etc.) associated with the browser <iframe>.

Event methods

In order to manage the browser <iframe>'s content, many new events were added (see below). The following methods are used to deal with those events:

The <iframe> gains support for the methods of the EventTarget interface: addEventListener(), removeEventListener(), and dispatchEvent().
sendMouseEvent(): Allows sending a MouseEvent to the <iframe>'s content.
sendTouchEvent(): Allows sending a TouchEvent to the <iframe>'s content. Note that this method is available for touch enabled devices only.
addNextPaintListener(): Allows defining a handler to listen for the next MozAfterPaint event in the browser <iframe>.
removeNextPaintListener(): Allows removing a handler previously set with addNextPaintListener().

Miscellaneous methods

Those methods are utilities, useful for apps that host a browser <iframe>.

getScreenshot(): Allows taking a screenshot of the browser <iframe>'s content. This is particularly useful to get thumbnails of tabs in a tabbed browser app.
zoom(): Change the zoom factor of the browser <iframe>'s content. This is particularly useful to perform zoom in/out on non-touch-enabled devices.

Events

In order to allow an application to manage the browser <iframe>, the application can listen for new events about what's happening within the browser <iframe>. The following new events can be listened for:

mozbrowserasyncscroll: Sent when the scroll position within a browser <iframe> changes.
mozbrowserclose: Sent when window.close() is called within a browser <iframe>.
mozbrowsercontextmenu: Sent when a browser <iframe> tries to open a context menu. This allows handling <menuitem> element available within the browser <iframe>'s content.
mozbrowsererror: Sent when an error occurred while trying to load content within a browser <iframe>.
mozbrowsericonchange: Sent when the favicon of a browser <iframe> changes.
mozbrowserloadend: Sent when the browser <iframe> has finished loading all its assets.
mozbrowserloadstart: Sent when the browser <iframe> starts to load a new page.
mozbrowserlocationchange: Sent when a browser <iframe>'s location changes.
mozbrowseropenwindow: Sent when window.open() is called within a browser <iframe>.
mozbrowsersecuritychange: Sent when the SSL state changes within a browser <iframe>.
mozbrowsershowmodalprompt: Sent when alert(), confirm(), or prompt() is called within a browser <iframe>.
mozbrowsertitlechange: Sent when the document.title changes within a browser <iframe>.
mozbrowserusernameandpasswordrequired: Sent when an HTTP authentification is requested.
mozbrowseropensearch: Sent when a link to a search engine is found.

Example

In this example we'll see how to implement a very basic browser app.

HTML

In the HTML we just add a URL bar, a "Go" and "Stop" button, and a browser <iframe>.

<header>
  <input id="url">
  <button id="go">Go</button>
  <button id="stop">Stop</button>
</header>

<iframe src="about:blank" mozbrowser remote></iframe>

CSS

We switch between the go and stop button with a little css trick.

button:disabled {
  display: none;
}

JavaScript

Now we can add the required functionalities:

document.addEventListener("DOMContentLoaded", function () {
  var url  = document.getElementById("url");
  var go   = document.getElementById("go");
  var stop = document.getElementById("stop");

  var browser = document.getElementsByTagName("iframe")[0];

  // This function is used to switch the Go and Stop button
  // If the browser is loading content, "Go" is disabled and "Stop" is enabled
  // Otherwise, "Go" is enabled and "Stop" is disabled
  function uiLoading(isLoading) {
      go.disabled =  isLoading;
    stop.disabled = !isLoading;
  }

  go.addEventListener("touchend", function () {
    browser.setAttribute("src", url.value);
  });

  stop.addEventListener("touchend", function () {
    browser.stop();
  });

  // When the browser starts loading content, we switch the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowserloadstart', function () {
    uiLoading(true);
  });

  // When the browser finishes loading content, we switch back the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowserloadend', function () {
    uiLoading(false);
  });

  // In case of error, we also switch back the "Go" and "Stop" buttons
  browser.addEventListener('mozbrowsererror', function (event) {
    uiLoading(false);
    alert("Loading error: " + event.detail);
  });

  // When a user follows a link, we make sure the new location is displayed in the address bar
  browser.addEventListener('mozbrowserlocationchange', function (event) {
    url.value = event.detail;
  });
});