PhoneGap Tutorial Series – #1 Project Structure and Internals
What is PhoneGap?
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.
- General web development (HTML/CSS/JS)
- General programming knowledge (flow control, data structures etc)
- General Mac skills (Terminal, Finder etc)
- Mac computer with Developer Tools (Xcode) installed and up to date. See this link for instructions: http://developer.apple.com/xcode/
- If deploying to an iOS device, an Apple Developer membership. See this link for more information: http://developer.apple.com/programs/ios/
- PhoneGap installation and configuration. See this link for instructions: http://www.phonegap.com/start#ios
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:
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 …