InAppBrowser
The
InAppBrowser
is a web browser view that displays when calling[window.open](window.open.html)()
, or when opening a link formed as<a target="_blank">
.
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.
Description
The object returned from a call to [window.open](window.open.html)
.
Methods
- addEventListener
- removeEventListener
- close
- show
- executeScript
- insertCSS
Accessing the Feature
As of version 3.0, Cordova implements device-level APIs as plugins.
Use the CLI's plugin
command, described in The Command-Line
Interface, to add or remove this feature for a project:
$ cordova plugin add org.apache.cordova.inappbrowser
$ cordova plugin ls
[ 'org.apache.cordova.inappbrowser' ]
$ cordova plugin rm org.apache.cordova.inappbrowser
These commands apply to all targeted platforms, but modify the platform-specific configuration settings described below:
-
Amazon Fire OS (in
res/xml/config.xml
)<feature name="InAppBrowser"> <param name="android-package" value="org.apache.cordova.inappbrowser.InAppBrowser" /> </feature>
-
Android (in
res/xml/config.xml
)<feature name="InAppBrowser"> <param name="android-package" value="org.apache.cordova.inappbrowser.InAppBrowser" /> </feature>
-
iOS (in the named application directory's
config.xml
)<feature name="InAppBrowser"> <param name="ios-package" value="CDVInAppBrowser" /> </feature>
-
Windows Phone 7 and 8 (in
config.xml
)<feature name="InAppBrowser" />
Some platforms may support this feature without requiring any special configuration. See Platform Support for an overview.
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.
- loadstart: event fires when the
-
callback: the function that executes when the event fires. The function is passed an
InAppBrowserEvent
object as a parameter.
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); });
Full Example
<!DOCTYPE html>
<html>
<head>
<title>InAppBrowser.addEventListener Example</title>
<script type="text/javascript" charset="utf-8" src="cordova.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.
- loadstart: event fires when the
-
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);
Full Example
<!DOCTYPE html>
<html>
<head>
<title>InAppBrowser.removeEventListener Example</title>
<script type="text/javascript" charset="utf-8" src="cordova.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.addEventListener('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
- 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();
Full Example
<!DOCTYPE html>
<html>
<head>
<title>InAppBrowser.close Example</title>
<script type="text/javascript" charset="utf-8" src="cordova.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>
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');
ref.show();
Full Example
<!DOCTYPE html>
<html>
<head>
<title>InAppBrowser.show Example</title>
<script type="text/javascript" charset="utf-8" src="cordova.js"></script>
<script type="text/javascript" charset="utf-8">
// Wait for Cordova to load
//
document.addEventListener("deviceready", onDeviceReady, false);
// Cordova is ready
//
function onDeviceReady() {
var ref = window.open('http://apache.org', '_blank', 'hidden=yes');
ref.addEventListener('loadstop', function(event) {
alert('background window loaded');
});
// 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
orcode
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 anArray
. For multi-line scripts, this is the return value of the last statement, or the last expression evaluated.
- If the injected script is of type
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"});
});
Full Example
<!DOCTYPE html>
<html>
<head>
<title>InAppBrowser.executeScript Example</title>
<script type="text/javascript" charset="utf-8" src="cordova.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
orcode
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"});
});
Full Example
<!DOCTYPE html>
<html>
<head>
<title>InAppBrowser.insertCSS Example</title>
<script type="text/javascript" charset="utf-8" src="cordova.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
, orexit
. (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)