introduction to phonegap development

Mobiletuts+

AdvertiseWrite for UsAboutUsageBuy & Sell Code Snippets

HomeTutorials

Adobe FlashAndroidCorona SDKiOS SDKMobile DesignMobile Web AppsPhoneGapSMSTitanium MobilewebOSWindows Phone 7

ArticlesMarketingNewsQuizzesTheory

TipsAndroidMarketingiOS SDK

SessionsBasix

iOS SDKAndroid

Premium

Plus Premium

Psdtuts+ Adobe PhotoshopNettuts+ Web DevelopmentVectortuts+ Illustrator and VectorAudiotuts+ Audio and ProductionAetuts+ Adobe After EffectsCgtuts+ Computer GraphicsActivetuts+ Flash, Flex, and ActionScriptPhototuts+ PhotographyMobiletuts+ Mobile DevelopmentWebdesigntuts+ Web DesignWptuts+ WordPress

Toggle

Subscribe

Introduction to PhoneGap Development http://mobile.tutsplus.com/tutorials/phonegap/phonegap-development/

1 of 24 12/28/2011 12:29 PM

Full Post RSSSummary RSSSubscribe via Email

Twitter UpdatesMobiletuts+Plus Network

Advertise Here

basix

Basix\PhoneGap

\Rating:

12345

Introduction to PhoneGap DevelopmentAbbas Suterwala on Sep 3rd 2010 with 32 comments

Tutorial Details

Technology: PhoneGapDifficulty: BeginnerEstimated Completion Time: 30 - 45 Minutes

Tweet


2 of 24 12/28/2011 12:29 PM

PhoneGap is an open source framework for building cross-platform mobile applications with HTML, CSS, andJavaScript. This is an ideal solution for web developers interested in mobile development as it allows them toleverage existing skills rather than start form scratch with a device-specific compiled language. This is also anideal solution for those interested in creating an application that can run on multiple devices with the same codebase. In this tutorial, you will learn how to setup the PhoneGap development environment and learn some of thefundamental development considerations of the platform.

Introducing PhoneGap

Applications built with PhoneGap are not just like normal mobile web sites. PhoneGap applications are able tointeract with mobile device hardware, such as the Accelerometer or GPS, in ways that are unavailable to normalweb applications. PhoneGap applications are also built and packaged like native applications, meaning that theycan be distributed through the Apple App Store or the Android Market.

PhoneGap supports a number of different mobile platforms, including:

AndroidiPhoneBlackberrySymbianPalm

The PhoneGap SDK provides an API that is an abstraction layer providing the developer with access tohardware and platform specific features. As PhoneGap abstracts the native mobile platform, the same code canbe used on multiple mobile platform with little or no change, making your application available to a wideraudience.

Hardware specific features supported by the PhoneGap API include:

GeolocationVibrationAccelerometerSound

Requirements:

In order to create applications with PhoneGap, you will need to first install the standard SDK for the mobileplatforms you want to target for your app. This is because PhoneGap will actually use these SDKs whencompiling your app for that platform.

So, if you are developing for Android, you will need:

Android NDKAndroid SDK

There are also some additional PhoenGap specific requirements for Android development, including:

Eclipse IDEADT plugin for Eclipse

76Like


3 of 24 12/28/2011 12:29 PM

Apache AntRubyGit Bash (Windows Only)

The PhoneGap Android documentation provides the complete list of requirements with install instructions foreach.

If you are developing for the iPhone, you will need:

An intel-based Apple ComputeriPhone SDKXcodeMac OS X Snow Leopard

Read our Introduction to iPhone Development tutorial for more information on setting up an iPhonedevelopment environment.

Once you have downloaded and unzipped phonegap, you will see it contains one separate folder for eachplatform 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 andiPhone.

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 commandprompt or terminal.

Run the following command:

ruby ./droidgap "[android_sdk_path]" [name] [package_name] "[www]" "[path]"1.

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 fornow.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


4 of 24 12/28/2011 12:29 PM

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 wwwfolder in your workspace:

Index.htmlMaster.css

Then click on run to see the phonegap example app in the android simulator.

Building the Default PhoneGap App for iPhone


5 of 24 12/28/2011 12:29 PM

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 PhoneGaptemplate 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.htmlMaster.css

Run the application to launch the demo PhoneGap app in the iPhone Simulator.


6 of 24 12/28/2011 12:29 PM

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 andsee how it performs. This basic app shows general use of the different API’s exposedby the PhoneGap SDK.


7 of 24 12/28/2011 12:29 PM

Go ahead and open index.htm. At the top of the page you will see the following code:

view plaincopy to clipboardprint?

<title>PhoneGap</title>1.2.

<link rel="stylesheet" href="master.css" type="text/css" media="screen" title="no title" charset="utf-8">3.4.

<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>5.

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:


<body onload="init();" id="stage" class="theme">1.2.

<h1>Welcome to PhoneGap!</h1>3.4.

<h2>this file is located at assets/index.html</h2>5.6.

<div id="info">7.8.

<h4>Platform: <span id="platform"> </span></h4>9.10.

<h4>Version: <span id="version"> </span></h4>11.12.

<h4>UUID: <span id="uuid"> </span></h4>13.14.

</div>15.16.

<dl id="accel-data">17.18.

<dt>X:</dt><dd id="x"> </dd>19.20.


8 of 24 12/28/2011 12:29 PM

<dt>Y:</dt><dd id="y"> </dd>21.22.

<dt>Z:</dt><dd id="z"> </dd>23.24.

</dl>25.26.

<a href="#" class="btn large" onclick="watchAccel();">Watch Accelerometer</a>27.28.

<a href="#" class="btn large" onclick="getLocation();">Get Location</a>29.30.

<a href="tel://411" class="btn large">Call 411</a>31.32.

<a href="#" class="btn large" onclick="beep();">Beep</a>33.34.

<a href="#" class="btn large" onclick="vibrate();">Vibrate</a>35.36.

<a href="#" class="btn large" onclick="show_pic();">Get a Picture</a>37.38.

<a href="#" class="btn large" onclick="get_contacts();">Get phone's contacts</a>39.40.

<div id="viewport" class="viewport" style="display: none;">41.42.

<img style="width:60px;height:60px" id="test_img" src="" />43.44.

</div>45.46.

</body>47.

This HTML creates the links that are shown as buttons on your mobile device screen. There are onclick handlersattached to these links which call JavaScript functions defined in the same file that are responsible for calling thePhoneGap 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 thePhoneGap event.

Deviceready Event

The deviceready event is fired by PhoneGap when all the SDK components are loded properly. It makes sensethen 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, theversion 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:



9 of 24 12/28/2011 12:29 PM

<a href="#" class="btn large" onclick="watchAccel();">Watch Accelerometer</a>1.

This portion of the API watches and sends notifications about device acceleration at regular intervals. It returnsthe present acceleration of the device by passing the x, y, and z coordinates to the callBackonSuccess functionregistered. 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:


<a href="#" class="btn large" onclick="getLocation();">Get Location</a>1.

The callBackonSuccessfunction is passed an object that contains the GPS coordinates which can be used in yourapplication 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″:


<a href="tel://411" class="btn large">Call 411</a>1.

Device Notifications

The next two lines in the body are used to beep or vibrate a device:


<a href="#" class="btn large" onclick="beep();">Beep</a>1.<a href="#" class="btn large" onclick="vibrate();">Vibrate</a>2.

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:


<a href="#" class="btn large" onclick="show_pic();">Get a Picture</a>1.

This api launches the devices camera application and waitsfor 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


10 of 24 12/28/2011 12:29 PM

development background and are interested in building apps for one or many devices, PhoneGap is surely astrong contender to consider!

Tags: AndroidBasixiOS SDKPhoneGap

Enjoyed this Post?

Subscribe to our RSS Feed, Follow us on Twitter or simply recommend us to friends and colleagues!

Tweet

By Abbas Suterwala

Rollover to read this author's bio or click through to see a full list of posts by this author.

I am Abbas Suterwala, a software engineer by profession and a passionate coder. I live every moment at thefullest. I love open source projects and mobile development, and I am especially interested in WordPress asblogging platform. When I am not chilling around with friends, I stay occupied with one of the following opensource projects I have done: Choomantar [Steganography ] (http://code.google.com/p/choomantar/), the BrowserCounter WordPress plugin (http://wordpress.org/extend/plugins/browser-counter/), and Google Buzz FromAdmin(http://wordpress.org/extend/plugins/google-buzz-from-admin/).

Like 76 people like this. Be the first of your friends.

76Like


11 of 24 12/28/2011 12:29 PM

Plus Premium

Premium Members

Source Files, Bonus Tutorials & More for all relevant Tuts+ sites in one subscription. Join Now

Add Comment

Discussion 32 Comments

Philo Hermans says:September 3, 2010 at 10:30 am

Great article! Just started with Titanium, but I think PhoneGab is easier! :)Will try it out! :)

Reply

1.

Phil says:September 4, 2010 at 6:14 am

Nice one

Reply

2.

Wayne R. says:September 6, 2010 at 8:28 am

Has anyone gotten the demo app to work? I have gone through this article and followed the link for the

3.


12 of 24 12/28/2011 12:29 PM

Android documentation and I cannot get the sample code to generate. I keep getting build errors and theoutput log wont tell me what they are, I only see “BUILD ERROR” then my prompt.

running Snow Leopard, Ruby 1.9, Ant, Android SDK 2.2 the latest NDK, Eclipse Heilios and the ADT Ihave made Android apps in the past so I know my eclipse setup is fine. I just cant get PhoneGap running.

I also tried the droidgap gen / droidgap create and it’s still not working.

Reply

Abbas Suterwala says:September 7, 2010 at 1:05 pmAuthor

Hi Wayne ,

Are you getting the build error after opening the workspace in eclipse.If that is the case ou might not have added phonegap.jar as an external library in you project .You can add that , that might resolve your build error .

Reply

tzs007 says:September 6, 2010 at 2:35 pm

Hi!

Phonegap’s install is annoying. I did the step by step install on Win7, but when I reached the 4A point onthe guide (http://phonegap.pbworks.com/Getting-started-with-Android-PhoneGap-in-Eclipse) I got anerror message: :29: in ‘require’ no such file to load — c:/phonegap/android/bin/lib/generate.rb

Yes, I figured out, I try run the .rb script from c:/phonegap/android/bin BUT THE GUIDE SAID IT!!!

WTF? If i change the folder to the c:/phonegap/android the installer is not find the droidgap.rb

How can I install PG?

@Philo: Maybe the PG is easier, but the Titanium is installable:)

Reply

Abbas Suterwala says:September 7, 2010 at 1:02 pmAuthor

Hi tzs007,

4.


13 of 24 12/28/2011 12:29 PM

In the bin directory you will have to run

ruby ./droidgap “[android_sdk_path]” [name] [package_name] “[www]” “[path]”Does your this command create a PhoneGap workspace properly .

Regards ,

Abbas.

Reply

tzs007 says:September 21, 2010 at 4:12 am

Thx Abbas. But I did that. But IMHO in the droidgap file somethings wrong when call thegenerate file from the /lib.

Kevin Groenendaal says:September 18, 2010 at 10:20 am

Been trying to get an Iframe working on a PhoneGap based application but with no luck. PhoneGap sendme to Safari Mobile whenever a iframe tag is imported ( Most likely have to do with the src=http://.htmlatribute )

Does anyone know a decent workaround? Maybe java perhaps?

Thanks

Reply

Dale Hurley says:October 16, 2010 at 7:25 pm

You could you a div and AJAX to display the data you would of put in the iFrame. This allows youto apply your own style to.

Reply

Steve H says:February 22, 2011 at 4:11 am

Hi,

5.


14 of 24 12/28/2011 12:29 PM

When using PhoneGap for iOS, you’re not allowed to just dump a public website in an iFrame. Theapplication must have a shell which works regardless of whether the device has network access ornot. For an example but the phone into Aeroplane mode and access Maps. Part of the approvalprocess when PhoneGap was fighting for validity was to stop public websites being displayed.Hence the need to redirect all http resources to Safari. Although I have discovered on iOS if you usewindow.location to set the source you can negate the problem. Although this is likely to get your apprejected.

Apple don’t like public websites in applications as it makes it impossible to enforce policies relatingto content. A childs game could be changed to adult content post submission and apple would beunaware.

You should be developing the application as pure html files included within the application. You canget data from public websites using AJAX although you’re have to configure a cross domain policy.

Reply

youmna chamcham says:November 8, 2011 at 1:15 am

Hi Steve,

I’m trying to get google calendar to work on a phonegap app.of course it’s not working in iframe.any other way you would recommend to do it?Thank you,Youmna

Totto says:September 22, 2010 at 2:15 pm

Got into problem with starting the default demo application on PhoneGap – with missing phonegap.jar fileafter the ruby bild. After some digging it got out that the problem was with the Ruby version – I hadinstalled the latest 1.9.2. With the previous Ruby 1.9.1 the build got finally fine and the demo app ransuccessfully following the instruction on the PhoneGap Getting Started Guide.

So has to dig deeper into what is like programming mobile applications with Titanium Appcelerator vs.with PhoneGap to continue with one of them. If anyone can share personal experience with pros and cons,let’s do it – would be very helpful. Also if you’ve found articles on the topic, share them too.

Reply

Aphtk says:October 6, 2010 at 1:56 pm

6.


15 of 24 12/28/2011 12:29 PM

Thanks soooo much for that answer …. trying it out now !

Reply

aphtk says:October 6, 2010 at 2:01 pm

No joy with Ruby 1.9.1

C:/Ruby191/lib/ruby/1.9.1/fileutils.rb:1265:in `initialize’: No such file or directory – C:/phonegap/phonegap-android/framework/phonegap.jar (Errno::ENOENT)

Reply

Douglas Bonneville says:December 4, 2010 at 11:56 pm

Where are the HTML files for the IOS version? I double-clicked the pkg, and started a new project basedon it in XCode but don’t see any “index” or “master” files. There is one template HTML file I see, butnothing else. Maybe I’m just overlooking it?

Reply

liquidws says:December 12, 2010 at 6:04 pm

i got the same problem.

Reply

7.

Miguel Costa says:December 29, 2010 at 7:14 am

For those of you who are loosing time trying to put Phonegap and Android SDK running on Windows, mypiece of advice:just forget it and do it on Linux (or Mac): it’s much more quick and easy.

Trust me ;-)

Reply

Deepu says:

8.


16 of 24 12/28/2011 12:29 PM

February 10, 2011 at 11:22 am

yes i agree with u… :)

Reply

Sinan KUTAS says:February 21, 2011 at 10:49 am

What is most popular application area of PhoneGap ?

Reply

9.

Rajesh says:April 20, 2011 at 8:23 am

Hi,

i would like to know the following details.

1. We have build the helloworld app on Android , how do I build for iPhone( like write oncedeployanywhere).2.Is there any SDK or API document? ( ex: Application.ViewStack need to find out the property details.

Could you please let us know.

Thanks & Regards,Rajesh. S

Reply

10.

Preet says:May 10, 2011 at 1:00 am

Hi,

Is there any way to display 2 splash screens by giving time duration while loading iPhone app inphonegapdelegate.m. Because my app is quite heavy and takes 12-15 secs to load. Could you please givesome code sample.

Thanks

Reply

11.


17 of 24 12/28/2011 12:29 PM

oyelakin festus says:May 12, 2011 at 8:43 am

i so much like and appreciate this, please can any one email this to my mail address.

Reply

12.

aswin sayeeraman says:June 2, 2011 at 6:00 am

fantastic article for beginners………………cool ……………….keep going

Reply

13.

Lukas says:July 7, 2011 at 5:34 pm

I’m making an app and I’m wondering is there a way to add different stylesheets for different devices,because my app looks fine in the phone emulator, but looks weird in the tablet emulator.

Reply

14.

saiJagan says:August 2, 2011 at 5:28 am

Hey !

Phoegap and Titanium in these to which is the better choice….

Reply

15.

Ammu says:August 3, 2011 at 8:47 am

Very helpful and nice…

Reply

16.


18 of 24 12/28/2011 12:29 PM

Tuan Bui says:August 18, 2011 at 6:19 pm

Good article. If you need to create surveys to get feedback for your mobile apps, check outhttp://www.mobosurvey.com.

Reply

17.

dinesh says:September 1, 2011 at 3:33 am

i want to set a new image to my java script for android with eclipse using phonegap .so what will be theimage path should i given..to java script..rely me soon

Reply

18.

cornelius says:September 12, 2011 at 12:39 pm

..in this tutorial only IOS and Android were bn mentioned, wat about blackberry

Reply

19.

Beginner Developer says:October 22, 2011 at 9:55 am

I’m building an Android hybrid application which displays a static ‘shell’ like a header and navigationbuttons, but the content itself is a mobile web page should be requested from the web.

I’ve tried to add an iframe which sources to the required page but unfortunately, it doesn’t work. Cananyone help me with this? I’d be glad…

Reply

20.

best android apps says:November 13, 2011 at 10:30 am

Thanks for the tutorial. I think, phonegap is one of the best compared to other tools to create android apps.one reason is, we do not have to learn from scratch, because almost all of us would have to know html andcss before.

21.


19 of 24 12/28/2011 12:29 PM

Reply

UI Designer says:December 26, 2011 at 8:06 am

Yes phonegap is really helpful for designer like me. Thanks Abbas for tutorials.

Reply

22.

Add a CommentName

Email Address

URL

Your Comments

To add a code snippet to your comment, please wrap your code like so: <pre name="code" class="html">YOURCODE</pre>. You can replace the class name with "js," "css," "sql," or "php." If there are any "<" or ">" withinyour code, please search and replace them with: < and > respectively.

RSS UpdatesFacebookTwitterGoogle+Email Updates

RSS Subscribers 10,235Twitter Followers 6,419Facebook Fans 6,017Advertise Here


20 of 24 12/28/2011 12:29 PM

Advertise Here

Learn More...

Already a member? Sign In

iPhone App Entrepreneur

Gain insight from the pros and find out what you need to become a successful iPhone App Entrepreneur!

Find Out More

Facebook


21 of 24 12/28/2011 12:29 PM

TwitterGoogle+

Follow Mobiletuts+ and Tuts+ on Twitter

☆ Android SDK: Build a Simple SAX Parser http://t.co/l9jXYbAL☆ Corona SDK: Build a Shell Game – Final Steps http://t.co/b3XoIb0J☆ Hot Mobile Themes from ThemeForest http://t.co/JUuo3hd3☆ Happy Holidays from Tuts+! http://t.co/s0y5h5Z6

Join our newsletter!

Find us on Facebook

Ravi Ashley La Tinta Marco Miguel

Micro Mehdi Danijela Pablo Masoom

Mobiletuts+

6,018 people like Mobiletuts+.

Like

Facebook social plugin


22 of 24 12/28/2011 12:29 PM

Get weekly updates and an exclusive pack of mobile design elements when you sign up to our freenewsletter.

NameEmail

Top Selling

on Codecanyon

UberMenu - WordPress Mega Me ... only $14.00 by sevenspark

RoyalSlider – Touch-Enable ... only $12.00 by Semenov

Mobbilee - More

Freelance Jobs

More Freelance Jobs...Basix

Mobile Basix

Just getting started? Start with our basix tutorials on the fundamentals. View All Basix Tutorials

Create a Tutorial, Get Paid!

Have something to teach the world? Want to earn money doing it? Tutorials, screencasts, and articles published


23 of 24 12/28/2011 12:29 PM

here on Mobiletuts+ are largely contributed by readers just like you! We'll pay you great money for goodcontent. Find Out More

Mobiletuts+

Part of the Plus education network

Powered by: Envato

RSS UpdatesFacebookTwitterGoogle+Email Updates

Copyright © 2011 EnvatoAdvertiseSuggestionsAbout UsIcons by WeFunction


24 of 24 12/28/2011 12:29 PM

introduction to phonegap development

Documents