PhoneGap From Scratch: Introduction

Want to learn how to use PhoneGap, but don’t know where to get started? Join us as we put together “Sculder”, not only a tribute to an excellent science fiction TV series, but a fully-fledged native mobile application for the believer in you!

In this series, we will build a mobile application using some of the features in PhoneGap. We will go from installation of the SDK to deployment into the app stores of the two major platforms: iOS and Android. Concepts covered in this series will include accessing the device camera, local storage, and geolocation.

In this first part, we will take a quick look at what PhoneGap actually is and what you can use it for, and then look at the installation of the PhoneGap framework and the SDKs that we require for testing on OS X, Windows, and Linux environments. We will then build and run the very simple “Hello World” PhoneGap application to ensure that we have everything running correctly.

What is PhoneGap?

By now you probably have a good idea of what PhoneGap is and you’ve probably even used it, but, if not, here’s a brief overview.

PhoneGap was born out of iPhoneDevCamp in 2008, where it was created simply because there were not a lot of Objective-C developers in comparison to Web Developers. The challenge was to put together a framework that would allow web developers to use HTML, CSS, and JavaScript to code applications that could take advantage of the native functionality of the mobile device, such as the Camera, Storage, and GeoLocation features. Initially built to work with the iPhone, within a year PhoneGap was growing and beginning to support Android too. Now, nearly 4 years old, PhoneGap is one of the most talked about toolkits for developing mobile applications and supports a much wider range of mobile devices including iOS, Android, Blackberry, Symbian, webOS, WP7, and Bada.

At the time of publication (e.g. January, 2012), the framework currently supports the Accelerometer, Camera, Compass, Contacts, File, Geolocation, Media, Network, Notifications (Alert, Sound, and Vibrate) and Storage device APIs. There is full support for all of these features in the newer iOS Devices (3GS+) and Android. For more details on support for Blackberry, WP7, Sybian, webOS, and Bada devices check the official compatibility table.

Despite contrary belief, PhoneGap is not a write once, deploy everywhere solution (although it does come close). It is certainly a cross-platform framework capable of running on many supported devices, but in order to deploy successfully you will likely need to test and tweak your code on each of the target devices.

Install & Hello World for iOS

If you want to develop for iOS, you will need an Intel based computer running MAC OS X version 10.6 or later. You will also need the latest version of Xcode (version 4 at the time of writing), and the iOS SDK for testing. In order to download Xcode, you’ll need to sign up as a member of the Apple Developer Program.

Head over to www.phonegap.com and in the top left hand corner you will see a button to download the latest version of PhoneGap. Clicking on this will prompt the download of a ZIP file containing everything you need to get started.

Unzipping the file will give you numerous folders, each labelled with the targeted OS. As we are installing for iOS, open up the iOS folder and mount the dmg file. The dmg contains a pkg file. Click this and go through the installation process. After completing the install, you can go ahead and start up Xcode and when you come to create a new project, you should be able to choose PhoneGap as a template.

We can now set the options for our project and the location of our files. Once we’ve done that, our project is built in the directory specified and Xcode presents us with our summary page. Here we can easily add app icons and change a couple of the settings when our application is ready to be packaged and submitted to the app store – for now we will just go ahead and hit RUN in the top left hand corner. This will compile the app and fire up the iOS simulator.

If you try this now, after the splash screen you should get an error stating that the index.html file could not be found. No need to worry, this is actually what should happen. We need to go the the working directory for the project (Right click on the project in Xcode and click show in finder) and there we will see a www directory in the project root.

We now need to drag that directory INTO Xcode and add it to the project.

In the options for these files we need to make sure that we select “Create folder reference for any added folders”, then click finish. Our www directory is now added to the project. We can now click run again and you will get the basic ‘Hello World’ for PhoneGap.

The www directory will now be our root directory for the app. This is where we will keep any HTML, CSS, or JavaScript that is going to be used by our app, just like you would expect for any other web application. The phonegap.js file is the JavaScript file that will act as our API, giving us access to the native APIs we might want to use in our application later.

Install & Hello World for Android

Unlike developing for iOS, you are able to develop for Android on any platform. Although it is advised that you use the Eclipse IDE with a couple of plugins, there is an alternative way to use PhoneGap (via Command Line), but it’s good if you start by doing it the longer way first with an IDE and then try out the command line way and see which one you prefer. In this tutorial we will be using the IDE method.

First, you are going to have to head to the Eclipse website and download the IDE for your platform of choice. The classic version is fine for what we need. Once downloaded, start Eclipse and we need to install the ADT plugin. You need to go to Help => Install New Software and click add in the right hand corner.

You then can enter ADT Plugin for the plugin name and enter the following for the repository URL.

https://dl-ssl.google.com/android/eclipse/

The plugin will download and install and Eclipse will prompt you to restart. Once it restarts you can create a new Android project.

You will then go through the project wizard where you will give your app a name and set up its workspace. you will also select your build target SDK – you can select the latest one for now (4.0.3 at the time of writing). Go through the rest of the wizard and set up the remaining information for the app.

You will be asked if you wish to download and install the required Android SDKs at this point. If you already have them on your machine, go ahead and browse to the folder. If not, you can let Eclipse download them for you.

Within the root directory of the application we need to create a directory called lids and within the assets directory create another directory called www. Now, back to the original PhoneGap file that was downloaded and in the Android folder you need to copy the phonegap.jar file to the libs directory we created and then copy the phonegap.js to the www directory.

Your structure should look like the following:

Within our www directory, create an index.html file and drop in the code below:

<!DOCTYPE HTML>
<html>
  <head>
    <title>mobiletuts phonegap</title>
  <script src="phonegap-1.2.0.js"></script>
  <script>
     function onLoad(){
          document.addEventListener("deviceready", onDeviceReady, true);
     }
     function onDeviceReady(){
          navigator.notification.alert("PhoneGap is working!!");
     }
  </script>
  </head>
  <body onload="onLoad();">
       <h1>Welcome to PhoneGap</h1>
       <h2>Edit assets/www/index.html</h2>
  </body>
</html>

Now we need to make some changes to the main Java file that can be found in the src folder. First, we need to change the class’ extend from Activity to DroidGap.. We then need to replace setContentView(R.layout.main); with super.loadUrl("file:///android_asset/www/index.html"); and then add import com.phonegap.*; after the first two imports. Your Java file upon completion should look something like this:

package com.shaundunneTest;
import android.app.Activity;
import android.os.Bundle;
import com.phonegap.*;
public class TestActivity extends DroidGap {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        super.loadUrl("file:///android_asset/www/index.html");
    }
}

Eclipse will probably be throwing some errors now, just right click on the libs folder and go to Build Path => Configure Build Path and then in the libraries tab, click add JAR and go ahead and include the phonegap.jar file. This should clear up the errors. Now, we need to add some permissions to the manifest file to ensure that PhoneGap will run correctly.

Open up the AndroidManifest.xml file and add the following before the application entry:

<supports-screens
        android:largeScreens="true"
        android:normalScreens="true"
        android:smallScreens="true"
        android:resizeable="true"
        android:anyDensity="true"
        />
        <uses-permission android:name="android.permission.CAMERA" />
        <uses-permission android:name="android.permission.VIBRATE" />
        <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
        <uses-permission android:name="android.permission.ACCESS_LOCATION_EXTRA_COMMANDS" />
        <uses-permission android:name="android.permission.READ_PHONE_STATE" />
        <uses-permission android:name="android.permission.INTERNET" />
        <uses-permission android:name="android.permission.RECEIVE_SMS" />
        <uses-permission android:name="android.permission.RECORD_AUDIO" />
        <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
        <uses-permission android:name="android.permission.READ_CONTACTS" />
        <uses-permission android:name="android.permission.WRITE_CONTACTS" />
        <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
        <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

On the activity tag, add the following attribute:

	android:configChanges="orientation|keyboardHidden"

This ensures that the app doesn’t reload the index.html anytime those events happen.

The last thing to do is copy the xml folder from the PhoneGap download to the res directory in the project. You are now ready to run this in the emulator.

You can right-click your project now and run as an Android Application. If you haven’t set up a device yet, you will be prompted to do so, if you need help doing this, check out the documentation here

And that’s all you need to get started on Android!

What About All the Other Platforms?

So far, we have covered only two of the mobile platforms for our application, but it is likely that we would want to distribute across all the platforms that PhoneGap supports, right? Well, rather than go through installing a few more SDKs, another IDE with a few more plugins, and setup a Virtual Machine for testing, this series will use the PhoneGap:Build service when it comes time to distribute the app.

PhoneGap:Build, as it states on the website, is a cloud based service that will take a zipped up HTML/CSS/JS application and send you back the application, compiled and ready to go for distribution (one caveat: for Android, iOS, and BB you will need the required certificates for Distribution). PhoneGap:Build is in BETA at the moment, and while there are paid options (which are well worth having if you are going to be using it regularly), there is a free option that will allow one private application. That’s all we need for our project a the moment, so go ahead and sign up now as we will be using the Build service at the end of the series.

Concluding Remarks

We now have our environment ready for development with PhoneGap. In the next part of this series, we will start looking at the APIs that PhoneGap allows us to access and how to use them in our app.