Handheld Designer Blog

Creating Native Apps - Getting Started With PhoneGap and Handheld Designer

April 1, 2013

Mobile web-apps are great, and can have many advantages over native apps. But sometimes you need to accomplish something that can only be done by a native app. Perhaps you need to access the device hardware, like the camera or GPS hardware, in a way that web-apps are prohibited to do, or maybe you just want to sell your app on the App Store.

Fortunately, an open-source tool called PhoneGap makes it easy to “wrap” a standard HTML5 mobile web-app in a native wrapper, producing a native app suitable for submission to the App Store. In this tutorial, we’ll review the steps necessary to convert a web-app created with Handheld Designer into a native iPhone or iPad application.

Creating a native application with PhoneGap requires a few simple steps:

  1. Create a new PhoneGap-based Xcode project.
  2. Create and test your application using Handheld Designer
  3. Export the HTML, CSS and JavaScript from your Handheld Designer web-app into your Xcode project.
  4. Build and test your native app in Xcode.

(Steps 3 and 4 can be repeated as necessary as you test and enhance your now-native app.)

Installing Xcode

Before we build our first native app, we must install Xcode and PhoneGap.

Xcode is Apple’s tool for creating native Mac and iOS applications and is distributed through the Mac App Store. You can install Xcode by visiting the Xcode page on the Mac App Store.

Although it’s not required to download Xcode or test your app in the iOS Simulator, you’ll need to join Apple’s iOS Developer Program if you want to install your native apps on actual iPhones or iPads, or submit your apps to the App Store.

PhoneGap also requires the Xcode command-line tools to be installed into to create new PhoneGap-based Xcode projects. To install the Xcode command-line tools, choose the Xcode Preferences / Downloads / Command Line Tools menu option within Xcode. This will download and install copies of the command-line tools into system folders on your computer.

Installing PhoneGap

Download and install PhoneGap using the instructions in the “Getting Started With iOS” guide. (At the time of this writing, the latest version of PhoneGap is 2.5.0. You may be able to find a newer version of the software and Getting Started guide linked from the main PhoneGap download page.)

Also note that the Getting Started guide will frequently refer to “Cordova”, which is the open-source project upon which PhoneGap is based. (Yes, nerds, the history is a little more complicated than that.)

The guide provides the complete details, but in brief you will:

  • Download the compressed PhoneGap archive from http://phonegap.com/download.
  • Extract the compressed archive to gain access to the Cordova command-line tools located in the “cordova-ios” directory.

Creating the Xcode Project

For each native application you want to build, you’ll create a new Xcode project using the Cordova command-line tools installed above. Again, follow the guide for detailed instructions, but this step involves:

  • Determining the the folder that will hold your new project, creating new folders as needed.
  • Executing the Cordova “create” script, with the appropriate command-line parameters, to create the new Xcode project.

Exporting the Handheld Designer Project

Create (or open) the Handheld Designer project that you’ll be converting to a native app. (In this example, we’ll be using the Weather app created in the Weather app tutorial. You can open a complete working version of the app from the Handheld Designer sample gallery.)

From within Handheld Designer, select the Project / Export as Web Application menu. Navigate to your new Xcode project folder, then choose the “www” folder. Handheld Designer will now export the HTML, CSS and JavaScript files for your web application into the PhoneGap project’s “www” folder.

Note that you’ll perform this step whenever you make changes to your application in Handheld Designer. If you’ve exported your project into the “www” folder before, Handheld Designer will warn you that you’ll be overwriting existing files; you can safely overwrite the exported files in the “www” folder each time you export your project.

Configuring and Running the Xcode Project

There’s one final step before you can run your native app: Open your Xcode project and find the “config.xml” file in the Xcode Project Navigator. Find the <content> element and change the src attribute to reflect the first page of your web-app. (For example, if the ID of the initial page in your Handheld Designer application is “main”, you should set the src attribute to “main.html”.)

Finally, click the Run button in Xcode, and Xcode will compile your app and load it in the iOS Simulator. From there, you can test your app in the simulator as if it was running on a native device.

(If you’re a member of Apple’s iOS Developer Program, you can also load your app onto an actual iPhone or iPad for testing. These steps are covered in Apple’s iOS development documentation.)

Handheld Designer Project Settings

PhoneGap provides an API for accessing native hardware features, making it possible for your application to capture a photo with the camera, record and playback audio, access the user’s contact database, read from and write to the native file system, and more.

In order to access this API, you need to add the appropriate Cordova JavaScript file to your project’s javascriptIncludes property in the Handheld Designer project settings.

The Cordova JavaScript filename varies based on the version of PhoneGap you’ve installed. In this post, we’re using version 2.5.0, so the file is named cordova-2.5.0.js.

You should also change the Handheld Designer project setting “jQuery Sources when exporting” to “Export and use local copies”. This will cause your application to export and use local copies of the jQuery and jQuery Mobile sources, rather than use the versions hosted on the Internet. This will ensure your application works correctly even when the device lacks an Internet connection.


Now that you’ve created a native application using PhoneGap, there are many more creative options available to you. You could build an application that uses devices features unavailable to a web-app, or submit (and sell!) your app through the App Store. And since PhoneGap allows you to built cross-platform native apps, you could even explore targeting non-iOS platforms such as Android and Windows Phone. Good luck!

As always, your feedback is welcome. Please use the Handheld Designer contact form for any questions, comments, or suggestions.

Copyright © 2010-2017, Handheld Designer, LLC, All Rights Reserved.
Made by hand in New England, USA.