Bridging The PhoneGap: ChildBrowser Plugin

This is the first post in a series that I have been meaning to write for a while. PhoneGap (now called Cordova) is the defacto platform for building native applications with HTML5. In the past few years we have seen quite a few JavaScript frameworks pop up to help you with your UI, which has always been the toughest part.

To name a few we have…

…and several more.

We’ve just about got this nut cracked. PhoneGap provides a fantastic wrapper for deploying your applications and taking advantage of native device features.

But there are places where we still have a gap. Fortunately enough, there is a GitHub Repo dedicated to bridging this gap with plugins for PhoneGap that provide missing or extended functionality to the base PhoneGap install.

In this post, we’ll take a look at one of these plugins called The ChildBrowser Plugin. I’ll go over the (Why, What, Where, How) WWWH for each of these plugins.

All of my demos will be done in iOS. Note that the process for doing this on Android may be different than what you see here.

The Child Browser Plugin

Why

PhoneGap wraps your application in a mobile Safari window. But what if you want to open a new window? While we are doing HTML/JavaScript development in PhoneGap, some things do not work. For instance, you cannot simply call…

window.open("http://google.com")

or

<a href="http://www.reddit.com">View On Reddit</a>

Spawning new windows or redirecting to other content is not OK and doesn’t work they way it does on the web. The reasons for spawning a new window in a web application vary, but consider the following scenarios…

  1. You want to let a user browse a link in your application without actually having to leave your app.
  2. You want to popup a window so they can login to a 3rd party (read Facebook, Twitter) without having to leave your application.
  3. You want to display a PDF document for them to read.

What

The Child Browser Plugin was created just for this scenario. It allows you to open a new window and even has events to capture responses from the spawned child window.

The ChildBrowser is part of the PhoneGap Plugins Project.

Once you download it, you need to install it. I’m going to create a sample application that lets you pull in Reddit Stories and then click on a link to view the article full screen in the child browser window if you so choose to do so.

In my first pass at this, I create a link for each item with the href set to the url of the article.

What happens when I click on the link?

Hmmmm, thats weird. It took us to the right web page and we didn’t leave the application, but now my application is gone and we have a website instead with no back button. Not what we wanted.

Let’s try it again and set the target of the href to _blank.

That works too, but it opened up mobile Safari and my app went away. It’s going to be a pain for users to click on links, go to Safari, come back to my app and then repeat over and over again. We need a way to let them browse web content without leaving our app.

We’ve seen enough of the What and Why, let’s look at the How.

How

The first step is of course to download the ChildBrowser plugin. You can download the whole repo of plugins, which contains a version for every platform. As I mentioned earlier, I am going to be targeting iOS.

It’s important to mention here that if you haven’t downloaded PhoneGap (Cordova) recently, you need to do it again. It recently switched to being called Cordova and all the namespaces changed. The plugins will throw errors if you don’t have Cordova.

For my UI, I am using the new Kendo UI Mobile.

Once you have downloaded the plugins, browse to the iOS directory and then to the ChildBrowser folder. Inside that folder, drag ChildBrowser.js or ChildBrowser.min.js to the www folder of your application. You can delete the FBConnect example.

Now in XCode, right click on the Plugins folder and select Add Files. Browse to the ChildBrowser folder and select it. When you click Add, make sure you have the Create folder references for any added folders selected. You also want the Destination checkbox checked, but it should be by default.

Now we need to tell PhoneGap (Cordova) about this new plugin by opening up the Cordova.plist file and making an entry in the plugins section. The correct key/value pair entry is ChildBrowserCommand on both sides.

Add a script reference for the ChildBrowser.js or ChildBrowser.min.js to your index.html file in the www folder.

<script src="ChildBrowser.js"></script>

Once the script reference has been added, I can call the ChildBrowser plugin from JavaScript. The following function will be called when an item is clicked. It open a child window and sets the url of the window. Notice that we have to install the plugin first and make sure it is in fact installed before trying to use it.

pub.goToUrl = function(sender) {
  // get url off of data attribute from item that was clicked
  var url = $(sender).data("url"); 

  // install ChildBrowser
  var cb = ChildBrowser.install();
  // if ChildBrowser is installed, open it with target set
  if(cb != null)
    window.plugins.childBrowser.showWebPage(url);
}

Now when I click on an item, a nifty window slides up from the bottom. It allows the user to fully navigate web content, and when they are done, it simply slides down and goes away, bringing them right back to my application. Check out the short YouTube video below showcasing the ChildBrowser in action.

ChildBrowser

The ChildBrowser plugin is a very nice way to display external content or allow your users to read PDF files without them ever having to leave you application. This is a much better experience for the user.

PhoneGap (Cordova) is really great, but you have to know how to bridge the gaps in functionality when they exist.

You can grab the Xcode project used here on my GitHub page. I’ll keep this repo updated with this series of posts, providing the demo projects that I built here. Hop on over and grab the download.

Start developing with PhoneGap. It’s easy, and it’s getting better all the time. There are gaps, but we can bridge those with plugins providing an end to end native experience with HTML5.

blog comments powered by Disqus