WebAPI/BrowserAPI: Difference between revisions

no edit summary
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
187

edits