# org.apache.cordova.inappbrowser This plugin provides a web browser view that displays when calling `window.open()`, or when opening a link formed as ``. var ref = window.open('http://apache.org', '_blank', 'location=yes'); __NOTE__: The InAppBrowser window behaves like a standard web browser, and can't access Cordova APIs. ## Installation cordova plugin add org.apache.cordova.inappbrowser ## window.open Opens a URL in a new `InAppBrowser` instance, the current browser instance, or the system browser. var ref = window.open(url, target, options); - __ref__: Reference to the `InAppBrowser` window. _(InAppBrowser)_ - __url__: The URL to load _(String)_. Call `encodeURI()` on this if the URL contains Unicode characters. - __target__: The target in which to load the URL, an optional parameter that defaults to `_self`. _(String)_ - `_self`: Opens in the Cordova WebView if the URL is in the white list, otherwise it opens in the `InAppBrowser`. - `_blank`: Opens in the `InAppBrowser`. - `_system`: Opens in the system's web browser. - __options__: Options for the `InAppBrowser`. Optional, defaulting to: `location=yes`. _(String)_ The `options` string must not contain any blank space, and each feature's name/value pairs must be separated by a comma. Feature names are case insensitive. All platforms support the value below: - __location__: Set to `yes` or `no` to turn the `InAppBrowser`'s location bar on or off. Android only: - __closebuttoncaption__: set to a string to use as the __Done__ button's caption. - __hidden__: set to `yes` to create the browser and load the page, but not show it. The load event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally. - __clearcache__: set to `yes` to have the browser's cookie cache cleared before the new window is opened - __clearsessioncache__: set to `yes` to have the session cookie cache cleared before the new window is opened iOS only: - __closebuttoncaption__: set to a string to use as the __Done__ button's caption. Note that you need to localize this value yourself. - __disallowoverscroll__: Set to `yes` or `no` (default is `no`). Turns on/off the UIWebViewBounce property. - __hidden__: set to `yes` to create the browser and load the page, but not show it. The load event fires when loading is complete. Omit or set to `no` (default) to have the browser open and load normally. - __toolbar__: set to `yes` or `no` to turn the toolbar on or off for the InAppBrowser (defaults to `yes`) - __enableViewportScale__: Set to `yes` or `no` to prevent viewport scaling through a meta tag (defaults to `no`). - __mediaPlaybackRequiresUserAction__: Set to `yes` or `no` to prevent HTML5 audio or video from autoplaying (defaults to `no`). - __allowInlineMediaPlayback__: Set to `yes` or `no` to allow in-line HTML5 media playback, displaying within the browser window rather than a device-specific playback interface. The HTML's `video` element must also include the `webkit-playsinline` attribute (defaults to `no`) - __keyboardDisplayRequiresUserAction__: Set to `yes` or `no` to open the keyboard when form elements receive focus via JavaScript's `focus()` call (defaults to `yes`). - __suppressesIncrementalRendering__: Set to `yes` or `no` to wait until all new view content is received before being rendered (defaults to `no`). - __presentationstyle__: Set to `pagesheet`, `formsheet` or `fullscreen` to set the [presentation style](http://developer.apple.com/library/ios/documentation/UIKit/Reference/UIViewController_Class/Reference/Reference.html#//apple_ref/occ/instp/UIViewController/modalPresentationStyle) (defaults to `fullscreen`). - __transitionstyle__: Set to `fliphorizontal`, `crossdissolve` or `coververtical` to set the [transition style](http://developer.apple.com/library/ios/#documentation/UIKit/Reference/UIViewController_Class/Reference/Reference.html#//apple_ref/occ/instp/UIViewController/modalTransitionStyle) (defaults to `coververtical`). - __toolbarposition__: Set to `top` or `bottom` (default is `bottom`). Causes the toolbar to be at the top or bottom of the window. ### Supported Platforms - Amazon Fire OS - Android - BlackBerry 10 - iOS - Windows Phone 7 and 8 ### Example var ref = window.open('http://apache.org', '_blank', 'location=yes'); var ref2 = window.open(encodeURI('http://ja.m.wikipedia.org/wiki/ハングル'), '_blank', 'location=yes'); ## InAppBrowser The object returned from a call to `window.open`. ### Methods - addEventListener - removeEventListener - close - show - executeScript - insertCSS ## addEventListener > Adds a listener for an event from the `InAppBrowser`. ref.addEventListener(eventname, callback); - __ref__: reference to the `InAppBrowser` window _(InAppBrowser)_ - __eventname__: the event to listen for _(String)_ - __loadstart__: event fires when the `InAppBrowser` starts to load a URL. - __loadstop__: event fires when the `InAppBrowser` finishes loading a URL. - __loaderror__: event fires when the `InAppBrowser` encounters an error when loading a URL. - __exit__: event fires when the `InAppBrowser` window is closed. - __callback__: the function that executes when the event fires. The function is passed an `InAppBrowserEvent` object as a parameter. ### InAppBrowserEvent Properties - __type__: the eventname, either `loadstart`, `loadstop`, `loaderror`, or `exit`. _(String)_ - __url__: the URL that was loaded. _(String)_ - __code__: the error code, only in the case of `loaderror`. _(Number)_ - __message__: the error message, only in the case of `loaderror`. _(String)_ ### Supported Platforms - Amazon Fire OS - Android - BlackBerry 10 - iOS - Windows Phone 7 and 8 ### Quick Example var ref = window.open('http://apache.org', '_blank', 'location=yes'); ref.addEventListener('loadstart', function() { alert(event.url); }); ## removeEventListener > Removes a listener for an event from the `InAppBrowser`. ref.removeEventListener(eventname, callback); - __ref__: reference to the `InAppBrowser` window. _(InAppBrowser)_ - __eventname__: the event to stop listening for. _(String)_ - __loadstart__: event fires when the `InAppBrowser` starts to load a URL. - __loadstop__: event fires when the `InAppBrowser` finishes loading a URL. - __loaderror__: event fires when the `InAppBrowser` encounters an error loading a URL. - __exit__: event fires when the `InAppBrowser` window is closed. - __callback__: the function to execute when the event fires. The function is passed an `InAppBrowserEvent` object. ### Supported Platforms - Amazon Fire OS - Android - BlackBerry 10 - iOS - Windows Phone 7 and 8 ### Quick Example var ref = window.open('http://apache.org', '_blank', 'location=yes'); var myCallback = function() { alert(event.url); } ref.addEventListener('loadstart', myCallback); ref.removeEventListener('loadstart', myCallback); ## close > Closes the `InAppBrowser` window. ref.close(); - __ref__: reference to the `InAppBrowser` window _(InAppBrowser)_ ### Supported Platforms - Amazon Fire OS - Android - BlackBerry 10 - iOS - Windows Phone 7 and 8 ### Quick Example var ref = window.open('http://apache.org', '_blank', 'location=yes'); ref.close(); ## show > Displays an InAppBrowser window that was opened hidden. Calling this has no effect if the InAppBrowser was already visible. ref.show(); - __ref__: reference to the InAppBrowser window (`InAppBrowser`) ### Supported Platforms - Amazon Fire OS - Android - BlackBerry 10 - iOS ### Quick Example var ref = window.open('http://apache.org', '_blank', 'hidden=yes'); // some time later... ref.show(); ## executeScript > Injects JavaScript code into the `InAppBrowser` window ref.executeScript(details, callback); - __ref__: reference to the `InAppBrowser` window. _(InAppBrowser)_ - __injectDetails__: details of the script to run, specifying either a `file` or `code` key. _(Object)_ - __file__: URL of the script to inject. - __code__: Text of the script to inject. - __callback__: the function that executes after the JavaScript code is injected. - If the injected script is of type `code`, the callback executes with a single parameter, which is the return value of the script, wrapped in an `Array`. For multi-line scripts, this is the return value of the last statement, or the last expression evaluated. ### Supported Platforms - Amazon Fire OS - Android - BlackBerry 10 - iOS ### Quick Example var ref = window.open('http://apache.org', '_blank', 'location=yes'); ref.addEventListener('loadstop', function() { ref.executeScript({file: "myscript.js"}); }); ## insertCSS > Injects CSS into the `InAppBrowser` window. ref.insertCSS(details, callback); - __ref__: reference to the `InAppBrowser` window _(InAppBrowser)_ - __injectDetails__: details of the script to run, specifying either a `file` or `code` key. _(Object)_ - __file__: URL of the stylesheet to inject. - __code__: Text of the stylesheet to inject. - __callback__: the function that executes after the CSS is injected. ### Supported Platforms - Amazon Fire OS - Android - BlackBerry 10 - iOS ### Quick Example var ref = window.open('http://apache.org', '_blank', 'location=yes'); ref.addEventListener('loadstop', function() { ref.insertCSS({file: "mystyles.css"}); });