Tutorial Details
- Technology: PhoneGap
- Difficulty: Beginner
- Estimated Completion Time: 30 - 45 Minutes
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:
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:
<title>PhoneGap</title> <link rel="stylesheet" href="master.css" type="text/css" media="screen" title="no title" charset="utf-8"> <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:
<body onload="init();" id="stage" class="theme">
<h1>Welcome to PhoneGap!</h1>
<h2>this file is located at assets/index.html</h2>
<div id="info">
<h4>Platform: <span id="platform"> </span></h4>
<h4>Version: <span id="version"> </span></h4>
<h4>UUID: <span id="uuid"> </span></h4>
</div>
<dl id="accel-data">
<dt>X:</dt><dd id="x"> </dd>
<dt>Y:</dt><dd id="y"> </dd>
<dt>Z:</dt><dd id="z"> </dd>
</dl>
<a href="#" class="btn large" onclick="watchAccel();">Watch Accelerometer</a>
<a href="#" class="btn large" onclick="getLocation();">Get Location</a>
<a href="tel://411" class="btn large">Call 411</a>
<a href="#" class="btn large" onclick="beep();">Beep</a>
<a href="#" class="btn large" onclick="vibrate();">Vibrate</a>
<a href="#" class="btn large" onclick="show_pic();">Get a Picture</a>
<a href="#" class="btn large" onclick="get_contacts();">Get phone's contacts</a>
<div id="viewport" class="viewport" style="display: none;">
<img style="width:60px;height:60px" id="test_img" src="" />
</div>
</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:
<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:
<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″:
<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:
<a href="#" class="btn large" onclick="beep();">Beep</a> <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:
<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!
Enjoyed this Post?
Subscribe to our RSS Feed, Follow us on Twitter or simply recommend us to friends and colleagues!
By Abbas Suterwala
Join our newsletter!
Create a Tutorial, Get Paid!
Have something to teach the world? Want to earn money doing it? Tutorials, screencasts, and articles published here on Mobiletuts+ are largely contributed by readers just like you! We'll pay you great money for good content. Find Out More
Great article! Just started with Titanium, but I think PhoneGab is easier! :)
Will try it out! :)
Nice one
Has anyone gotten the demo app to work? I have gone through this article and followed the link for the Android documentation and I cannot get the sample code to generate. I keep getting build errors and the output 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 I have 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.
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 .
Hi!
Phonegap’s install is annoying. I did the step by step install on Win7, but when I reached the 4A point on the guide (http://phonegap.pbworks.com/Getting-started-with-Android-PhoneGap-in-Eclipse) I got an error 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:)
Hi tzs007,
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.
Thx Abbas. But I did that. But IMHO in the droidgap file somethings wrong when call the generate file from the /lib.
Been trying to get an Iframe working on a PhoneGap based application but with no luck. PhoneGap send me to Safari Mobile whenever a iframe tag is imported ( Most likely have to do with the src=http://.html atribute )
Does anyone know a decent workaround? Maybe java perhaps?
Thanks
You could you a div and AJAX to display the data you would of put in the iFrame. This allows you to apply your own style to.
Hi,
When using PhoneGap for iOS, you’re not allowed to just dump a public website in an iFrame. The application must have a shell which works regardless of whether the device has network access or not. For an example but the phone into Aeroplane mode and access Maps. Part of the approval process 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 use window.location to set the source you can negate the problem. Although this is likely to get your app rejected.
Apple don’t like public websites in applications as it makes it impossible to enforce policies relating to content. A childs game could be changed to adult content post submission and apple would be unaware.
You should be developing the application as pure html files included within the application. You can get data from public websites using AJAX although you’re have to configure a cross domain policy.
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
Got into problem with starting the default demo application on PhoneGap – with missing phonegap.jar file after the ruby bild. After some digging it got out that the problem was with the Ruby version – I had installed the latest 1.9.2. With the previous Ruby 1.9.1 the build got finally fine and the demo app ran successfully 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.
Thanks soooo much for that answer …. trying it out now !
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)
Where are the HTML files for the IOS version? I double-clicked the pkg, and started a new project based on it in XCode but don’t see any “index” or “master” files. There is one template HTML file I see, but nothing else. Maybe I’m just overlooking it?
i got the same problem.
For those of you who are loosing time trying to put Phonegap and Android SDK running on Windows, my piece of advice:just forget it and do it on Linux (or Mac): it’s much more quick and easy.
Trust me ;-)
yes i agree with u… :)
What is most popular application area of PhoneGap ?
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 once deployanywhere).
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
Hi,
Is there any way to display 2 splash screens by giving time duration while loading iPhone app in phonegapdelegate.m. Because my app is quite heavy and takes 12-15 secs to load. Could you please give some code sample.
Thanks
i so much like and appreciate this, please can any one email this to my mail address.
fantastic article for beginners………………cool ……………….keep going
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.
Hey !
Phoegap and Titanium in these to which is the better choice….
Very helpful and nice…
Good article. If you need to create surveys to get feedback for your mobile apps, check out http://www.mobosurvey.com.
i want to set a new image to my java script for android with eclipse using phonegap .so what will be the image path should i given..to java script..rely me soon
..in this tutorial only IOS and Android were bn mentioned, wat about blackberry
I’m building an Android hybrid application which displays a static ‘shell’ like a header and navigation buttons, 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. Can anyone help me with this? I’d be glad…
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 and css before.
Yes phonegap is really helpful for designer like me. Thanks Abbas for tutorials.
A Phonegap case study with Application Craft called ‘pain free mobile app development’ may help (and alleviate the pain! Its here: http://phonegap.com/case_study/phonegap-application-craft-pain-free-mobile-app-development/
Can anyone give me information how PhoneGap can be used to develop Windows Mobile application.?
Krishna..
other than setting up (http://phonegap.com/start/#wp) and coding HTML/CSS/JS, what other information do you need?
I am very new to PhoneGap.
Can any one tell me how to develop a an app for BlackBerry?
I need a help from you for developing a simple app like to view the “deviceId”.
Thanks in advance.
But you must add xml forlder in you project. XML forlder of PhoneGap into res/values if you want to running code in Eclipse.
can anyone help me out …working with ‘files api’ of phonegap in android and symbian ??
Great article. thanks.