An Introduction to PhoneGap

This is the first of a series of posts that will focus on using PhoneGap, the free and open source framework for creating mobile applications using web technologies such as HTML, CSS, and JavaScript that will come in handy for game development. In this first article, we will introduce PhoneGap and build a very simple Android application using PhoneGap, the Android SDK, and Eclipse. In a follow-on article, we will look at how you can use PhoneGap and PhoneGap Build to create iOS apps, Android apps, BlackBerry apps, and others from the same web source code. In future articles, we will dive deeper into exploring the various tools and features of PhoneGap that will help you build great mobile applications that perform and function just like native applications.

Before we get into setting up and working with PhoneGap, let’s talk a little bit about what PhoneGap is. PhoneGap was originally developed by a company called Nitobi but was later purchased by Adobe Inc. in 2011. When Adobe acquired PhoneGap, it donated the code of the project to the Apache Software Foundation, which renamed the project to Apache Cordova. While both tools are similar and open source, and PhoneGap is built upon Cordova, PhoneGap has additional capabilities to integrate tightly with Adobe’s Enterprise products, and users can opt for full support and training. Furthermore, Adobe offers PhoneGap Build, which is a web-based service that greatly simplifies building Cordova/PhoneGap projects. We will look at PhoneGap Build in a future post.

Apache Cordova is the core code base that Adobe PhoneGap draws from. While both are open source and free, PhoneGap has a paid-for Enterprise version with greater Adobe product integration, management tools, and support. Finally, Adobe offers a free service called PhoneGap Build that eases the process of building applications, especially for those needing to build for many devices.

Getting Started

For this post, to save space, we are going to jump right into getting started with PhoneGap and Android and spend a minimal amount of time on other configurations. To follow along, you need to install node.js, PhoneGap, Apache Ant, Eclipse, the Android Developer Tools for Eclipse, and the Android SDK. We’ll be using Windows 8.1 for development in this post, but the instructions are similar regardless of the operating system. Installation guides, for any major OS, can be found at each of the links provided for the tools you need to install.

Eclipse and the Android SDK

The easiest way to install the Android SDK and the Android ADT for Eclipse is to download the Eclipse ADT bundle here. Just downloading the bundle and unpacking it to a directory of your choice will include everything you need to get moving.

If you already have Eclipse installed on your development machine, then you should go to this link here, which will let you download the SDK and the Android Development Tools along with instructions on how to integrate the ADT into Eclipse. Even if you have Eclipse, I would recommend just downloading the Eclipse ADT bundle and installing it into your own unique environment. The ADT plugin can sometimes have conflicts with other Eclipse plugins.

Making sure Android tooling is set up

One thing you will need to do, no matter whether you use the Eclipse ADT bundle or not, is to make sure that the Android tools are added to your class path. This is because PhoneGap uses the Android Development Tools and Android SDK to build and compile the Android application. The easiest way to make sure everything is added to your path is to edit your environment variables. To do that, just search for “Edit Environment” and select Edit the system environment variables.

This will open your System Properties window. From there, select Advanced and then Environment Variables as shown in the next figure. Under System Variables, select Path and Edit.

Now you need to add sdkplatform-tools and sdktools  to your path as shown in the next figure. If you have used the Eclipse ADT bundle, your SDK directory should be of the form C:adt-bundle-windows-x86_64-20131030sdk.  If you cannot find your Android SDK, search for your ADT. In our case, the two directory paths we add to the Path  variable are C:adt-bundle-windows-x86_64-20131030sdkplatform-tools  and C:adt-bundle-windows-x86_64-20131030sdktools.

Once you’re done, select OK , but don’t just exit the Environment Variables  screen yet since we will need to do this again when installing Ant.

Installing Ant

PhoneGap makes use of Apache Ant to help build projects. Download Ant from here and make sure to add the bin directory to your path. It is also good to set the environment variable ANT_HOME as well. To do that, create a new variable in the Environment Variables screen under System Variables called ANT_HOME and point it to the directory where you installed Ant:

For more detailed instructions, you can read the official install guide for Apache Ant here.

Installing Node.js

Node.js is a development platform built on Chrome’s JavaScript runtime engine that can be used for building large-scale, real-time, server-based applications. Node.js is used to provide a lot of the command-line tools for PhoneGap, and to install PhoneGap, we first need Node.js. Unix, OS X, and Windows users can find installers as well as source code here on the Node.js download site. For this post, we will be using the Windows 64-bit installer, which you should be able to double-click and install. Once you’re done installing, you should be able to open a command prompt and type npm –version and see something like this:

Installing PhoneGap

Once you have Node.js installed, open a command line and type npm install –g phonegap. Node will now download and install PhoneGap and its dependencies as shown here:

Creating an initial project in PhoneGap

Now that you have PhoneGap installed, let’s use the command-line tools to create an initial PhoneGap project. First, create a folder where you want to store your project. Then, to create a basic project, all you need to do is type phonegap create mytestapp as shown in the following figure. PhoneGap will now build a basic project with a deployable app.

Now go to the directory you are using for your project’s root directory. You should see a directory called mytestapp, and if you open that directory, you should see something like the following:

Now look under platforms>android and you should see something like what is shown in the next figure, which is the directory structure that PhoneGap made for your Android project. Make sure to note the assets directory, which contains the HTML and JavaScript of the application or the Cordova directories that contain the necessary code to tie Android’s API’s to PhoneGap/Cordova’s API calls.

Now let’s import the project into Eclipse. Open Eclipse and select Create a New Project, and select Android Project from Existing Code.

Browse to your project directory and select the platforms/android folder and select Finish, like this:

You should now see the mytestapp project, but you may see a lot of little red X’s and warnings about the project not building correctly. To fix this, all you need to do is clean and build the project again like so:

• Right-click on the project directory.
• In the resulting Properties dialog, select Android from the navigation pane.
• For the project build target, select the highest Android API level you have installed.
• Click on OK.
• Select Clean from the Project menu. This should correct all the errors in the project. If it does not, you may need to then select Build again if it does not automatically build.

Now you can finally launch your project. To do this, select the HelloWorld project and right-click on it, and select Run as and then Android application. You may now be warned that you do not have an Android Virtual Device, and Eclipse will launch the AVD manager for you. Follow the wizard and set up an AVD image for your API. You can do this by selecting Create in the AVD manager and copying the values you see here:

Once you have built the image, you should now be able to launch the emulator. You may have to again right-click on the HelloWorld directory and select Run as then Android application. Select your AVD image and Eclipse will launch the Android emulator and push the HelloWorld application to the virtual image. Note that this can take up to 5 minutes! In a later post, we will look at deploying to an actual Android phone, but for now, the emulator will be sufficient. Once the Android emulator has started, you should see the Android phone home screen. You will have to click-and-drag on the home screen to open it, and you should see the phone launch pad with your PhoneGap HelloWorld app. If you click on it, you should see something like the following:

Summary

Now that probably seemed like a lot of work, but now that you are set up to work with PhoneGap and Eclipse, you will find that the workflow will be much faster when we start to build a simple application. That being said, in this post, you learned how to set up PhoneGap, how to build a simple application structure, how to install and set up Android tooling, and how to integrate PhoneGap with the Eclipse ADT. In the next post, we will actually get into making a real application, look at how to update and deploy code, and how to push your applications to a real phone.

About the author

Robi Sen, CSO at Department 13, is an experienced inventor, serial entrepreneur, and futurist whose dynamic twenty-plus year career in technology, engineering, and research has led him to work on cutting edge projects for DARPA, TSWG, SOCOM, RRTO, NASA, DOE, and the DOD. Robi also has extensive experience in the commercial space, including the co-creation of several successful start-up companies. He has worked with companies such as UnderArmour, Sony, CISCO, IBM, and many others to help build new products and services. Robi specializes in bringing his unique vision and thought process to difficult and complex problems, allowing companies and organizations to find innovative solutions that they can rapidly operationalize or go to market with.