Home > Mobile Development, PhoneGap > PhoneGap Tutorial Series – #1 Project Structure and Internals

PhoneGap Tutorial Series – #1 Project Structure and Internals


What is PhoneGap?

PhoneGap is an open source framework for writing applications using typical web technologies like HTML, CSS, and javascript. The PhoneGap architecture supplies javascript wrappers that allow a developer to access native phone features (like contacts, GPS, and the camera) by writing their app against the PhoneGap javascript API.

The basic gist is that the typical web developer will be able to write a standalone HTML/CSS/javascript application that runs in a WebKit browser with access to native functions just by calling the PhoneGap javascript. PhoneGap aides the developer by abstracting the complexities of native development by allowing the developer to write the app in well-known technology without having to learn the intricacies of each mobile platform and thereby hiding the complexity of writing the same application multiple times in various native languages (like Objective-C for the iPhone or Java for Android).

Since I have been focusing on iOS development, this series of blog posts will focus on using PhoneGap to create an iPhone application. The series will walk you through the PhoneGap architecture, using the PhoneGap API, installing a third party plugin, and creating your own custom PhoneGap plugin.

The following posts assume a fair degree of familiarity with programming concepts and the Apple developer tools. Please review the following links for information on any topics where you may need additional education or explanation.

Assumed knowledge:

  1. General web development (HTML/CSS/JS)
  2. General programming knowledge (flow control, data structures etc)
  3. General Mac skills (Terminal, Finder etc)


  1. Mac computer with Developer Tools (Xcode) installed and up to date. See this link for instructions:
  2. If deploying to an iOS device, an Apple Developer membership. See this link for more information:
  3. PhoneGap installation and configuration. See this link for instructions:


How Does PhoneGap Work on the iPhone?

To get started I’d like to explain a little bit about how PhoneGap iOS project is setup and how PhoneGap actually works on the iPhone so that you can better understand the course of events that take place when you execute a PhoneGap function.

The first thing you will need to do is set up a PhoneGap project so please follow the Getting Started guide for the iOS PhoneGap project to install PhoneGap and create a PhoneGap project from the PhoneGap template.

Note: You will need to complete these steps using Xcode3 as Xcode4 does not yet have supported phone gap templates – if you do not have access to Xcode3 click here for a starter project.


PhoneGap Project Structure:

Once you have created a project based off of the Phone Gap Template then we are ready to get started with a tour of the Xcode project:

In the screenshot you will notice that there are numbered areas that I would like to call your attention to:

1. ‘www’ folder — this is the folder where all of the static resources for the web view should be stored. This is also the location where the phoneGap build steps will copy the phonegap.js files and where you will place all of your own HTML/CSS/JS files.

2. index.html / phonegap.js script — the index.html is the start page of your application. In order to access PhoneGap functions you must include the phonegap.js script reference on the index.html and any other html page from where you will call PhoneGap functions.

3. PhoneGap classes — PhoneGap provides an extension to the typical iOS classes for the UIApplicationDelegate (which implements the UIWebViewDelegate methods) and the UIViewController. These classes perform most of the “magic” behind PhoneGap such as setting up the webView and wiring together the view controller and delegates.

4. PhoneGap commands — PhoneGap provides a number of built-in plugins to access native resources like the camera or the address book, this is where you can find the source code…

5. Project Plugins — This is where you would place your own custom plugins since PhoneGap can be easily extended and new features added by extending the PhoneGapCommand class and implementing the objective-c code for the native function you want to expose (see later in the tutorial for how to do this.)


So … How Does it all Work?

PhoneGap works by extending and wrapping common classes of the iOS SDK:

1. The PhoneGapDelegate class extends UIApplicationDelegate and implements the UIWebViewDelegate protocol and is responsible for setting up the application, instantiating the view controller, configuring the views, and performing the delegate functions for the webView.

2. The PhoneGapViewController extends UIViewController and is responsible for responding to view lifecycle methods.

3. The PhoneGapCommand is the base class for all the available PhoneGap API plugins (like the Camera, GPS, and Contacts) and is responsible for providing access to the appDelegate, appViewController, and the webView. This class can be extended to create your own custom plugins.

Putting it all together…

Basically, PhoneGap works by intercepting URL requests for the UIWebView that is loaded in the view. The PhoneGapAppDelegate implements the UIWebViewDelegate protocol to detect and intercept changes to the document.location of the UIWebView. Once intercepted, PhoneGap interrogates the request to determine what to do with it.

There are several url patterns that PhoneGap handles right out of the box:

1. gap:// command — this represents a request to execute a PhoneGap command, this string is generated by calling something like “PhoneGap.exec(‘SomePlugin.someMethod’, someArg1, someArg2);” in javascript which ultimately ends up being translated into a URL request of gap://SomePlugin.someMethod?arg1Name=someArg1&arg2Name=someArg2

This gap:// url is then set into the document.location of the WebView (by the PhoneGap javascript) and then intercepted by the PhoneGapAppDelegate (UIWebViewDelegate – webView:shouldStartLoadWithRequest method) and ultimately instantiates and executes the Objective-C PhoneGapCommand.

Once the Objective-C PhoneGapCommand has completed it may (or may not) notify the webView that it has completed. This is defined by the API but typically there is some sort of onSuccess and onFailure javascript method defined for each API call. The underlying document is notified of the results of the Objective-C operation by executing the onSuccess or OnFailure method — [webView stringByEvaluatingJavascriptFromString:@”onSuccess()”].

See this link for a more detailed explanation of this process – PhoneGap for the iPhone Exposed.

2. file://www/someurl.html — this represents a request to load a local file (possibly from the ‘www’ directory) into the webView

3. http://someweburl.html — this represents an http request to load a remote file into the webview

4. mailto: sms: tel: etc — there are several protocols build into the UIWebView to handle various functions like sending email or making a phone call which will cause the appropriate iPhone app to open and handle the request

5. Custom — you can override the PhoneGapAppDelegate webView:shouldStartLoadWithRequest method in order to implement your own custom URL handler.

Well that’s all for now … Stay posted for the next installment of the PhoneGap Tutorial Series – #2 Using the PhoneGap API …

  1. March 14, 2011 at 7:49 PM

    Similar to Titanium from Appcelerator

  2. April 1, 2011 at 11:40 AM

    Wow! Awesome series of tutorials Hiedi. I’m considering the use of phonegap as my framework for building interactive books for the students at our art school. I’ll follow your tutorials and see if I can get something up and runnin

  3. Jammy
    June 28, 2011 at 4:06 AM

    I am new in iphone development. I have one task in phone gap application in iphone. I have created one UIViewController in that phone gap application from that i want to call the values of the UIViewController in phone gap application.

    IN simple words i want to get UIViewController values in phone gap controller by the custom user plugin..

    how should i start..

    please help me..

    thx in advance.

    • June 29, 2011 at 2:23 PM

      Sorry Jammy but I am still not clear on what you want to do, perhaps post some code to explain?

  4. ben
    July 7, 2011 at 1:21 PM

    Is there anything we can’t do using phonegap by the way? I assume there is no problem to write an app to fetch products on an ecommerce website and sell them via a phonegap made app?

  5. Bill Dane
    October 18, 2011 at 9:59 AM

    I have a bit of a disconnect here. Obviously I’m a rookie or I wouldn’t be here so here’s my issue. I just downloaded and installed Xcode4 and PhoneGap 1.1.0. I’ve gone through the Getting Started guide for the iOS PhoneGap project to install PhoneGap and create a PhoneGap project from the PhoneGap template, and that seemed to go fine. Your instructions above state to download your starter project (as I don’t have Xcode3). I downloaded the zip and unzipped it into a new folder named HelloPhoneGap and then double-clicked on the HelloPhoneGap.xcodeproj file to open the project in Xcode. When I went to run the project I get 4 warnings (no errors) and Xcode says the build is successful, but the simulator doesn’t launch. Also, the button in the upper-left where I would select what device I’m targeting, says “UniveralFramework > iPhone 5.0”. I must be missing a step or two. Thanks for your time and this great resource.

    • October 28, 2011 at 1:55 PM

      Those instructions were from before Xcode4 had a PhoneGap project template. Just use the PhoneGap template and skip using the started project – it was for PhoneGap 0.9.6 anyway.

  1. March 18, 2011 at 4:01 PM
  2. April 19, 2011 at 10:22 AM

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: