WebAPI/BrowserAPI: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
No edit summary
Line 96: Line 96:
|}
|}


== Attributes ==
== Example implementation ==


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


: The URI of the content to appear in the element.
''This code is completely untested at the moment.''


== Methods ==
=== HTML ===


=== go(URI) ===  
  <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>


: Navigate to the URI provided.
=== JS ===


=== stop() ===
  function $(id) {
 
    return document.getElementById(id);
: Stop the content from loading. Used by a stop button in a browser app.
  }
 
 
=== reload()''' ===
  let iframe = $('browser');
 
 
: Reload the content in the browser. Used by a refresh button in a browser app. We may in future need other versions of this method (e.g. to bypass the browser cache and do a hard reload).
  iframe.addEventListener('mozbrowserloadstart', function(e) {
 
    $('load-status').innerText = 'loading...';
=== goBack() ===
  });
 
 
: Navigates back one step in the session history. Could have success/failure reported in a callback but this isn't essential. Used by a back button in a browser app.
  iframe.addEventListener('mozbrowserloadend', function(e) {
 
    $('load-status').innerText = 'done loading';
=== goForward() ===
  });
 
 
: Navigates forward one step in the session history. Could have success/failure reported in a callback but this isn't essential. Used by a forward button in a browser app.
  iframe.addEventListener('mozbrowserlocationchange', function(e) {
 
    $('location-bar').innerText = e.detail;
=== getCanGoBack(callback) ===
  });
 
 
: Tells the app whether there is a history item in the session history to navigate back to. Should return a boolean true or false in a callback. Used by a browser app to decide whether to display a back button.
  iframe.addEventListener('mozbrowsertitlechange', function(e) {
 
    $('title').innerText = e.detail;
 
  });
=== getCanGoForward(callback) ===
 
 
  iframe.addEventListener('mozbrowsericonchange', function(e) {
: Tells the app whether there is a history item in the session history to navigate forward to. Should return a boolean true or false in a callback. Used by a browser app to decide whether to display a forward button.
    $('favicon').src = e.detail;
 
  });
 
 
=== getScreenshot(callback) ===
  iframe.addEventListener('mozbrowsersecuritychange', function(e) {
 
    // 'secure', 'insecure', or 'broken'.  'broken' indicates mixed content.
: Generates a screenshot of the content currently displayed in the browser element. The screenshot should be returned to the callback as a binary blob, in addition to the URL it corresponds to. This could be used by a browser app to save visual bookmark or history information or as visual information to help in switching between tabs.
    $('security-status').innerText = e.detail.state;
 
   
=== getContentDimensions(callback) ===
    // There's also e.detail.extendedValidation (boolean), but this will be
 
    // false until bug 764496 is fixed.
: Gets the dimensions of the current browser content, returned as integers in the provided callback.
  });
 
 
=== setVisible ===
  iframe.addEventListener('mozbrowsercontextmenu', function(e) {
 
    // TODO
== Events ==
  });
Events which are fired by a browser element. ''This section is a bit out of date.''
 
 
  iframe.addEventListener('mozbrowsererror', function(e) {
=== loadstart ===
    switch (e.detail.type) {
 
    case 'other':
: Indicates that the element started loading content. Used by a browser app to show a loading indicator.
      // Something has gone wrong -- we're probably displaying a Gecko error
 
      // page, e.g. "no network connection" or "invalid SSL cert".  You
=== loadend ===
      // probably don't need to do anything here.
 
      break;
: Indicates that the element finished loading content. Used by a browser app to hide a loading indicator.
    case 'fatal':
 
      // The tab crashed. Not implemented yet; see bug 766437.
=== loadprogress ===
      break;
 
    }
: '''''not implemented''''' — Provides an estimate of the percentage of a page loaded. This is tricky but is better for browser apps to provide a determinate rather than indeterminate progress indicator.
  });
 
 
=== locationchange ===
  iframe.addEventListener('mozbrowserkeyevent', function(e) {
 
    // TODO. You probably don't care about this event.
: Indicates that the URI changed, the URI is included as a string in the event payload.
  });
 
 
=== titlechange ===
  iframe.addEventListener('mozbrowsershowmodalprompt', function(e) {
 
    // TODO
: Indicates that the title of the page changed, the title is included as a string in the event payload.
  });
 
 
=== iconchange ===
  iframe.addEventListener('mozbrowseropenwindow', function(e) {
 
    // TODO
: Indicates the favicon URL of the page changed, the URL of the favicon is included as a string in the event payload.
  });
 
 
=== showmodalprompt ===
  iframe.addEventListener('mozbrowserclose', function() {
 
    // This is really only meaningful for popup windows.
: Indicates that the content requested an alert, confirm, or prompt dialog. This API is a bit complicated; see the relevant test, or ask someone.
    document.body.removeChild(iframe);
 
  });
=== openwindow ===
 
 
  function go_button_clicked() {
: Indicates that the content requested a new window to be opened. Used by a browser app to open a new window/tab.
    iframe.src = $('location-bar').value;
 
  }
=== close ===
 
 
  // TODO:
: Indicates that the content requested the current window to be closed. Used by a browser app to close a window/tab.
  //  * getCanGoBack
 
  //  * getCanGoForward
=== securitychange ===
  //  * goBack
 
  //  * goForward
: Indicates that the security status of a web page changed. The options are "secure", "insecure", and "broken".  "broken" corresponds to the "broken lock icon", which indicates mixed content.
  //  * setVisible
 
  //  * getScreenshot
=== resize ===
 
: Indicates that the browser was resized. Not sure what data should be included in the event payload.
 
=== contextmenu ===
 
: Indicates that the browser should display a contextual menu and execute callbacks in the scope of the child frame when the user selects one of the options in the menu.
 
=== error ===
 
=== fail ===
 
=== scroll ===
 
== Other Features ==
=== Process separation ===
 
: Each browser element should be capable of running in its own system process.
 
=== Framebusting protection ===
 
: A browser element should ignore X-Frame-Options HTTP headers and act as a window.top boundary in order to prevent web sites from frame-busting. We already have a pref to disable X-Frame-Options system-wide but we need a way to just disable this for <browser> elements.
 
=== Touch pan & zoom ===
 
: Users of touch-based devices should be able to zoom with pinch to zoom, zoom in on an element by double-tapping it and pan around the page by dragging their finger across the screen.
 
=== <meta name="viewport"> tags ===
 
: Support for the de-facto standard of the viewport meta tag which allows web pages to be viewed at a readable physical size at different pixel densities.
 
=== target=_blank/_top ===
 
: Open <a target="_top"> and <a target="_blank"> in a new window.
 
=== Permissions prompts ===
 
: Some method of showing/wrapping permissions prompts for e.g. geolocation, indexedDB and fullscreen
 
=== Clear private data ===
 
: Some method of clearing private data, specifically for one app. Not sure if this should be part of the browser API, or another API. This should include the ability to clear cookies & cache for one particular app. Download history, saved form data, saved passwords and offline website data (indexedDB, localStorage, appcache etc.) may also need to be cleared in future.
 
=== Turn cookies on/off ===
 
: Some method of turning cookies on and off specifically for one app. Not sure if this should be part of the browser API or some other API.
 
=== <select> popups ===
 
: Implement <select> popups for B2G.
 
== Other Comments ==
 
Other features that could be required in the future:
* Find in page
* Download manager
* View source

Revision as of 03:15, 7 July 2012

Browser Element & API

This is a proposal for a Browser API and a new HTML element called "<browser>", 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-as-webapp).

This is similar to the XUL browser element.

Summary

New HTML tag name "<browser>" bug 738172

Attributes
Name Priority Bug Status
src P1 complete
Methods
Name Priority Bug Status
go P2 not started
stop P1 bug 709759 not started
reload P2 bug 741717 not started
go{Back,Forward}, canGo{Back,Forward} P2 bug 741755 complete
getScreenshot P1 bug 753595 complete
getContentDimensions bug 757859 in progress
setVisible bug 702880 complete, needs follow-up, bug 762939, in progress
Events
Name Priority Bug Status
loadstart P1 complete
loadend P1 complete
loadprogress P3 not started
locationchange P1 complete
titlechange P1 complete
iconchange P1 bug 719461 complete
alert/prompt/confirm P1 bug 741587 complete
open P1 bug 742944 complete
close P1 bug 757182 complete
securitychange P1 bug 763694 complete
contextmenu P1 bug 756371 complete
error bug 768842 complete
error:fatal bug 766437 not started
scroll P1 bug 770847 not started
Other Related Features (not all necessarily part of Browser API)
Name Priority Bug Status
Process separation P1 bug 714861 complete
Framebusting protection P1 bug 771273 in progress
Touch pan & zoom P1 bug 745136 in progress
<meta name="viewport"> tags P2 bug 746502 not started
target=_blank/_top P2 bug 769254 in progress
Permissions prompts P1 not started
Clear private data P1 not started
Turn cookies on/off P1 not started
<select> popups P1 bug 759511 not started

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
Retrieved from "https://wiki.mozilla.org/index.php?title=WebAPI/BrowserAPI&oldid=448395"