Differences between revisions 10 and 11
Revision 10 as of 2012-12-10 22:08:53
Size: 4826
Comment:
Revision 11 as of 2013-04-12 10:06:41
Size: 5210
Comment:
Deletions are marked like this. Additions are marked like this.
Line 36: Line 36:
window.open returns an object that you can listen for three events on: "loadstart", "loadstop" and "exit", as well as call the "close()" function. 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.
Line 81: Line 81:
ref.addEventListener('loaderror', function(event) { alert(event.type + ' - ' + event.url + ' - ' + event.code + ' - ' + event.message); } );
Line 84: Line 85:
The "event" object has two properties: "type" and "url". The "event" object has two properties: "type" and "url" (plus optional "code" and "message" properties for loaderror).
Line 91: Line 92:

    ```code``` (optional: loaderror only)
        the error code for the event

    ```message``` (optional: loaderror only)
        the message for the event

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

   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)