PhoneGap development part 2

We could break out PhoneGap and start native development straight away for a single platform using their SDK’s. But this isn’t a great approach. There is a large amount of overhead with native development. We need to build and compile our projects, install them on devices, and then clean, uninstall, and rebuild whenever we make a small change. Because PhoneGap leverages open web standards, we don’t need to go straight to the native SDKs—we can start work in a desktop browser, and then move on to a native project once the functionality is fleshed out. This way, we speed up our development cycles and spend more time implementing core functionality.

Strictly speaking, you can use any major desktop browser to get started on your PhoneGap app. All of these browsers have adequate, at least, developer tools for logging and debugging our code. For our purposes, however, we strongly advocate using a WebKit based browser, either Safari or Chrome. With the exception of Microsoft, all of the major mobile OS vendors now use a WebKit-based browser. As of November 2012 it has the most market share of any layout engine at over 40% of the browser market share. It is the default browser in the Apple iOS, Android, BlackBerry Tablet OS, Bada Tizen and webOS mobile operating systems.

PhoneGap apps are organized inside a www directory, with an index.html file as the starting point. PhoneGap apps uses the file:// URL protocol that all run from on the supported platforms—the web assets are served directly from the file system, and, in most cases, a remote server is only used to serve dynamic data that cannot be bundled at compile time. There are lots of benefits to this approach—your application functions offline, there is lower latency for retrieving assets, and available bandwidth is less of a concern—but, at this stage, the main benefit is that you won’t need to upload your files anywhere to get the full testing experience. Just open index.html directly from your file system to get the optimal PhoneGap development workflow.

As PhoneGap has a full JavaScript runtime on every platform, you are free to use a full-stack framework, such as Sencha Touch or jQuery Mobile. I would recommend using the standard JavaScript APIs to keep file size down, and to increase the clarity of your code. However, the benefits of these frameworks are well known. They’re certainly popular options when combined with PhoneGap. Apache Cordova is a library used to create native mobile applications using Web technologies. The application is created using HTML, CSS and JavaScript and compiled for each specific platform using the platform native tools. Cordova provides a standard set of JavaScript APIs to access device features on all supported platforms.

To really appreciate PhoneGap we will need to create a native project based on the code that we have. We’re going to build an application for iPhone:

  • Download and install the latest version of Xcode (includes the iOS 6 SDK)
  • Download the Xcode Command Line Tools ( Xcode Preferences > Downloads > Command Line Tools). This package will install copies of the core command line tools and system headers into system folders, inlcuding the LLVM compiler, linker, and build tools.
  • Download and extract the latest version of Apache Cordova (locate and extract, the code for iOS is within the incubator-cordova-ios directory structure)
  • Copy the cordova-ios folder to a for you convenient location like Documents

Project creation

Xcode projects for Cordova are created by invoking a script file via the command line. There are 3 ordered, required parameters for creating a Cordova project from the command line:

  • Project location. This is the directory where the Xcode project and files for the application will be located. This tutorial is using ~/Documents/cordova-ios as the base location and the application name as the project directory. Thus the location for our project will be 
~/Documents/cordova-ios/HelloWorld, where HelloWorld is the project name. The final directory, HelloWorld in this example, must not already exist as it will be created during execution of the command
  • Package name. When submitting apps to the App Store, this must be the reverse domain name App ID that is created via the Apple Provisioning Portal. Since you will not be submitting this sample app, this tutorial uses org.apache.Cordova plus the app name, HelloWorld: 
  • Project name. This is the name of the actual project. Most developers make the project name and the application name the same. In this example the project name is HelloWorld


In the terminal app with ~/Documents/cordova-ios/bin as the current directory, enter the 3 pieces of information via the following command:

./create ~/Documents/cordova-ios/HelloWorld org.apache.cordova.HelloWorld HelloWorld

Open the project  by navigating to the location where you created the project. This guide uses ~/Documents/cordova-ios/HelloWorld. Double click the HelloWorld.xcodeproj file to open the project in Xcode. I think you have to build the project at least once to generate a default folder structure. The resulting app will look like this:


All of the code for the sample application is contained within the www directory in the Xcode project structure. The starting page is named index.html. Any page that uses Cordova must include the cordova-*.js file for the associated Cordova version and platform. The format of the JavaScript file name is cordova-x.y.z where x represents the major version number, y the minor version and z any point release. For example, the Cordova 2.2.0 file was named cordova-2.2.0.js. The sample HelloWorld application includes this file from index.html:

<script type="text/javascript" src="cordova-2.2.0.js"></script><script type="text/javascript" src="js/index.js"></script><script type="text/javascript">// <![CDATA[
// ]]></script>

When loading a page, Cordova’s deviceReady event must fire before you can access any of the platform features via the Cordova JavaScript APIs. Within the sample application this is set up within the app object found within the js/index.js file. The app.initialze() call at the bottom of the index.html file sets in motion the binding of events to receive and respond to the deviceReady event.

Currently the platforms and plugins folders are empty because we haven’t specified that any be added yet. The default www folder however contains a basic PhoneGap application architecture preset for you (includes js, css, img folders etc and includes the links to them from index.html. Note that it also includes config.xml for PhoneGap Build use). It’s important to note that this is the folder where you will be developing. It will be copied down into the different platforms to be used when you build and launch your application so the latest is used.

To code your own application you can replace the sample code in the www directory of a new project with the HTML, JavaScript and CSS code for your application. The name of the initial file to load when the app is launched should be index.html (advanced users can change this if necessary). Subdirectories within the www directory are permitted. You can use many mobile JavaScript frameworks with Cordova to create the UI and page navigation of your application. Popular ones include:

  • JQuery Mobile
  • Dojo Mobile
  • Sencha Touch

There are many additional considerations to make your application unique. The sample HelloWorld application is set up to run in all iOS environments, iPhone, iPod, and iPad. You can design an app for a single device type by modifying the build settings within Xcode. You should customize the application with your own icons and splash screens. The sample application includes Cordova specific images in the Apple required sizes and resolutions as examples. The Cordova Specific settings are located in the config.xml file.

Note that older versions of PhoneGap requires a different JavaScript file for each platform and using an incompatible phonegap.js will result in errors when running your application. Beginning with PhoneGap 1.6, the PhoneGap project started consolidating the JavaScript files into one common file.

Leave a Reply