Using the browser API

  • Revision slug: DOM/Using_the_Browser_API
  • Revision title: Using the Browser API
  • Revision id: 351053
  • Created:
  • Creator: ptheriault
  • Is current revision? No
  • Comment Browser API was completely undocumented so I have made a first attempt to try to capture it. It is currently incomplete, and possibly incorrect, and is in dire need of a review by someone with a deep knowledge of this API.

Revision Content

DRAFT
This page is not complete.

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 of that the embedded is an Open Web App can be expressed as well.
  • An API to manipulate and listen for changes of 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="..." 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="..." mozapp='https://path/to/manifest.webapp' mozbrowser>

Permissions

In order to successfully embed a browser frame, the app must have the browser permission. Additionally, to embed an Open Web App, the app must have the embed-apps permission.

Properties

mozapp
Specifies that the embed content is the Open Web App described by the manifest location supplied as the value of this property.
mozbrowser
Specifies that the content should be a loaded in a browser frame.
remote
Specifies that the content should be loaded in it's own child process, seperate to the page embedding this frame.

Methods

A number of extra methods are avaiable on a browser frame:

setVisible(visible)
Allows the parent to explicitly change the visibility state of child browser frames.
getVisible()
Returns the current visibility state of the child browser frame. Returns a DOMRequest.
sendMouseEvent(type, x, y, button, clickCount, modifiers)
Send a mouse event to the browser frame.
sendTouchEvent(type, identifiers, touchesX, touchesY,radiisX, radiisY, rotationAngles, forces,count, modifiers)
Send a touch event to the browser frame.
goBack()
Navigate the child browser frame back.
goForward()
Navigate the child browser frame forward.
reload()
Reload the browser frame.
stop()
Stop loading the browser frame.
getScreenshot(maxWidth, maxHeight)
Allows the parent to take a screenshot of the child browser frame, scaled to fit within maxWidth & maxHeight pixels. The returned image will be . Returns a DOMRequest.
addNextPaintListener()
Add a listener to recieve an event the first time the child frame is ready to paint (This listener is sent an event after the first MozAfterPaint event is dispacted in the child.)
removeNextPaintListener()
Remove the listener added by the previous function.
getCanGoBack()
Returns a DOMRequest whos result is a boolean indicating wether the browser can be navigate backwards (i.e. value of nsIWebNavigation.canGoBack in the child browser frame)
getCanGoForward()
Returns a DOMRequest whos result is a boolean indicating wether the browser can be navigate forwards (i.e. value of nsIWebNavigation.canGoForward in the child browser frame)

Events

mozbrowserlocationchange
Sent when the frame location changes.
Property Type Description
??? ?? ??
mozbrowserloadstart
Fired when the child frame starts to load a new page.
Property Type Description
??? ?? ??
mozbrowserloadend
Fired when the frame has finished loading all its assets.
Property Type Description
??? ?? ??
mozbrowsertitlechange
Fired when the document.title changes in the child frame.
Property Type Description
??? ?? ??
mozbrowsericonchange
Fired with the favicon of the child content changes.
Property Type Description
??? ?? ??
mozbrowserclose
Fired when window.close() is called in the child.
Property Type Description
??? ?? ??
mozbrowsersecuritychange
Fired when the SSL state changes in the child. Properties:
state: .
Property Type Description
state DOMString string The current SSL state, 'broken', 'secure' or 'insecure' - see nsIWebProgressListener#State_Security_Flags for description of security flags.
isEV boolean True only if the current certificate is an Extended Validation certificate. (Note:Until bug 764496 is fixed, this will always return false.)
mozbrowsererror
Fired when an error occured when trying to load the content within the browser frame.
Property Type Description
??? ?? ??

Examples

See https://wiki.mozilla.org/WebAPI/BrowserAPI

Revision Source

<div style="margin: 1em 0px; padding: 1em; background-color: rgb(255, 255, 204); text-align: center;">
  <strong>DRAFT</strong>
  <div style="font-size: x-small;">
    This page is not complete.</div>
</div>
<p>The HTML Browser API is an extension of the HTML <a href="/en-US/docs/HTML/Element/iframe" title="/en-US/docs/HTML/Element/iframe"><code>iframe</code></a> element that allows web apps to implement browsers or browser-like applications. This entails two major aspects:</p>
<ul>
  <li>Make the <code>iframe</code> appear like a top-level browser window to the embedded content. This means that <span id="summary_alias_container"><span id="short_desc_nonedit_display"><a href="/en-US/docs/DOM/window.top" title="/en-US/docs/DOM/window.top"><code>window.top</code></a>, <a href="/en-US/docs/DOM/window.parent" title="/en-US/docs/DOM/window.parent"><code>window.parent</code></a>, <a href="/en-US/docs/DOM/window.frameElement" title="/en-US/docs/DOM/window.frameElement"><code>window.frameElement</code></a>, etc. should <em>not</em> reflect the frame hierarchy.</span></span> Optionally, the notion of that the embedded is an Open Web App can be expressed as well.</li>
  <li>An API to manipulate and listen for changes of the embedded content's state.</li>
</ul>
<p>In addition to that, it's also possible to express the notion that the embedded content is an <a href="/en-US/docs/Apps" title="/en-US/docs/Apps">Open Web App</a>. In that case the content is loaded within the appropriate app context (such as permissions).</p>
<h3 id="Usage">Usage</h3>
<p>An <code>iframe</code> is turned into a browser frame by setting the <code>mozbrowser</code> attribute:</p>
<pre>
&lt;iframe src="..." mozbrowser&gt;</pre>
<p>In order to embed an Open Web App, the <code>mozapp</code> attribute must also be supplied, with the path to the app's manifest:</p>
<pre>
&lt;iframe src="..." mozapp='https://path/to/manifest.webapp' mozbrowser&gt;</pre>
<h3 id="Permissions">Permissions</h3>
<p>In order to successfully embed a browser frame, the app must have the <code>browser</code> permission. Additionally, to embed an Open Web App, the app must have the <code>embed-apps</code> permission.</p>
<h3 id="Properties">Properties</h3>
<dl>
  <dt>
    mozapp</dt>
  <dd>
    Specifies that the embed content is the Open Web App described by the manifest location supplied as the value of this property.</dd>
  <dt>
    mozbrowser</dt>
  <dd>
    Specifies that the content should be a loaded in a browser frame.</dd>
</dl>
<dl>
  <dt>
    remote</dt>
  <dd>
    Specifies that the content should be loaded in it's own child process, seperate to the page embedding this frame.</dd>
</dl>
<h3 id="Methods">Methods</h3>
<p>A number of extra methods are avaiable on a browser frame:</p>
<dl>
  <dt>
    setVisible(visible)</dt>
  <dd>
    Allows the parent to explicitly change the visibility state of child browser frames.</dd>
  <dt>
    getVisible()</dt>
  <dd>
    Returns the current visibility state of the child browser frame. Returns a <a href="/en/DOM/DOMRequest" title="https://developer.mozilla.org/en/DOM/DOMRequest">DOMRequest</a>.</dd>
  <dt>
    sendMouseEvent(type, x, y, button, clickCount, modifiers)</dt>
  <dd>
    Send a mouse event to the browser frame.</dd>
  <dt>
    sendTouchEvent(type, identifiers, touchesX, touchesY,radiisX, radiisY, rotationAngles, forces,count, modifiers)</dt>
  <dd>
    Send a touch event to the browser frame.</dd>
  <dt>
    goBack()</dt>
  <dd>
    Navigate the child browser frame back.</dd>
  <dt>
    goForward()</dt>
  <dd>
    Navigate the child browser frame forward.</dd>
  <dt>
    reload()</dt>
  <dd>
    Reload the browser frame.</dd>
  <dt>
    stop()</dt>
  <dd>
    Stop loading the browser frame.</dd>
  <dt>
    getScreenshot(maxWidth, maxHeight)</dt>
  <dd>
    Allows the parent to take a screenshot of the child browser frame, scaled to fit within maxWidth &amp; maxHeight pixels. The returned image will be . Returns a <a href="/en/DOM/DOMRequest" title="https://developer.mozilla.org/en/DOM/DOMRequest">DOMRequest</a>.</dd>
  <dt>
    addNextPaintListener()</dt>
  <dd>
    Add a listener to recieve an event the first time the child frame is ready to paint (This listener is sent an event after the first <code>MozAfterPaint </code>event is dispacted in the child.)</dd>
  <dt>
    removeNextPaintListener()</dt>
  <dd>
    Remove the listener added by the previous function.</dd>
  <dt>
    getCanGoBack()</dt>
  <dd>
    Returns a <a href="/en/DOM/DOMRequest" title="https://developer.mozilla.org/en/DOM/DOMRequest">DOMRequest</a> whos result is a boolean indicating wether the browser can be navigate backwards (i.e. value of nsIWebNavigation.canGoBack in the child browser frame)</dd>
  <dt>
    getCanGoForward()</dt>
  <dd>
    Returns a <a href="/en/DOM/DOMRequest" title="https://developer.mozilla.org/en/DOM/DOMRequest">DOMRequest</a> whos result is a boolean indicating wether the browser can be navigate forwards (i.e. value of nsIWebNavigation.canGoForward in the child browser frame)</dd>
</dl>
<h3 id="Events">Events</h3>
<dl>
  <dt>
    mozbrowserlocationchange</dt>
  <dd>
    Sent when the frame location changes.</dd>
  <dd>
    <table class="standard-table" height="49" width="214">
      <tbody>
        <tr>
          <td class="header">Property</td>
          <td class="header">Type</td>
          <td class="header">Description</td>
        </tr>
        <tr>
          <td><code>???</code></td>
          <td>??</td>
          <td>??</td>
        </tr>
      </tbody>
    </table>
  </dd>
  <dt>
    mozbrowserloadstart</dt>
  <dd>
    Fired when the child frame starts to load a new page.</dd>
  <dd>
    <table class="standard-table" height="49" width="214">
      <tbody>
        <tr>
          <td class="header">Property</td>
          <td class="header">Type</td>
          <td class="header">Description</td>
        </tr>
        <tr>
          <td><code>???</code></td>
          <td>??</td>
          <td>??</td>
        </tr>
      </tbody>
    </table>
  </dd>
  <dt>
    mozbrowserloadend</dt>
  <dd>
    Fired when the frame has finished loading all its assets.</dd>
  <dd>
    <table class="standard-table" height="49" width="214">
      <tbody>
        <tr>
          <td class="header">Property</td>
          <td class="header">Type</td>
          <td class="header">Description</td>
        </tr>
        <tr>
          <td><code>???</code></td>
          <td>??</td>
          <td>??</td>
        </tr>
      </tbody>
    </table>
  </dd>
  <dt>
    mozbrowsertitlechange</dt>
  <dd>
    Fired when the document.title changes in the child frame.</dd>
  <dd>
    <table class="standard-table" height="49" width="214">
      <tbody>
        <tr>
          <td class="header">Property</td>
          <td class="header">Type</td>
          <td class="header">Description</td>
        </tr>
        <tr>
          <td><code>???</code></td>
          <td>??</td>
          <td>??</td>
        </tr>
      </tbody>
    </table>
  </dd>
  <dt>
    mozbrowsericonchange</dt>
  <dd>
    Fired with the favicon of the child content changes.</dd>
  <dd>
    <table class="standard-table" height="49" width="214">
      <tbody>
        <tr>
          <td class="header">Property</td>
          <td class="header">Type</td>
          <td class="header">Description</td>
        </tr>
        <tr>
          <td><code>???</code></td>
          <td>??</td>
          <td>??</td>
        </tr>
      </tbody>
    </table>
  </dd>
  <dt>
    mozbrowserclose</dt>
  <dd>
    Fired when window.close() is called in the child.</dd>
  <dd>
    <table class="standard-table" height="49" width="214">
      <tbody>
        <tr>
          <td class="header">Property</td>
          <td class="header">Type</td>
          <td class="header">Description</td>
        </tr>
        <tr>
          <td><code>???</code></td>
          <td>??</td>
          <td>??</td>
        </tr>
      </tbody>
    </table>
  </dd>
  <dt>
    mozbrowsersecuritychange</dt>
  <dd>
    Fired when the SSL state changes in the child. Properties:</dd>
  <dd>
    state: .</dd>
  <dd>
    <table class="standard-table">
      <tbody>
        <tr>
          <td class="header">Property</td>
          <td class="header">Type</td>
          <td class="header">Description</td>
        </tr>
        <tr>
          <td><code>state</code></td>
          <td>DOMString string</td>
          <td>The current SSL state, 'broken', 'secure' or 'insecure' - see <a href="/en-US/docs/XPCOM_Interface_Reference/nsIWebProgressListener#State_Security_Flags" title="/en-US/docs/XPCOM_Interface_Reference/nsIWebProgressListener#State_Security_Flags">nsIWebProgressListener#State_Security_Flags</a> for description of security flags.</td>
        </tr>
        <tr>
          <td><code>isEV</code></td>
          <td>boolean</td>
          <td>True only if the current certificate is an Extended Validation certificate. (Note:Until bug 764496 is fixed, this will always return false.)</td>
        </tr>
      </tbody>
    </table>
  </dd>
  <dt>
    mozbrowsererror</dt>
  <dd>
    Fired when an error occured when trying to load the content within the browser frame.</dd>
  <dd>
    <table class="standard-table" height="49" width="214">
      <tbody>
        <tr>
          <td class="header">Property</td>
          <td class="header">Type</td>
          <td class="header">Description</td>
        </tr>
        <tr>
          <td><code>???</code></td>
          <td>??</td>
          <td>??</td>
        </tr>
      </tbody>
    </table>
  </dd>
</dl>
<h3 id="Examples">Examples</h3>
<p>See https://wiki.mozilla.org/WebAPI/BrowserAPI</p>
Revert to this revision