Using the browser API

This article is in need of a technical review.

Non-standard
This feature is not on a current W3C standards track, but it is supported on the Firefox OS platform. Although implementations may change in the future and it is not supported widely across browsers, it is suitable for use in code dedicated to Firefox OS apps.

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="http://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="http://hostname.tld" mozapp='http://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="http://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:

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.

Performance methods

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

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:

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.

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:

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;
  });
});

See also

Document Tags and Contributors

Last updated by: fabrice.desre,