PhoneGap Android ChildBrowser Revamp

Recently I've been spending quite a bit of time revamping the Android ChildBrowser so that it is more in line with the ChildBrowser available for iOS. The big problem was that on Android we started a new Intent to view the web page and there was no way to communicate back to the original application. This new approach uses a dialog with an embedded web view to show the new web page but don't worry you can still use the old way if you really want.

Installation of the new plugin is much the same as it was previously.

1. To install the plugin, move www/childbrowser.js to your project's www folder and include a reference to it in your html file after phonegap.{ver}.js.

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

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

2. Copy the image files folder www/childbrowser to your project'w www folder. Note you need the entire folder not just the images. Feel free to provide your own images, these are only some default place holders we are providing.

3. Create a directory within your project called "src/com/phonegap/plugins/childBrowser" and copy "src/com/phonegap/plugins/childBrowser/ChildBrowser.java" into it.

4. Add the following activity to your AndroidManifest.xml file. It should be added inside the <application> tag.

<activity android:name="com.phonegap.DroidGap" android:label="@string/app_name">
<intent-filter>
</intent-filter>
</activity>

5. In your res/xml/plugins.xml file add the following line:

<plugin name="ChildBrowser" value="com.phonegap.plugins.childBrowser.ChildBrowser"/>

Once installed properly, you should be able to browse external sites. I've provided the full listing of my test html at the end of this post but for now here's a screen shot of what the app would look like:

As you can see there are three buttons. The first "Show Page" is going to give you a dialog that looks like this:

This is accomplished by calling the following JavaScript:

window.plugins.childBrowser.showWebPage(
            "http://www.phonegap.com", {
            showLocationBar: true
        });

The second button "Show Page No Toolbar" once pressed gives you a dialog that looks like this:

Which is accomplished by calling the following JavaScript:

window.plugins.childBrowser.showWebPage(
            "http://www.phonegap.com", {
            showLocationBar: false
        });

As you can see the only difference between it and the first example is that the showLocationBar parameter has been set to false. Currently this is the only optional parameter we support right now but more can be added easily if required.

Finally if you push the last button "Old ChildBrowser" you would have a new Intent being launched to handle the page view:

Now the syntax for getting the old ChildBrowser behaviour has changed a bit. It is now:

window.plugins.childBrowser.openExternal("http://www.phonegap.com");

Now this is all well and good but how does it help us communicate between the application and the child browser. To do this we provide a couple of event handler on the ChildBrowser for onClose and onLocationChanged. You provide your own functions which are called when the ChildBrowser gets a close event or a locationChanged event. For instance:

function showPage(locbar) {
    window.plugins.childBrowser.onLocationChange = locationChanged;
    window.plugins.childBrowser.onClose = closed;
    window.plugins.childBrowser.showWebPage(
        "http://www.phonegap.com", {
        showLocationBar: locbar
    });
}

function locationChanged(newurl) {
    console.log("The JS got this url = " + newurl);
}
    
function closed() {
    console.log("The JS got a close event");
}

Well I hope people find the changes useful. It should make doing oauth a lot easier. No, I don't have an example for that yet.