Table of Contents


This document is under construction as Cordova/PhoneGap have changed quite a bit.

PhoneGap is a tool that allows you to target various phones, including Android, IPhone, Windows Phone 7, Blackberry, Symbion and WebOS.

To effectively use PhoneGap, you will need Eclipse, the Android SDK and the ADT plugin for Eclipse. If you don't have these tools installed already, descriptions and links for these tools are described later in this paragraph. Your first, step, then, will be to go to the

Cordova is the name for the open source version of PhoneGap. Because PhoneGap is a widely known name, we will probably hear that name the most often. But from a developers point of view, there is no real difference between PhoneGap and Cordova, and it is the Cordova source and documents that will often be the most important to us. PhoneGap was bought by Adobe in 2011. Since Cordova is open source, this is really a non-issue for most developers. Hopefully Adobe's deep pockets will help increase the popularity of Cordova, and help finance its development, but otherwise, there should be no significant impact. I'm not, of course, clairvoyant or able to predict the future, but that is my guess as to how things will pan out.

Navigate to the Get Started Guide and choose the platform you want to target. In our case, it will likely be Android. The description of how to get started is included on the page you selected. There is even a video to help step you through the process. I include my own take on the subject below, and show how a script that can make the process much simpler for you.

Don't forget to copy create a res/xml directory, and move the plugins.xmland phonegap.xml into it. Without this step, I got the following error:

android.content.res.Resources$NotFoundException: Resource ID #0x0


the problem was that the deviceReady event was never firing because the plugin(s) were not installed properly. In other words, these lines at the bottom of index.html were not working right:

document.addEventListener('deviceready', function onDeviceReady() {
    angular.bootstrap(document, ['statesApp']);
}, false);

NOTE: The deviceReady code won't work in a browser. This means you can have difficulties if you want to preview your app before installing it on AndroidX86 or a phone. The problem, of course, is that the deviceReady event will never fire in a browser since we are not installed in a device. Given the code above, this means that angular will never load, and hence main.html and about.html, etc. will never load. One fix would be to comment out those lines and restore the ng-app statement on the body tag near the top of the HTML file.

I fixed the plugins problem by doing this:

#! /bin/bash

rm -r platforms
rm -r plugins

cordova platform add android
cordova plugin add org.apache.cordova.network-information

It follows that we don't want to check in the plugins folder at all. Probably the best solution is to add plugins to your repository wide .gitignore file. Don't worry about having checked in plugins on one or two projects, but we do want to fix this issue going forward.

Phone Gap Setup

More recent information is here:

To create PhoneGap applications automatically, you need to know how to set up environment variables, as explained here. Before we get into the details, let me give you an overview in the form of a cheat sheet that will help you understand where we are headed.

If you have not done so already, you will first need to download and install the following:

Many developers get the Android SDK as part of the ADT Bundle that includes Eclipse. The bundle is just a zip file. In the other platforms section of the downloads page you can find a zip file for the Android SDK. Support for Mac and Linux are also under other platforms.

Details on what to download are discussed below and also in the page on setting up Eclipse. But first let's talk about setting up your environment.

The PhoneGap/Cordova Setup Cheat Sheet

To use the PhoneGap/Cordova create program to quickly and easily create a Cordova project you need to make sure you have the path on your system set up correctly so that several programs will run. In particular, you want the following programs to run from the command line:

In other words, you should be able to type any of those words, exactly as shown, and they should not produce an error that reads "XXX is not recognized as an internal or external command." Some of the programs may not do anything useful, but as long as they run, regardless of the ouput they produce, then you are good. For instance, here is the output you want to see from the ant program:

Buildfile: build.xml does not exist!
Build failed

Right now, we don't need to supply a build.xml file, we just need to see that ant is on the path. The output shown above confirms that ant is indeed on the path. If it were not, we would get an error about ant being an unrecognized command.

To ensure that all these programs run, you should set up the following environment variables, as shown on the left of the table presented below. On the right you see sample illustrations of what the paths could be:

The paths on the right are merely suggestions; you may wish to put these folders somewhere else.

Next, you need to set up the path on your system. Look at this group of paths, and see if they help:

%ANDROID_SDK_HOME%\platform-tools; adb
%ANDROID_SDK_HOME%\tools; android
%ANT_HOME%\bin; ant
%JAVA_HOME%\bin; javac
%PHONEGAP_HOME%\lib\android\bin create

The following SanityCheck batch file can help you confirm that you have at least set each of the environment variables on your system:


ECHO Looks good.


ECHO Missing one of the following:
ECHO -------------------
ECHO Try one of the following locations:
ECHO Apache ant: http://ant.apache.org
ECHO Android SDK: http://developer.android.com
ECHO Cordova: http://cordova.apache.org/
ECHO JDK: http://java.oracle.com

ECHO Your system currently has these settings:
ECHO -----------------------------------------
ECHO -----------------------------------------

Your setup is likely different from mine, but it might still be helpful to show the current setup on one of my systems as of January, 2014:

JAVA_HOME - C:\Program Files\Java\jdk1.7.0_51
ANT_HOME - C:\Development\apache-ant-1.9.3
PHONEGAP_HOME - C:\Development\cordova
ANDROID_SDK_HOME - C:\Users\Charlie\EclipseAdt\sdk

So long as you have the correct environment variables setup, then you can add those paths to your system exactly as shown. For instance, I appended the following to my path.


At the command prompt, this portion of my path produces the following output when I type the wordpath:


Use SetX to Set the Environment

Here is a little batch file that you can create to automate the process of setting your environment variables:

SetX JAVA_HOME "C:\Program Files\Java\jdk1.7.0_45"
SetX ANT_HOME C:\Src\Ant\apache-ant-1.9.3
SetX PHONEGAP_HOME C:\Src\cordova-android
SetX ANDROID_SDK_HOME C:\Src\Eclipse\sdk

The SetX is built into windows. You can learn about it by searching the internet or typing:

setx /h

In the code shown above, we are setting environment variables:


By default, the variable is set for the current user. If you want to change the entire environment for all users, look in the /M parameter. Here is how the help describes that variable:

/M Specifies that the variable should be set in the system wide (HKEY_LOCAL_MACHINE) environment. The default is to set the variable under the HKEY_CURRENT_USER environment.

Details on Setting up the Environment for PhoneGap

Now that you have an overview of where you are headed, I will add a bit more detail for those who are not clear on exactly how to proceed. The first thing to understand is that it is possible to build a fully functional "hello world" Cordova project using the tools that come with the PhoneGap SDK. First make sure you have downloaded the SDK, unzipped it, and placed it in a well known location, such as C:\Dev\Phonegap-2.3.0 orC:\Users\YourUserName\Dev\Phonegap-2.3.0. Here is the download site:


Also download Ant, unzip it, and place it in the same Dev directory as PhoneGap, ie C:\Dev\ApacheAnt-184:



You need to set up the JAVA_HOME environment variable.

For instance, set JAVA_HOME to this value:

C:\Program Files\Java\jdk1.6.0_27


Create an environment variable called ANT_HOME and point it at the home directory for ANT, the zip file you downloaded and probably put in c:\users\yourname\dev\ant....


Set up the following path variables, altering the paths so they make sense on your system. For instance, change the user name:


The point is that you need to set up your path so that the Android SDK platform-tools and tools directories are on your path:


Make sure Java works from the command line. If not, set up Java-home. Make sure javac will run from the command line. If not, examine the part of your path that we set with %JAVA_HOME%\bin.

Create a PhoneGap/Cordova Project

If you have everything set up right, then you should be able to go to the command prompt and run create.

As you know, in my system create is in:


On computers where you don't have rights to the root of the C drive, you might try something like this:


But regardless of where you put the program, you should be able to run it from any directory since it is now on your path.

Here is how to run the create program:

create C:\Temp\Cordova03 com.elvenware.cordova03 Cordova03

This command tells create to build a Cordova project and put in a folder called C:\Temp\Cordova03. The program will create the folder for you. It will set up your program to run in the com.elvenware.cordova03 namespace. The name of the project it creates will be Cordova03. This command creates a fully functional, ready to use instance of a Cordova project.

Notice that I am putting the project in a temp directory. Assuming that you are using Eclipse, the next step will be to copy it into our Eclipse workspace. If you are not using Eclipse, then you can the project from the temp directory or move it to someplace more useful.

To import the project in to Eclipse, choose File | Import | Android | Existing Android Code into Workspace

Browse to your project. Select the Copy Projects into workspaceoption. Click OK. Now you should see your project in the Eclipse Project Manager. You can run it by right clicking, and choosing Run As | Android Application.

Because you will be giving the command to create a project so often, it helps to automate the process. Here is a batch file for running create. To run it, you will need to be sure you have your [PHONEGAP]\lib\android\bin directory on your path, as described above. Here is the batch file:

set Project=Cordova03
set ProjectSmall=cordova03
create C:\Temp\%Project% com.elvenware.%ProjectSmall% %Project%

Please see this text on running batch files from NotePad++:

NOTE: It seems like Mac users should be able to create your project in your workspace, and then just import it without the Copy Projects into workspace option. This does not, however, seem to work on a PC, which is why we create the project in a temp directory, and then import it.

Running an PhoneGap/Cordova Project from Eclipse

Once you have created the project, you need to import it by selecting File | Import. Now use the Android | Existing Android Code into Workspace option to browse for the root directory of your new PhoneGap project. After importing the project it should be visible in the Project Explorer. If the Project Explorer is not visible, choose Window | Show View | Project Explorer from the menu.

Plug in your Android device, start an Android X86 instance in VirtualBox, or start the Emulator. You have to have the developer options turned on for your device before you can use it for development. There are multiple ways to set up the developer options on an Android device, so I'll ask that you perform an Internet search to find the technique used for your device. There are other, lengthy, sections of this Elvenware site that describe how to set up Android x86 in VirtualBox.

The emulator tends to be monumentally slow, but it is probably the easiest option to setup. To start the emulator:

To Run the project:

Customize the Cordova Create Script

Go to your [dev]/[PhoneGap]/lib/android/bin/templates/project directory.

For instance, here is the path on my system:


Back up the Assets directory. Make sure you have all your environment variables set up as described above, and then run either of the batch files found in the root of this zip file:


(If you are on the Mac, or Linux, for now you can just delete the existing Assets folder, and copy one of the new ones into the place where you made the deletion.

If you open up the zip file you will find that I am simply replacing the index.html, index.js, and index.css files with custom files set up the way I prefer to see them. You will, I'm sure, want to implement changes of your own. Once you see how the system works, you will probably find it easy to modify these to create the effects you prefer. Notice that I delete a number of the files that come with the default package. That is why I suggest that you back up the original content before you delete it. You can, of course, download a new copy of the original PhoneGap templates at any time from the PhoneGap site.

PhoneGap Build

This cloud based service will take your HTML, CSS and JavaScript wrapped up in a zip file and return verisons for Apple iOS, Android, Palm, Symbian, and Blackberry. It is all done in the cloud. Right now the service is free, but it will cost more when they get out of beta.


The Key Steps in Setting up Your Project


  1. Set up Eclipse as you would for normal Android developmen: Eclipse Classic, Androids SDK, ADT
  2. Create a standard Android Project
  3. Ceate libs, xml and /assets/www folders and add
    1. assets/www/phonegap.js,
    2. lib/phonegap.jar,
    3. res/xml/plugins.xml and res/xml/phonegap.xml
  4. Edit manifest and
  5. Create assets/www/index.html

Python Scripts to Automate Android to PhoneGap Conversion

There are several solutions to this problem, but I have written some scripts that help me convert Android applications to PhoneGap. To get started, first be sure that you have installed Python. You might also want to install PyDev, which is a Python development environment in the form of an add on to Eclipse. An alternative would be to install Aptana, which is a version of Eclipse that comes with PyDev built-in.

After installing Python, you should download the two zip files shown below. The first contains the scripts that convert the project, the second contains the core parts of the PhoneGap tools that need to be included in your PhoneGap projects. The scripts should work on Windows, Linux and the Mac.

When you are done, the destDir and srcDir fields might look like this, assuming your workspace is in J:\src\PhoneGap/. Note that the # sign is a comment in Python, and that we use forward slashes rather than back slashes, and that we include a trailing slash at the end of each line:

# Here is an Android project to be converted
destDir = "J:/src/PhoneGap/PhoneGap03/"
# Here is where the files from PhoneGap live

HTML 5 vs Android

HTML 5 Advantages

There are many platforms out there, and targeting HTML 5 gets you to all platforms at once. The idea is to have one platform to target all these devices. Most of the modern phones use WebKit, which fully supports HTML 5.

You can embed web apps inside native apps. People don't want to have to open a browser to open a web app.

HTML 5 is really HTML 5, CSS and JavaScript. It doesn't all work on all platforms, but it works in a wide variety of locations. Graceful degradation helps you work with this problem, in particular because things that are not supported are just ignored.

HTML5 is fluid. It stretches and morphs on different screens even if you don't write platform specific code.

HTML 5 is compelling because it supports:

Native Android Apps

Can be built with Dalvik and Java, or C++, or RenderScript for graphics code. You also have access to Python. These are all Android specific tools.

Native apps are good:

The point here is that there are great features in HTML 5, and great features in native applications. Perhaps you should build a web app for everyone, and then build a native app for successful platorms.

With WebViews you can get a bit of both worlds, have a native app that leverages your HTML5 code.

Some powerful tools, Sproutcore, Sencha touch, jquery mobile, jo, iUI, Modernizr, Polyfills

Using the jQuery ajax Command in PhoneGap

If you use jQuery ajax,or related calls in a PhoneGap application, if you try to use LocalHost in your URL, you are asking to reach the web server of the Android operating system that your application is hosted on. In most cases, there will be no web server on that Phone/OS, and so you will just get an error. If there were a WebServer on the device, it would still likely fail, because your database, data and scripts are probably not on the phone, but back on your web server.

The important thing to grasp here is that an Android emulator or VirtualBox running Android x86 is, for all intents and purposes the same thing as a phone. It is a separate operating system, a separate device from the copy of Windows, Mac, or Linux that is hosting it. That's what we mean by a virtual machine: it is a virtual computer/phone/device hosted by your main OS. It thinks its running on its own device, and so does your web server.

To make things work, you need to create a URL that can be reached from your virtual device, from a real phone. The first thing to test is whether the URL can be reached from the Browser on your computer. As a rule, if the URL does not work on your browser, then it won't work in the virtual device or in a real phone. Remember that you can simulate passing parameters in a URL when testing in the browser:


You don't use the part after the question mark in your PhoneGap program, but you do in your test URL that you run in the browser.

Of course the URL above won't work in the phone, because it references localhost. You need to use the Windows command line utility ipconfig to get the actual IP address of your machine. In my case, it is

An address like that should work in an emulator, in VirtualBox or on your phone. If it does not, that means you don't have your FireWall set up correctly as explained here:



Download Apache Ant:


Read how to install it:




Check the following. Go to the command prompt and confirm that you can run:

You should be able to type java -version and get reasonable output. Make sure that javac.exe is on your path. This usually means putting \jdk\bin on your path.