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:
- Create a new PhoneGap-based Xcode project.
- Create and test your application using Handheld Designer
- 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.)
Before we build our first native app, we must install Xcode and PhoneGap.
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.
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.)
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.
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.
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.