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.
_blank
new in-app browser instance
_system
system browser
_self
in current browser instance
[1] http://www.w3.org/TR/html401/types.html#type-frame-target
Specification
var ref = window.open( strUrl, strWindowName[, strWindowFeatures])
strUrl
- this is a url, prefixed with a scheme for external urls or a filename for urls that exist in the local www folder
strWindowName
- valid values are "_self", "_system", "_blank", or null. null is treated the same as "_self", any other value is treated as "_blank".
"_self" -> opens in the Cordova WebView if strUrl is in the white-list, else it opens in the InAppBrowser
"_system" -> always open in the system web browser
"_blank" -> always open in the InAppBrowser
strWindowFeatures
- Optional parameter listing the features of the new window. The string must not contain any blank space, each feature name and value must be separated by a comma. We only support the value below:
location --> set to 'yes' or 'no' to turn the location bar on or off for the InAppBrowser
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).
type
- corresponds to the event name
url
- the relevant url for the event
code (optional: loaderror only)
- the error code for the event
message (optional: loaderror only)
- the message for the event
5. Close the InAppBrowser
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
Existing Work
https://github.com/phonegap/phonegap-plugins