For a full overview of PhoneGap, I suggest reading this article by Kyle Miller. One of the things I like about PhoneGap that Kyle does not mention is that PhoneGap has the Apache licence; that means there are no roadblocking requirements to developing commercial software, and there are no fees attached unlike some of PhoneGap’s competitors.

As an aside, PhoneGap is becoming an Apache project and will be called Apache Callback.

To get started with PhoneGap we must first have an environment compatible with PhoneGap, as it does not provide a standard environment for development. For iOS apps you must have XCode, Eclipse is recommended for Android, and for BlackBerry you will need Ant and WebWorks.

Since we are focusing on Android, we will need to install Eclipse and the Android SDK.

PhoneGap recommends Eclipse Classic and should be easy enough to get your hands on and install.

Next, download and unpack or install the Android SDK and the ADT plug-in.

Once the Android SDK is unpacked, run the Android SDK manager (tools/android script in my case) and select the SDKs to download and install. You’ll want to install the new 4.0 (API 14) release; possibly API 13 and/or 12, which are Honeycomb builds, so when it’s simulated, they will have a large widescreen appearance; and API 10, which is Android 2.3.3, the version of Android on many phones currently — probably the version of Android that you recognise.

I’d suggest leaving the downloading and installing of Android overnight, it does take an awful long time.

Now I ran into a bit of an issue installing the ADT. Eclipse complained about the lack of org.eclipse.wst.sse.core and refused to install the plug-in, this was a result of my version of Eclipse (indigo) not being in the available software sites.

A bit of googling resulted in this solution, after which the ADT plug-in installed fine.

Finally, we are actually ready to start coding.

Open up Eclipse and start a new project, select Android Project from the Android folder. When selecting a build target, I chose Android 2.3.3, which we can run under the newer version of Android later on if we want.

At this point, to make sure that our default Eclipse and Android environment is fine, click on run to load up a basic Hello World output.

You will need to create an Android Virtual Device now, so make one that matches your minimum SDK version.

To start using PhoneGap we need to copy in the libraries that it uses. Take the Android/phonegap-x.y.z.jar file in the directory that you extracted PhoneGap to, and put it into the /libs directory of your project. You will have to create this directory. Once the file is pasted into the directory, right-click on the jar file in the Project Explorer and add it to the build path of the project.

Within the /assets folder, create a www folder and inside that folder, an index.html file. Fill the html file with whatever dummy code you desire, we are only testing the environment again at this point. You will also need to copy into this file Android/phonegap-x.y.z.js for later use.

Also copy the Android/xml folder from the PhoneGap extraction directory to the xml folder in your project.

In the project’s AndroidManifest.xml file add the following line inside the tags:

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

Lastly, we need to update the java file in the project’s /src directory to load PhoneGap.

  • Add import com.phonegap.*;
  • Make the public class extend DroidGap rather than Activity
  • Comment out setContentView(R.layout.main); and add a new line that has
    super.loadUrl(“file:///android_asset/www/index.html”);

Now let’s run the project again and see our PhoneGap app in action.

If you get an error stating:java.lang.IllegalArgumentException: already added: Lcom/phonegap/AccelListener; I fixed this by cleaning the project.

We have success at getting the bare minimum going with PhoneGap. It took a while to get here, but now we are starting to do useful coding. Stay tuned for that instalment.