Skip to content
cross-platform ChildBrowser plugin for PhoneGap/Cordova
Java Objective-C C# JavaScript
Branch: master
Clone or download
alunny Update
note that I am no longer working on this
Latest commit f15e20d Oct 13, 2013
Type Name Latest commit message Commit time
Failed to load latest commit information.
readmes very rough cross-platform ChildBrowser Jan 20, 2012
src Update src/ios/ChildBrowserCommand.m Jan 24, 2013
www adding semicolon, for consistency Feb 7, 2013 Update Oct 13, 2013
plugin.xml [ios] s/appViewController/viewController/ Aug 9, 2012

ChildBrowser plugin for PhoneGap

Important Note

I (@alunny) am no longer working on this project, and no longer on PhoneGap Build. If you would like changes to get into PhoneGap Build's version of this plugin, please see


This is a prototype of a cross-platform ChildBrowser PhoneGap plugin. Android and iOS are currently supported. Support for BlackBerry and Windows Phone is also planned.

The goal is for a single JavaScript file to be usable on all supported platforms, and the native code to be installed in a project through a separate script.

The Structure

-- src
  -- android
  -- ios
    -- ChildBrowser.bundle
      -- arrow_left.png
      -- arrow_left@2x.png
      -- ...
    -- ChildBrowserCommand.h
    -- ChildBrowserCommand.m
    -- etc
-- www
  -- childbrowser.js
  -- childbrowser
    -- icon_arrow_left.png
    -- icon_arrow_right.png
    -- ...


The plugin.xml file is loosely based on the W3C's Widget Config spec.

It is in XML to facilitate transfer of nodes from this cross platform manifest to native XML manifests (AndroidManifest.xml, App-Info.plist, config.xml (BB)).

A specification for this file format will be forthcoming once more feedback has been received, and the tooling around plugin installation is more mature.

ChildBrowser JavaScript API

As with most Cordova/PhoneGap APIs, functionality is not available until the deviceready event has fired on the document. The childbrowser.js file should be included after the phonegap.js file.

All functions are called on the singleton ChildBrowser instance - accessible as window.plugins.childBrowser.



showWebPage(url, [options])

Displays a new ChildBrowser with the specified URL. Defaults to true.

Available options:

  • showLocationBar (Android and iOS): show/hide a location bar in the generated browser
  • showAddress (Android and iOS): show/hide the address bar in the generated browser
  • showNavigationBar (Android and IOS): show/hide the entire navigation bar. Important: since there is no "Done"-Button anymore, the ChildBrowser can only be closed with the api call close() (see below).


                                        { showLocationBar: true });



Closes the ChildBrowser.




openExternal(url, usePhoneGap)

(Android only) Opens the URL in a regular browser - if usePhoneGap, that browser will be a PhoneGap-enabled webview




All events can be subscribed to by assigning a function to window.plugins.childBrowser['on' + eventName]; see examples below


Called when the ChildBrowser has been closed


window.plugins.childBrowser.onClose = function () {
    alert('childBrowser has closed');


Called when the ChildBrowser loads a URL (including the initial location, when showWebPage is called). The callback function is passed the new URL being loaded.


window.plugins.childBrowser.onLocationChange = function (url) {
    alert('childBrowser has loaded ' + url);


(iOS only) Called when the user opts to load an app in the device's browser (exiting the PhoneGap app in the process).


window.plugins.childBrowser.onOpenExternal = function () {
    alert('opening Mobile Safari');

Thank you GitHub People

  • @RandyMcMillan
  • @reinberger
  • @yimingkuan


MIT License (2008). See for full text.

Copyright 2012, Andrew Lunny, Adobe Systems

Copyright (c) 2005-2010, Nitobi Software Inc.

Copyright (c) 2011, IBM Corporation

Copyright (c) 2010 Jesse MacFadyen, Nitobi

Copyright (c) 2012 Randy McMillan

You can’t perform that action at this time.