Introduction

Developers that have started using CM WebClient 1.8 Mobile’s touch optimized templates usually find that creating a mobile web app deployment is straightforward. But while deployment as a web app is acceptable for some, other developers creating commercial and specialized applications often benefit from native deployment. For example, you may need to use the camera to capture pictures or scan documents, implement a signature capability, or access the phone contact database. CM WebClient supports this style of native application using Adobe/Apache PhoneGap. There is a Camera and Signature template available, and you are encouraged to create your own device templates and share on the WebClient Mobile Google Code project.

This tutorial is for Apple devices (iPhone / iPad), and also requires use of a Mac to run Xcode and to meet Apple licensing requirements. If you are targeting Android or Blackberry devices, you will need to follow a similar but different procedure for each device platform. I.e. your core code remains the same, but the PhoneGap native wrapper is different for each technology. PhoneGap has tutorials available for every supported platform.

Download and Install Software

For this part you need access to an Apple Mac. Point the browser from your mac to the Apple developer website, http://developer.apple.com. Download the latest version of Xcode and the iOS SDK’s. It is over three gigabytes, so you may want to have a couple coffees at this point. You may also want to take some time to sign up as a developer, either individually or within an organization. Organizational approvals can take weeks to process by Apple, so it is always better to do this well in advance of needing to upload your app for public distribution.

After you have installed Xcode, download the PhoneGap distribution from http://phonegap.com. This example is using version 1.3.

Run the installer

Follow the steps on the installer wizard

Create Your Xcode Project

Open Xcode and select “Create a new Xcode project”

Choose PhoneGap as the template for your new project

Give your project a name and identify your company. Typically your organization / company id will be your domain name in reverse word order. It is important to deselect Automatic Reference Counting – otherwise build errors will result.

Select a directory location for your project. A subfolder will be created beneath the directory you select to contain your project. It is recommended to also create a local repository for source code changes – that way you can easily revert if you make a mistake.

Next, enter project information. You can drag and drop application icons if you wish (you can do this later if you don’t have any  icons prepared).

Keep scrolling down and enter iPad information as well as application launch images (splash screens). Do not enter Entitlements unless you know what to fill in.

Hit the validate setting button to make sure all is ok

You may get a window like this. Accept this recommendation.

It is recommended to select the automatic snapshot option

Configure and Run

You will now see the Xcode workbench. First we have to run the application once in order to create a “www” folder that contains the Phonegap startup code and resources. Select a simulator target and hit the run (play) button.

You will see this error in the simulator – this is expected and is not an issue. It means that your app cannot find a start page.

This next step is very important and must be done exactly as described. We need to create a folder reference in Xcode to our www and javascript resources. You do this by opening Finder and dragging the “www” folder beneath the project onto the Xcode project work space. You will see a green plus sign indicating the drag target is accepted. You will then be prompted to create a reference to this folder.

Use the following settings

Run your project again, and you should see that PhoneGap is now working. The HTML5 and JavaScript you see are running directly on the device, not served up by a web server.

Connect your application

The next step is to connect your CM WebClient pages to PhoneGap. There are two parts to this.

First we need to add a whitelist entry to allow your app to access external resources. You do this in the PhoneGap.plist file.

Next, add some JavaScript in the index.html file to access your dynamic content. For production applications, you will want to create some static web pages and a mechanism to check the online status. This is straightforward but beyond the scope of this tutorial.

Run your app again from Xcode and you should be rewarded with your app on your device emulator!

Congratulations, You Are Deployed!

You need some further steps to deploy your app to physical devices and to iTunes. Stay tuned for more blog posts, or contact us at CM FIrst for assistance if you are on one of our support plans.