PhoneGap is an open source framework for building cross-platform mobile applications with HTML, CSS, and JavaScript. This is an ideal solution for web developers interested in mobile development as it allows them to leverage existing skills rather than start form scratch with a device-specific compiled language. This is also an ideal solution for those interested in creating an application that can run on multiple devices with the same code base. In this tutorial, you will learn how to setup the PhoneGap development environment and learn some of the fundamental development considerations of the platform.
Introducing PhoneGap
Applications built with PhoneGap are not just like normal mobile web sites. PhoneGap applications are able to interact with mobile device hardware, such as the Accelerometer or GPS, in ways that are unavailable to normal web applications. PhoneGap applications are also built and packaged like native applications, meaning that they can be distributed through the Apple App Store or the Android Market.
PhoneGap supports a number of different mobile platforms, including:
- Android
- iPhone
- Blackberry
- Symbian
- Palm
The PhoneGap SDK provides an API that is an abstraction layer providing the developer with access to hardware and platform specific features. As PhoneGap abstracts the native mobile platform, the same code can be used on multiple mobile platform with little or no change, making your application available to a wider audience.
Hardware specific features supported by the PhoneGap API include:
- Geolocation
- Vibration
- Accelerometer
- Sound
Requirements:
In order to create applications with PhoneGap, you will need to first install the standard SDK for the mobile platforms you want to target for your app. This is because PhoneGap will actually use these SDKs when compiling your app for that platform.
So, if you are developing for Android, you will need:
- Android NDK
- Android SDK
There are also some additional PhoenGap specific requirements for Android development, including:
- Eclipse IDE
- ADT plugin for Eclipse
- Apache Ant
- Ruby
- Git Bash (Windows Only)
The PhoneGap Android documentation provides the complete list of requirements with install instructions for each.
If you are developing for the iPhone, you will need:
- An intel-based Apple Computer
- iPhone SDK
- Xcode
- Mac OS X Snow Leopard
Read our Introduction to iPhone Development tutorial for more information on setting up an iPhone development environment.
Once you have downloaded and unzipped phonegap, you will see it contains one separate folder for each platform supported by PhoneGap:
PhoneGap comes with a default application that can be used to showcase the powerful functionality of the SDK. The rest of this tutorial will be dedicated to showing you how to setup this default app for both Android and iPhone.
Building the Default PhoneGap App for Android
To create a workspace for your PhoneGap app on android, go to the "phonegap-android" folder on the command prompt or terminal.
Run the following command:
1 |
|
2 |
ruby ./droidgap "[android_sdk_path]" [name] [package_name] "[www]" "[path]" |
- android_sdk_path - Path where you installed the Android SDK.
- name - The name to give the new application.
- package_name - The name you want to give to your application.
- www - The folder from where you want to copy the files of your PhoneGap app. Leave this blank for now.
- path - The application workspace for your project.
Once this command runs successfully the application workspace will be generated in the path you have given. Then you can open you Eclipse and first choose "New Android Project" and then choose "Create From Existing Source" and select the application work space which was created with the previous command.
Once that is done, copy the following files from the phonegap/phonegap-android/example folder to the www folder in your workspace:
- Index.html
- Master.css
Then click on run to see the phonegap example app in the android simulator.
Building the Default PhoneGap App for iPhone
To create a PhoneGap app for iPhone go to the phonegap-iphone folder where you unzipped the PhoneGap files.
Once you are in that folder in your terminal type ‘make’ to build PhoneGapLibInstaller.pkg.
Then you will have to run PhoneGapLibInstaller.pkg which will install the PhoneGapLib and the PhoneGap template in Xcode.
Then you can launch Xcode and create a ‘New Project’. Then choose PhoneGap based application template.
Next, copy the following files into the www folder of your workspace:
- Index.html
- Master.css
Run the application to launch the demo PhoneGap app in the iPhone Simulator.
Behind the Scenes (In Code)
So now you have got the demo PhoneGap app running on your simulator. You can play around with the app and see how it performs. This basic app shows general use of the different API's exposed
by the PhoneGap SDK.
Go ahead and open index.htm. At the top of the page you will see the following code:
1 |
|
2 |
<title>PhoneGap</title> |
3 |
|
4 |
<link rel="stylesheet" href="master.css" type="text/css" media="screen" title="no title" charset="utf-8"> |
5 |
|
6 |
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script> |
The first thing is a link to master.css which gives all the style to the button you seen on screen.
The second line includes phonegap.js which is generated when we have created a workspace for our application. This file does all the magic of calling the native APIs through JavaScript.
Now if you scroll to the end of index.html you will see the following code:
1 |
|
2 |
|
3 |
<body onload="init();" id="stage" class="theme"> |
4 |
|
5 |
<h1>Welcome to PhoneGap!</h1> |
6 |
|
7 |
<h2>this file is located at assets/index.html</h2> |
8 |
|
9 |
<div id="info"> |
10 |
|
11 |
<h4>Platform: <span id="platform"> </span></h4> |
12 |
|
13 |
<h4>Version: <span id="version"> </span></h4> |
14 |
|
15 |
<h4>UUID: <span id="uuid"> </span></h4> |
16 |
|
17 |
</div>
|
18 |
|
19 |
<dl id="accel-data"> |
20 |
|
21 |
<dt>X:</dt><dd id="x"> </dd> |
22 |
|
23 |
<dt>Y:</dt><dd id="y"> </dd> |
24 |
|
25 |
<dt>Z:</dt><dd id="z"> </dd> |
26 |
|
27 |
</dl>
|
28 |
|
29 |
<a href="#" class="btn large" onclick="watchAccel();">Watch Accelerometer</a> |
30 |
|
31 |
<a href="#" class="btn large" onclick="getLocation();">Get Location</a> |
32 |
|
33 |
<a href="tel://411" class="btn large">Call 411</a> |
34 |
|
35 |
<a href="#" class="btn large" onclick="beep();">Beep</a> |
36 |
|
37 |
<a href="#" class="btn large" onclick="vibrate();">Vibrate</a> |
38 |
|
39 |
<a href="#" class="btn large" onclick="show_pic();">Get a Picture</a> |
40 |
|
41 |
<a href="#" class="btn large" onclick="get_contacts();">Get phone's contacts</a> |
42 |
|
43 |
<div id="viewport" class="viewport" style="display: none;"> |
44 |
|
45 |
<img style="width:60px;height:60px" id="test_img" src="" /> |
46 |
|
47 |
</div>
|
48 |
|
49 |
</body>
|
This HTML creates the links that are shown as buttons on your mobile device screen. There are onclick handlers attached to these links which call JavaScript functions defined in the same file that are responsible for calling the PhoneGap API to interact with the device native hardware.
The first function to be called in JavaScript is init(). This will register our JavaScript function deviceInfo to the PhoneGap event.
Deviceready Event
The deviceready event is fired by PhoneGap when all the SDK components are loded properly. It makes sense then that the JavaScript API's of PhoneGap should be used after this event fires.
You can read more about deviceready in the API documentation.
Device Object
The device object contains basic information about the device the app is running on, like the platform, the version etc. These values can be used to perform device specific checks in your code.
You can read more about the device object in the official API documentation.
Accelerometer
The first link in the body calls the watchAccel function:
1 |
|
2 |
<a href="#" class="btn large" onclick="watchAccel();">Watch Accelerometer</a> |
This portion of the API watches and sends notifications about device acceleration at regular intervals. It returns the present acceleration of the device by passing the x, y, and z coordinates to the callBackonSuccess function registered. The x, y, z values can then be used in the application to respond to movement.
Read more about the accelerometer here.
GPS & Positioning
The second link in the body is responsible for gathering the current device location:
1 |
|
2 |
<a href="#" class="btn large" onclick="getLocation();">Get Location</a> |
The callBackonSuccessfunction is passed an object that contains the GPS coordinates which can be used in your application to perform location based processing.
You can read more about the Geolocation API.
Making Calls
The third line in the body will launch the device dialer with the number "411":
1 |
|
2 |
<a href="tel://411" class="btn large">Call 411</a> |
Device Notifications
The next two lines in the body are used to beep or vibrate a device:
1 |
|
2 |
<a href="#" class="btn large" onclick="beep();">Beep</a> |
3 |
<a href="#" class="btn large" onclick="vibrate();">Vibrate</a> |
Read more about beep and vibrate in the official docs.
Using the Camera
The next line in the body calls the function show_pic to take a photo:
1 |
|
2 |
<a href="#" class="btn large" onclick="show_pic();">Get a Picture</a> |
This api launches the devices camera application and waits
for user to capture an image.
Read more about taking photos in the official API documentation.
Conclusion
PhoneGap is a very powerful framework for cross-platform development. If you have already have a strong web development background and are interested in building apps for one or many devices, PhoneGap is surely a strong contender to consider!
