View source for WebAPI/BrowserAPI

= Browser Element & API =

This is a proposal for a Browser API and a new HTML element called "<browser>" or "<webview>", which is similar to an iframe but allows the implementation of a fully featured web browser as a web app.

This feature is being tracked by the meta-bug {{bug|693515}} (alias browser-api).

This is similar to the [https://developer.mozilla.org/en/XUL/browser XUL browser element].

== Roadmap ==

* P1
** {{In progress|}} Nested OOP {{bug|nested-oop}}
** State/Session restore {{bug|1033999}}
** Navigation scope
*** User stories: {{bug|996039}}, {{bug|972320}}, {{bug|1023803}}
*** Reference: https://github.com/w3c/manifest/issues/114
** {{In progress|}} Hardware key events {{bug|989198}}
** Fine-grained visilibity API {{bug|1034001}} (e.g. <code>setVisible(bool)</code> -> <code>setVisible({state: bool, rendering: bool, normalpriority: bool })</code>)
* P2
** <iframe mozbrowser> to <webview> {{bug|738172}}
** Rewrite some browser API using C++
* P3
** Dialog API (http auth, alert, etc)
** OOM Priority API
* P4
** Clean up existing functions
** Password management
** Freeze process
* P5
** Metadata API
* Related
** {{In progress|}} {{Pl|WebAPI/WidgetAPI|WidgetAPI|}} embed-widgets permission and mozwidget attribute {{bug|1005818}}

== Summary ==

{{Note|Please find the current document on MDN https://developer.mozilla.org/en-US/docs/WebAPI/Browser}}

{| class="wikitable"
|+Attributes
|-
! Name !! Priority !! Bug !! Status
|-
|src || P1 || || {{implemented|}}
|}

{| class="wikitable"
|+ Methods
|-
! Name !! Priority !! Bug !! Status
|-
|go || || || '''not started'''
|-
|stop || P1 || {{bug|709759}} || {{implemented|}}
|-
|reload || P2 || {{bug|741717}} || {{implemented|}}
|-
|go{Back,Forward}, canGo{Back,Forward} || P2 || {{bug|741755}} || {{implemented|}}
|-
|getScreenshot || P1 || {{bug|753595}} || {{implemented|}}
|-
|getContentDimensions || || {{bug|757859}} || {{implemented|}}
|-
|setVisible || || {{bug|702880}}, {{bug|762939}} || {{implemented|}}
|}

{| class="wikitable"
|+Events
|-
! Name !! Priority !! Bug !!Status
|-
|loadstart || P1 || || {{implemented|}}
|-
|loadend || P1 || || {{implemented|}}
|-
|loadprogress || || || '''not started'''
|-
|locationchange || P1 || || {{implemented|}}
|-
|titlechange || P1 || || {{implemented|}}
|-
|iconchange || P1 || {{bug|719461}} || {{implemented|}}
|-
|alert/prompt/confirm || P1 || {{bug|741587}} || {{implemented|}}
|-
|open || P1 || {{bug|742944}} || {{implemented|}}
|-
|close || P1 || {{bug|757182}} || {{implemented|}}
|-
|securitychange || P1 || {{bug|763694}} || {{implemented|}}
|-
|contextmenu || P1 || {{bug|756371}} || {{implemented|}}
|-
|error || || {{bug|768842}} || {{implemented|}}
|-
|error:fatal || || {{bug|766437}} || {{implemented|}}
|-
|scroll || P1 || {{bug|770847}} || {{implemented|}}
|}

{| class="wikitable"
|+Other Related Features (not all necessarily part of Browser API)
|-
! Name !! Priority !! Bug !! Status
|-
|Process separation || P1 || {{bug|714861}} || {{implemented|}}
|-
|Framebusting protection || P1 || {{bug|771273}} || {{implemented|}}
|-
|Touch pan & zoom || P1 || {{bug|745136}} || {{implemented|}}
|-
|<meta name="viewport"> tags || P2 || {{bug|746502}} || {{implemented|}}
|-
|target=_blank/_top || P2 || {{bug|769254}} || {{implemented|}}
|-
|Permissions prompts || P1 || || {{implemented|}}
|-
|Clear private data || P1 || || {{implemented|}}
|-
|Turn cookies on/off ||  || || '''not started'''
|-
|<select> popups || P1 || {{bug|759511}} || {{implemented|}}
|}

== Example implementation ==

This is a minimal implementation of a browser.  When it's complete, it will
exercise the full surface area of the API.

''This code is completely untested at the moment.''

=== HTML ===

  &lt;div&gt;&lt;span id='location-bar'&gt;&lt;/span&gt; &lt;button onclick='go_button_clicked()'&gt;Go&lt;/button&gt;&lt;/div&gt;
  &lt;div id='load-status'&gt;&lt;/div&gt;
  &lt;div id='security-status'&gt;&lt;/div&gt;
  &lt;img id='favicon'&gt;
  &lt;div id='title'&gt;&lt;/div&gt;
  &lt;iframe mozbrowser id='browser'&gt;&lt;/iframe&gt;

=== JS ===

  function $(id) {
    return document.getElementById(id);
  }
  
  let iframe = $('browser');
  
  iframe.addEventListener('mozbrowserloadstart', function(e) {
    $('load-status').innerText = 'loading...';
  });
  
  iframe.addEventListener('mozbrowserloadend', function(e) {
    $('load-status').innerText = 'done loading';
  });
  
  iframe.addEventListener('mozbrowserlocationchange', function(e) {
    $('location-bar').innerText = e.detail;
  });
  
  iframe.addEventListener('mozbrowsertitlechange', function(e) {
    $('title').innerText = e.detail;
  });
  
  iframe.addEventListener('mozbrowsericonchange', function(e) {
    $('favicon').src = e.detail;
  });
  
  iframe.addEventListener('mozbrowsersecuritychange', function(e) {
    // 'secure', 'insecure', or 'broken'.  'broken' indicates mixed content.
    $('security-status').innerText = e.detail.state;
    
    // There's also e.detail.extendedValidation (boolean), but this will be
    // false until bug 764496 is fixed.
  });
  
  iframe.addEventListener('mozbrowsercontextmenu', function(e) {
    // TODO
  });
  
  iframe.addEventListener('mozbrowsererror', function(e) {
    switch (e.detail.type) {
    case 'other':
      // Something has gone wrong -- we're probably displaying a Gecko error
      // page, e.g. "no network connection" or "invalid SSL cert".  You
      // probably don't need to do anything here.
      break;
    case 'fatal':
      // The tab crashed.  Not implemented yet; see bug 766437.
      break;
    }
  });
  
  iframe.addEventListener('mozbrowserkeyevent', function(e) {
    // TODO.  You probably don't care about this event.
  });
  
  iframe.addEventListener('mozbrowsershowmodalprompt', function(e) {
    // TODO
  });
  
  iframe.addEventListener('mozbrowseropenwindow', function(e) {
    // TODO
  });
  
  iframe.addEventListener('mozbrowserclose', function() {
    // This is really only meaningful for popup windows.
    document.body.removeChild(iframe);
  });
  
  function go_button_clicked() {
    iframe.src = $('location-bar').value;
  }
  
  // TODO:
  //   * getCanGoBack
  //   * getCanGoForward
  //   * goBack
  //   * goForward
  //   * setVisible
  //   * getScreenshot

== Draft Specification ==

Other browser vendors have implementations of a similar API (e.g. [https://developer.chrome.com/apps/tags/webview Chrome]). An early draft proposal for a standardised <webview> element and associated API can be found [http://benfrancis.github.io/webview/ here]. Please provide feedback in the issue tracker [https://github.com/benfrancis/webview/issues here].

[[Category:Web APIs]]