PhoneGap for iPhone exposed | November 4th, 2009
Earlier this week I attended the Apple iPhone Developers Tech Talks in Seattle. The event was free and by invite only and you had to have an app in the app store, or be very close to having one to be invited. This meant that the content of the talk could be technical without losing anyone, and we had an informative deep dive into technical things like OpenGLES, Device Audio, and UIKit functionality best practices. I learned a lot over the day about what to avoid, and how to optimize iPhone applications.
As a PhoneGap developer, user and evangelist, I made it my duty to talk to everyone I could about PhoneGap and guage the level of interest from the Apple dev community. After speaking to a couple people at Apple, it became clear that they are very much aware of PhoneGap, but have very little understanding of what it does or how it works. I have decided to dig into these questions to make sure that there are no misconceptions about the project. PhoneGap is entirely opensource, but not everyone has the time read a bunch of code. ( if only …)
PhoneGap Under the Hood
PhoneGap aims to provide a consistent interface to device functionality across multiple platforms to enable rapid application development via well known technologies, namely HTML / JavaScript / CSS.
At it’s core, PhoneGap is nothing more than a spec listing JavaScript accessible calls that an application programmer can use to make applications. Each device ( iPhone, Android, BlackBerry, … ) has it’s own specific implementation, and the tools and processes you use to build, test and deploy/submit your app will vary for each. So again, PhoneGap is a JavaScript accessible API implemented on multiple devices.
All implementations render their user interface using HTML and CSS in a web browser control of some sort. Most modern devices support rich rendering features ( HTML5, CSS3 ) so it is a relatively simple to design, and layout your application with your existing skills, tools, and even existing graphical assets.
The typical PhoneGap application is a packaged version of a webpage/website that runs from the phone. What this means is that all html/css/js files are bundled into the application and run from the file:// protocol. A common misunderstanding is that the application is loaded over the web, which is definitely NOT the way we recommend users write their apps, and (to my knowledge) NOT the way typical PhoneGap based applications are architected. In this case you would be writing a mobile-optimized website and will likely not be approved for app store submission.
In some cases PhoneGap applications have a server component that delivers data via an HTTP API, usually json or xml using XMLHttpRequest. PhoneGap itself does not provide any server communication functionality, so app developers must roll their own server access layer.
So How Does PhoneGap Work?
Every device implementation has it’s own specific means of accessing device functionality, so I will be focusing on the iPhone implementation. The iPhone implementation is probably the most misunderstood, and most used, plus it is where I have spent the most time.
How does JavaScript call Objective-C code?
In order for a developer’s application code (js) to access device functionality they will include the file phonegap.js in their (html) application. The file phonegap.js defines the entire API and contains the key functionality for device communication. All device functionality that PhoneGap exposes is done via the navigator object in JavaScript.
For example, to access Accelerometer functionality, you would call JavaScript methods on the navigator.accelerometer object.
In order for phonegap.js to send a request to the device it simply sets the location of the page based on the following protocol:
gap://CommandHandler.method?arg1Name=arg1Value&arg2Name=arg2Value
- gap://
- This is a phonegap request and not a request to load a new page.
- CommandHandler
- This is a subset of device functionality that contains methods. An example would be Accelerometer or Notification
- method
- Each CommandHandler defines it’s own methods
- arguments
- a URL encoded list of arguments that are passed to the method ( varies based on the method ) Note that phonegap.js will URLEncode the parameters for you.
and here’s a concrete example:
gap://Notification.alert?message=Hello&title=My%20App%Name&buttonLabel=OK
This will call the Notification objects alert method, passing it a message,title, and the text to display on the button.
So, upon receiving the command, Objective-C code will take over and perfom the requested command.
So How Does Objective-C call my JS code?
Some calls from JS require a callback mechanism to let the JS code know when the command has completed, if it succeeded and so on. The majority of this is handled for the developer in phonegap.js. Objective-C code will call stringByEvaluatingJavascriptFromString() to pass data back into the js code. The mechanism for each command is defined in phonegap.js, so the developer will simply pass a function callback that phonegap.js will call once the command has returned data.
Here is a concrete example:
In my application, I want to access the accelerometer, so I define a callback function :
function onAccelData(accelObj)
{
// accelObj has properties x,y,z that you can use to see the
// current state of the accelerometer so presumably you
// would do something with that data here.
}
function onAccelFail()
{
// accelermeter functionality is not available,
// do something else ...
}
In order recieve the data, I need to make a call to the js Accelerometer object :
navigator.accelerometer.watchAcceleration(onAccelData, onAccelFail);
Now, your callback is going to be called repeatedly with updated accelerometer data, that your application can use as you see fit. Since this is not intended to be a blog post about how to use the accelerometer, I will stop there. You should know also that the accelerometer supports stopping as well, and you can also specify how often you want to be updated.
So that, in a nutshell, is the entire iPhone implementation of PhoneGap. Note, there is no voodoo or magic sauce, just 2 data transfer mechanisms and a protocol between them.
Hopefully this will give better perspective and help anyone who has to answer the question: What is PhoneGap?
Remember that PhoneGap is completely opensource so if you want a deeper look under the hood, you are completely free to do so.
If you want to use PhoneGap, you can git it here :http://github.com/phonegap/phonegap
To read more, have a look at www.phonegap.com
I invite your questions, comments, criticism, accolades, beers!
November 4th, 2009 at 8:50 am
[...] This post was mentioned on Twitter by purplecabbage and Shazron Abdullah, Alexei White. Alexei White said: RT @purplecabbage: #PhoneGap for #iPhone Exposed! http://bit.ly/3Fwc8L #programming [...]
November 15th, 2009 at 8:17 am
Any chance you could point out some simple example pages? Everything listed at phonegap are i-tunes downloads. I’m more interested in the cross-browser capabilities than just the i-Phone stuff, (yeah, I know I’m probably the only one who is).
For some of us, the world doesn’t revolve around only Apple. Or maybe thats my point. Can this be used as a cross-browser/device web app? I get the part about using it as a Safari/WebKit file w/JavaScript include (as an app on the device), but can it be used just as web content with javascript access?
Still, the project looks really interesting. Keep on blogging.
November 17th, 2009 at 7:04 am
Dwight,
This post was an explanation of how PhoneGap works on iPhone, the other platforms work in a similar fashion, but not necessarily exactly the same. The cool part is that the complexity is hidden from you for the most part, and the same js/html can be used for multiple platforms.
If you did deeper at phonegap.com on the community pages, you should find more info/examples on the other platforms. You are definitely NOT alone in wanting to target other devices.
In reply to your last question, web content can only access this functionality if it is loaded from a PhoneGap based application, and not the devices normal web-browser. However, the recommendation is that you perform your application logic on the client within your application and not simply on the server.
Typical phonegap apps contain their business + presentation logic in JavaScript on the client, and if a server is used, it is usually accessed via json/xhr through an API that primarily serves data.
November 30th, 2009 at 2:39 am
Hi,
The attraction of PhoneGap for me is that I can have the index.html file as part of the app and let AJAX access the database and PHP logic on my server. Actually, I left the index.html file on the server but it could have been part of the app. In any case, app fly-with-me-A.apk works wonderfully well so long as it has a data connection.
Best Regards,
Tom Birchmire
February 11th, 2010 at 3:28 pm
I have noticed that navigator.notification.alert works only on iPhone Device 3.0 and later. Is there any way that it could be used on earlier versions of iPhone (2.2)?
October 19th, 2010 at 6:20 am
I’ve just setup PhoneGap and then copy one of my web project into the www directory , guess what , every thing works fine! it’s just like voodoo and magic.
i can’t help to google “how phonegap works” and then find this post, thanks a lot.
btw : i’ll read the source code of phonegap (if i have time :p)
March 14th, 2011 at 11:35 am
[...] See this link for a more detailed explanation of this process - PhoneGap for the iPhone Exposed. [...]
May 2nd, 2011 at 7:13 pm
Tried to find out how PhoneGap works and ended up at your post.
Thanks for the post with very useful insights.
The thing I was looking for is your explanation that
“all html/css/js files are bundled into the application and run from the file:// protocol.”
Cheers,
Totti
September 23rd, 2011 at 12:58 am
Hi,
I want to make a photosharing application, where people can take images and upload to a server/space online … will this be easy to do with PhoneGap and what would be the best starting place?
I’m a junior front end developer so can work with html/css/ and I know basic javascript so any examples or web links would be very helpful ..
thank you
September 26th, 2011 at 1:58 pm
Have a look at the Camera/Capture apis as well as fileTransfer to upload the image to a server.
http://docs.phonegap.com/phonegap_camera_camera.md.html
http://docs.phonegap.com/phonegap_file_file.md.html#FileTransfer