Installing PhoneGap Plugins with pluginstall

Phonegap applications can be extended with plugins to add additional functionality. Historically, installing plugins meant copying a bunch of files into the correct places in your project.

Andrew Lunny wrote the Cordova Plugin Specification and pluginstall. Pluginstall is a tool that automates the installation of plugins which conform to the plugin specification.

In addition to demonstrating pluginstall, we’ll also use the PhoneGap create script to make a new project. The cordova build scripts will be used for compiling and installing the binary. Using these tools it’s possible to develop PhoneGap apps with a text editor, instead of an IDE.

Prerequisites

I’ll assume that you have Phonegap 2.2.0 and the Android SDK installed.

Pluginstall requires node.js and is installed through npm. If you’re on a mac and use homebrew, install node and npm with brew install node.

Setup

Install pluginstall:

$ npm install -g pluginstall

Create a new Android project using the PhoneGap create script. Create takes the new project path, package name and activity name as arguments.

$ cd /usr/local/phonegap-2.2.0/lib/android
$ ./bin/create ~/foo com.example.foo Foo

The create script built a new PhoneGap project in directory ~/foo. Inside the project there is a cordova directory with some command line tools.

Let’s ensure the generated project works before we modify anything. Start the emulator.

$ cd ~/foo
$ cordova/emulate

Patiently wait for the emulator to start. Unlock the screen and keep the emulator running. Compile, build, install, and launch your app.

$ cordova/BOOM

The application should launch and say “Device is ready”.

Install the plugin

Get a local copy of the Child Browser Plugin.

$ cd /tmp
$ git clone git://github.com/alunny/ChildBrowser.git

Install the plugin using pluginstall. Pluginstall takes the platform, project directory and plugin directory as arguments.

$ pluginstall android ~/foo /tmp/ChildBrowser

The Child Browser plugin is now installed. pluginstall used to the information in the plugin.xml manifest to update the project. It added an Activity to the Android manifest, listed the plugin in config.xml, added java source code, and added javascript code and images to our project.

Write some code to use the plugin

Edit ~/foo/assets/www/index.html

Include the javascript after cordova.js

<script type="text/javascript" src="cordova-2.2.0.js"></script>
<script type="text/javascript" src="childbrowser.js"></script>
<script type="text/javascript" src="js/index.js"></script>

Edit ~/foo/assets/www/js/index.js

In onDeviceReady, add a call that will open a web page in the Child Browser after 3 seconds:

onDeviceReady: function() {
  app.receivedEvent('deviceready');
  setTimeout( function() {
    window.plugins.childBrowser.showWebPage(
            'http://phonegap.com',
            { showLocationBar: true },);
    }, 3000);
}

Compile, build, install, and launch your app into the running emulator.

$ cordova/BOOM

The sample application should run and open http://phonegap.com in the Child Browser Plugin.