InAppBrowser

Provides the ability to spawn a browser instance from a Cordova application. The API is based on standard browser capability.

Declarative API

The declarative API is based on the target attribute on anchor elements.

[1] http://www.w3.org/TR/html401/types.html#type-frame-target

Specification

var ref = window.open( strUrl, strWindowName[, strWindowFeatures])

strUrl

strWindowName

strWindowFeatures

window.open returns an object that you can listen for three events on: "loadstart", "loadstop", "loaderror", and "exit", as well as call the "close()" function.

Example usage

1. Local urls

   1 window.open('local-url.html');                  // loads in the Cordova WebView 
   2 window.open('local-url.html', '_self');         // loads in the Cordova WebView
   3 window.open('local-url.html', '_system');       // Security error: system browser, but url will not load (iOS)
   4 window.open('local-url.html', '_blank');        // loads in the InAppBrowser
   5 window.open('local-url.html', 'random_string'); // loads in the InAppBrowser
   6 window.open('local-url.html', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar
   7 

2. White-listed urls

   1 window.open('http://whitelisted-url.com');                  // loads in the Cordova WebView
   2 window.open('http://whitelisted-url.com', '_self');         // loads in the Cordova WebView
   3 window.open('http://whitelisted-url.com', '_system');       // loads in the system browser
   4 window.open('http://whitelisted-url.com', '_blank');        // loads in the InAppBrowser
   5 window.open('http://whitelisted-url.com', 'random_string'); // loads in the InAppBrowser
   6 window.open('http://whitelisted-url.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar
   7 

3. Urls that are not white-listed

   1 window.open('http://url-that-fails-whitelist.com');                  // loads in the InAppBrowser
   2 window.open('http://url-that-fails-whitelist.com', '_self');         // loads in the InAppBrowser
   3 window.open('http://url-that-fails-whitelist.com', '_system');       // loads in the system browser
   4 window.open('http://url-that-fails-whitelist.com', '_blank');        // loads in the InAppBrowser
   5 window.open('http://url-that-fails-whitelist.com', 'random_string'); // loads in the InAppBrowser
   6 window.open('http://url-that-fails-whitelist.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar
   7 

4. Events

   1 var ref = window.open('http://whitelisted-url.com', '_blank');
   2 ref.addEventListener('loadstart', function(event) { alert(event.type + ' - ' + event.url); } );
   3 ref.addEventListener('loadstop', function(event) { alert(event.type + ' - ' + event.url); } );
   4 ref.addEventListener('loaderror', function(event) { alert(event.type + ' - ' + event.url + ' - ' + event.code + ' - ' + event.message); } );
   5 ref.addEventListener('exit', function(event) { alert(event.type); } );

The "event" object has two properties: "type" and "url" (plus optional "code" and "message" properties for loaderror).

5. Close the InAppBrowser

   1 var ref = window.open('http://whitelisted-url.com', '_blank');
   2 ref.close();

Tip

Local and whitelisted URLs should be opened with Cordova functionality by default (_self) and you have to be explicit if you want those trusted resources opened without Cordova functionality (_blank or _system). Also -- window.location = 'foo' is equivalent to the '_self' options above.

Testing InAppBrowser

* InAppBrowserTest

Existing Work

https://github.com/phonegap/phonegap-plugins

Mailing List Discussion

1. http://markmail.org/thread/tmcjk33lszn7hxhc

2. http://markmail.org/thread/wbka4n6zzto44hgr

InAppBrowser (last edited 2013-04-12 10:06:41 by ShazronAbdullah)