Differences between revisions 11 and 12
Revision 11 as of 2013-04-12 10:06:41
Size: 5210
Comment:
Revision 12 as of 2017-03-13 22:25:50
Size: 0
Comment: old
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
= 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 <<BR>>
 "_system" -> always open in the system web browser <<BR>>
 "_blank" -> always open in the InAppBrowser <<BR>>
 
```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 ===

{{{#!highlight javascript
window.open('local-url.html'); // loads in the Cordova WebView
window.open('local-url.html', '_self'); // loads in the Cordova WebView
window.open('local-url.html', '_system'); // Security error: system browser, but url will not load (iOS)
window.open('local-url.html', '_blank'); // loads in the InAppBrowser
window.open('local-url.html', 'random_string'); // loads in the InAppBrowser
window.open('local-url.html', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar
}}}

=== 2. White-listed urls ===

{{{#!highlight javascript
window.open('http://whitelisted-url.com'); // loads in the Cordova WebView
window.open('http://whitelisted-url.com', '_self'); // loads in the Cordova WebView
window.open('http://whitelisted-url.com', '_system'); // loads in the system browser
window.open('http://whitelisted-url.com', '_blank'); // loads in the InAppBrowser
window.open('http://whitelisted-url.com', 'random_string'); // loads in the InAppBrowser
window.open('http://whitelisted-url.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar
}}}

=== 3. Urls that are not white-listed ===

{{{#!highlight javascript
window.open('http://url-that-fails-whitelist.com'); // loads in the InAppBrowser
window.open('http://url-that-fails-whitelist.com', '_self'); // loads in the InAppBrowser
window.open('http://url-that-fails-whitelist.com', '_system'); // loads in the system browser
window.open('http://url-that-fails-whitelist.com', '_blank'); // loads in the InAppBrowser
window.open('http://url-that-fails-whitelist.com', 'random_string'); // loads in the InAppBrowser
window.open('http://url-that-fails-whitelist.com', 'random_string', 'location=no'); // loads in the InAppBrowser, no location bar
}}}


=== 4. Events ===

{{{#!highlight javascript
var ref = window.open('http://whitelisted-url.com', '_blank');
ref.addEventListener('loadstart', function(event) { alert(event.type + ' - ' + event.url); } );
ref.addEventListener('loadstop', function(event) { alert(event.type + ' - ' + event.url); } );
ref.addEventListener('loaderror', function(event) { alert(event.type + ' - ' + event.url + ' - ' + event.code + ' - ' + event.message); } );
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 ===

{{{#!highlight javascript
var ref = window.open('http://whitelisted-url.com', '_blank');
ref.close();
}}}


{{{#!wiki tip
'''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