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 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. setVisible(bool) -> setVisible({state: bool, rendering: bool, normalpriority: bool }))
• 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 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

Attributes

Name	Priority	Bug	Status
src	P1		[IMPLEMENTED]

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]

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]

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

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

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. Chrome). An early draft proposal for a standardised <webview> element and associated API can be found here. Please provide feedback in the issue tracker here.