Extending the PhoneGap API – Third-Party Plugins (ChildBrowser)
So the last post was all about editing PhoneGap classes to add a little something extra, today it’s about using a third-party plugin that you may have downloaded from somewhere or gotten from someone.
The plugins that we will be using today are from Jesse MacFayden (aka @purplecabbage on twitter). The original source code for the plugins can be downloaded from github here: https://github.com/purplecabbage/phonegap-plugins.git
If you are using PhoneGap 0.9.6
You can get the entire source for my sample project “HelloPhoneGap” from github here: https://github.com/hutley/HelloPhoneGap
If you are using PhoneGap 1.0
You can get the entire source for my sample project “HelloPhoneGap1.0” from github here: https://github.com/hutley/HelloPhoneGap1.0
What is a PhoneGap Plugin?
Simply enough, a PhoneGap plugin is an extension to PhoneGap that allows access to some piece of native functionality on the phone that PhoneGap doesn’t already provide.
A PhoneGap plugin consists of at least two pieces:
- JavaScript file that defines the functions for accessing the native hooks
- Implementation files written in the native language to interact with native phone features
So for iOS a PhoneGap plugin is a package that consists of at least one JavaScript file and at least a pair of .m and .h Objective-C files that extend the PhoneGapCommand class.
It is possible (depending on the complexity of the plugin) that there will be other files as well such as UIViewControllers, UI.xib files, images, etc.
Installing a Third-Party Plugin
Once you have a copy of the plugin that you want to use, you need to make it accessible to your project. This can be done in a variety ways and the plugin could be located in a number of places. To keep it simple and not venture into a long rant on packaging, we will place our newly acquired plugin in the ${PROJECT_DIR}/Plugins directory.
General Steps to Follow:
- Download your plugin to your machine somewhere – take note of the location
- Open your XCode project (which was created from the PhoneGap template)
- Locate the Plugins directory within your project (not the PhonGapLib project)
- Right-click and add the files from your downloaded plugin directory. Be sure to check the “copy” and “create group references” checkboxes
- Build the project — you may need to add dependent libraries depending on the plugin
In my HelloPhoneGap example I have copied in two plugins from @purplecabbage:
- ChildBrowser – plugin to open resources in a child browser of the application rather than launching Safari.
- NativeControls – plugin to use native controls like a TabBar and ActionSheet (which I will demonstrate in an upcoming post).
As you can see from the above screenshot, the ChildBrowser plugin has images, a viewController, a .xib file, as well as JavaScript and the PhoneGapCommand implementation. The NativeControls plugin is a bit simpler with just the three typical files.
In order to use these plugins from JavaScript the script files need to be located in the ‘www’ directory and you need to include the proper script file on your HTML page. For peace of mind, I added a build step to copy the .js files from the ${PROJECT_DIR}/plugins directory to the ${PROJECT_DIR}/www.
I execute the following script during the build to copy the files:
#!/bin/sh
# PluginCopy.sh
# HelloPhoneGap
# Created by Hiedi Utley on 3/30/11.
# Copyright 2011 Chariot Solutions, LLC. All rights reserved.
cp -rf ${PROJECT_DIR}/Plugins/*/*.js ${PROJECT_DIR}/www
Note: You will need to chmod the PluginCopy.sh script file once you download it from github in order to build the HelloPhoneGap project.
How To Use the Plugin
Using a plugin is relatively simple, after you have put all the files in place in the project, you just need to include the script file for the plugin on your page. Depending on the plugin – you may need to explicitly “install” the plugin – which just means instantiate an instance of the plugin object and make it available for use.
Typically plugins are added to the window.plugins object and are accessible like window.plugins.somePlugin but sometimes that can get unwieldy and you may want to shorten the reference to something like var somePlugin = window.plugins.somePlugin; for use on your page. It’s up to you…
As for figuring out if you need to explicitly install a plugin, all you need to do is inspect the JavaScript (and/or the README) for the plugin and look for a call to the PhoneGap.addConstructor if that’s there, then you should be able to access the plugin as soon as onDeviceReady() is called. If not – you may need to do a SomePlugin.install() within onDeviceReady before using the plugin.
Sample Code
The following excerpt is from the childBrowser.html page in the HelloPhoneGap project – and there are several things to note:
- line 9 - PhoneGap.js is included before any other plugin files
- line 10 – ChildBrowser.js file is included – this file should be located in the ${PROJECT_DIR}/ www directory
- lines 13-22 – onDeviceReady() method signifies that PhoneGap has been initialized
- line 21 – ChildBrowser.install() exlicitly installs the ChildBrowser plugin. Note some plugins will do this automatically. Check…
- lines 23-34 - openChildBrowser(url) calls the childBrowser.showWebPage(url) function to launch a new UIWebView with the requested URL
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<!-- Change this if you want to allow scaling -->
<meta name="viewport" content="width=default-width; user-scalable=no" />
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<link rel="stylesheet" href="HelloPhoneGap.css" type="text/css"/>
<title>HelloPhoneGap</title>
<script type="text/javascript" charset="utf-8" src="phonegap.0.9.4.min.js"></script>
<script type="text/javascript" charset="utf-8" src="ChildBrowser.js"></script>
<script type="text/javascript" charset="utf-8">
var childBrowser;
function onBodyLoad()
{
document.addEventListener("deviceready",onDeviceReady,false);
}
/* PhoneGap has been initialized and is ready to roll */
function onDeviceReady()
{
phoneGapReady.innerHTML = "PhoneGap is Ready";
childBrowser = ChildBrowser.install();
}
function openChildBrowser(url)
{
try {
//both of these should work...
//window.plugins.childBrowser.showWebPage(url);
childBrowser.showWebPage(url);
}
catch (err)
{
alert(err);
}
}
</script>
</head>
<body onload="onBodyLoad()">
<button onclick="openChildBrowser('http://www.google.com');">Open Google</button>
</body>
</html>
So the screenshots show the childBrowser.html page and by clicking on the button, the plugin is called which ultimately instantiates a instance of the ChildBrowserViewController which loads the ChildBrowserViewController.xib file to display a new UIWebView and load the requested URL.
As a side note, I also wanted to be able to open local file resources in my ChildBrowser (which it wasn’t able to do before) so I did edit the plugin files to make this happen. If you are interested in the changes – please peruse the ChildBrowserCommand.m file lines 36-44.
So that’s all for now — next post will concentrate on using the NativeControls (ActionSheet) plugin to interact with the built-in PhoneGap Camera API.
