# PhoneGap Documentation

# InAppBrowser

> The `InAppBrowser` is a web browser that displays in the app when calling `window.open`.

    var ref = window.open('http://apache.org', '_blank', 'location=yes');

## Description

The object returned from a call to `window.open`.

## Methods

- addEventListener
- removeEventListener
- close
- executeScript
- insertCSS

## Permissions

### Android

#### app/res/xml/config.xml

    <plugin name="InAppBrowser" value="org.apache.cordova.InAppBrowser" />

### iOS

#### config.xml

    <plugin name="InAppBrowser" value="CDVInAppBrowser" />

### Windows Phone 7 + 8

#### config.xml

    <plugin name="InAppBrowser" />

# 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.

## Supported Platforms

- Android
- iOS
- Windows Phone 7 + 8

## Quick Example

    var ref = window.open('http://apache.org', '_blank', 'location=yes');
    ref.addEventListener('loadstart', function() { alert(event.url); });

## Full Example

    <!DOCTYPE html>
    <html>
      <head>
        <title>InAppBrowser.addEventListener Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
             var ref = window.open('http://apache.org', '_blank', 'location=yes');
             ref.addEventListener('loadstart', function(event) { alert('start: ' + event.url); });
             ref.addEventListener('loadstop', function(event) { alert('stop: ' + event.url); });
             ref.addEventListener('loaderror', function(event) { alert('error: ' + event.message); });
             ref.addEventListener('exit', function(event) { alert(event.type); });
        }

        </script>
      </head>
      <body>
      </body>
    </html>

# 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

- Android
- iOS
- Windows Phone 7 + 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);

## Full Example

    <!DOCTYPE html>
    <html>
      <head>
        <title>InAppBrowser.removeEventListener Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // Global InAppBrowser reference
        var iabRef = null;

        function iabLoadStart(event) {
            alert(event.type + ' - ' + event.url);
        }

        function iabLoadStop(event) {
            alert(event.type + ' - ' + event.url);
        }

        function iabLoadError(event) {
            alert(event.type + ' - ' + event.message);
        }

        function iabClose(event) {
             alert(event.type);
             iabRef.removeEventListener('loadstart', iabLoadStart);
             iabRef.removeEventListener('loadstop', iabLoadStop);
             iabRef.removeEventListener('loaderror', iabLoadError);
             iabRef.removeEventListener('exit', iabClose);
        }

        // device APIs are available
        //
        function onDeviceReady() {
             iabRef = window.open('http://apache.org', '_blank', 'location=yes');
             iabRef.addEventListener('loadstart', iabLoadStart);
             iabRef.addEventListener('loadstop', iabLoadStop);
             iabRef.removeEventListener('loaderror', iabLoadError);
             iabRef.addEventListener('exit', iabClose);
        }

        </script>
      </head>
      <body>
      </body>
    </html>

# close

> Closes the `InAppBrowser` window.

    ref.close();

- ref: reference to the `InAppBrowser` window (InAppBrowser)

## Supported Platforms

- Android
- iOS
- Windows Phone 7 + 8
- BlackBerry 10

## Quick Example

    var ref = window.open('http://apache.org', '_blank', 'location=yes');
    ref.close();

## Full Example

    <!DOCTYPE html>
    <html>
      <head>
        <title>InAppBrowser.close Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
             var ref = window.open('http://apache.org', '_blank', 'location=yes');
             // close InAppBrowser after 5 seconds
             setTimeout(function() {
                 ref.close();
             }, 5000);
        }

        </script>
      </head>
      <body>
      </body>
    </html>

# 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

- Android
- iOS

## Quick Example

    var ref = window.open('http://apache.org', '_blank', 'location=yes');
    ref.addEventListener('loadstop', function() {
        ref.executeSript({file: "myscript.js"});
    });

## Full Example

    <!DOCTYPE html>
    <html>
      <head>
        <title>InAppBrowser.executeScript Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // Global InAppBrowser reference
        var iabRef = null;

        // Inject our custom JavaScript into the InAppBrowser window
        //
        function replaceHeaderImage() {
            iabRef.executeScript({
                code: "var img=document.querySelector('#header img'); img.src='http://cordova.apache.org/images/cordova_bot.png';"
            }, function() {
                alert("Image Element Successfully Hijacked");
            }
        }

        function iabClose(event) {
             iabRef.removeEventListener('loadstop', replaceHeaderImage);
             iabRef.removeEventListener('exit', iabClose);
        }

        // device APIs are available
        //
        function onDeviceReady() {
             iabRef = window.open('http://apache.org', '_blank', 'location=yes');
             iabRef.addEventListener('loadstop', replaceHeaderImage);
             iabRef.addEventListener('exit', iabClose);
        }

        </script>
      </head>
      <body>
      </body>
    </html>

# 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

- Android
- iOS

## Quick Example

    var ref = window.open('http://apache.org', '_blank', 'location=yes');
    ref.addEventListener('loadstop', function() {
        ref.insertCSS({file: "mystyles.css"});
    });

## Full Example

    <!DOCTYPE html>
    <html>
      <head>
        <title>InAppBrowser.insertCSS Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // Global InAppBrowser reference
        var iabRef = null;

        // Inject our custom CSS into the InAppBrowser window
        //
        function changeBackgroundColor() {
            iabRef.insertCSS({
                code: "body { background: #ffff00"
            }, function() {
                alert("Styles Altered");
            }
        }

        function iabClose(event) {
             iabRef.removeEventListener('loadstop', changeBackgroundColor);
             iabRef.removeEventListener('exit', iabClose);
        }

        // device APIs are available
        //
        function onDeviceReady() {
             iabRef = window.open('http://apache.org', '_blank', 'location=yes');
             iabRef.addEventListener('loadstop', changeBackgroundColor);
             iabRef.addEventListener('exit', iabClose);
        }

        </script>
      </head>
      <body>
      </body>
    </html>

# InAppBrowserEvent

The object that is passed to the callback function from an `addEventListener` call on an `InAppBrowser` object.

## 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)

# 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 that will be the caption for the "Done" button.

  ## iOS only

  - closebuttoncaption - set to a string that will be the caption for the "Done" button. Note that you will have to localize this value yourself.
  - 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 inline 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 (defaults to `fullscreen`).
  - transitionstyle: Set to `fliphorizontal`, `crossdissolve` or `coververtical` to set the transition style (defaults to `coververtical`).

## Supported Platforms

- Android
- iOS
- BlackBerry 10
- Windows Phone 7 + 8

## Quick 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');

## Full Example

    <!DOCTYPE html>
    <html>
      <head>
        <title>window.open Example</title>

        <script type="text/javascript" charset="utf-8" src="cordova-x.x.x.js"></script>
        <script type="text/javascript" charset="utf-8">

        // Wait for device API libraries to load
        //
        document.addEventListener("deviceready", onDeviceReady, false);

        // device APIs are available
        //
        function onDeviceReady() {
            // external url
            var ref = window.open(encodeURI('http://apache.org'), '_blank', 'location=yes');
            // relative document
            ref = window.open('next.html', '_self');
        }

        </script>
      </head>
      <body>
      </body>
    </html>