Getting started with PhoneGap in Xcode for iOS

This article describes steps needed to set up an environment and a workflow for developing PhoneGap/Apache Cordova applications in Xcode, targeting iOS devices. Xcode is the integrated development environment (IDE) provided by Apple for developing OS X and iOS applications. iOS is Apple's mobile operating system for iPhone, iPad, and iPod touch devices. PhoneGap is an open source application platform that enables you to create natively-installed mobile applications using HTML and JavaScript, also known as Apache Cordova.

The first step to setting up Xcode for PhoneGap applications is to download and install the Xcode IDE from Apple. You can download Xcode from the Apple developer site. Before you can download Xcode, you must register as a developer with Apple. Once you do, you get access to Xcode, the iOS device simulator, and Apple developer documentation for free. If you want to deploy your applications to an actual device or distribute your applications via the iTunes store, you will have to register with Apple as an iOS developer, which has a yearly cost associated with it.

After you download Xcode, simply follow the setup wizard to complete the installation process.

Once you have successfully installed Xcode, your next step is to download and install PhoneGap.

1. Visit the PhoneGap download page (http://phonegap.com/download) in your browser and click the orange Download link to start the download.

Note: The following steps are shown for PhoneGap 1.5.0, but the process should be applicable or similar to all versions of PhoneGap.

2. Extract the ZIP file's contents.
3. Navigate to the libs/ios/ folder of the extracted files, and double-click on the Cordova-1.5.0.pkg package installer.

This will launch the PhoneGap installation wizard, which will guide you through the process of installing PhoneGap on your system (see Figure 1).

3. Follow the installation instructions provided by the installer until you see "Thanks for installing PhoneGap 1.5.0! ".

When you see this message, PhoneGap installation is complete. You are now ready to create your first PhoneGap project within Xcode.

The PhoneGap installer adds a PhoneGap project template to Xcode, which streamlines the creation of PhoneGap applications.

1. To get started, simply click Create A New Xcode Project in the Xcode welcome screen (see Figure 2). Alternatively, you can choose File > New > New Project to create your new PhoneGap project.

The first step in creating a new Xcode project is to select a project template.

2. Find and select the Cordova-based Application template, located under iOS > Application, and then click Next (see Figure 3).

After you have chosen the project template, you'll need to name your project. Give it a name indicative of what you're going to be building.

3. In this case just type Hello, since you're building a simple Hello World application (see Figure 4).

On the New Project Options screen, you also need to enter a company identifier. The company identifier is the prefix that is concatenated with the product name to create the unique bundle identifier for your application. The bundle identifier should match the App ID that you create for a unique application within the Apple Provisioning Portal (see Figure 5).

If you aren't sure what to type here, or if you are not deploying to a device or distributing this application right away, you can type whatever you want or leave this blank. You can always change the bundle identifier later by editing the Identifier field in the Xcode project summary screen, or by manually editing your project's Info.plist file.

Note: On the project options screen, you also have the option to turn on Automated Reference Counting (ARC). If you aren't writing any native code within your PhoneGap application, you can ignore this. You only need to worry about ARC if you are writing PhoneGap native plugins or writing native code. PhoneGap native plugins enable you to write your own native code and JavaScript APIs to extend the capabilities of the PhoneGap container.

PhoneGap projects will work regardless of whether ARC is enabled or disabled. If ARC is enabled, then you do not need to manage memory allocation using retain and release instructions in any native code. The Xcode LLVM compiler will automatically generate the appropriate retain and release instructions for you. If ARC is not enabled, you will have to manually manage memory. Remember, ARC only applies to native code, not HTML or JavaScript code.

4. Click Next.
5. Select a folder on your file system in which your PhoneGap project will reside (see Figure 6).

6. Click Create.

Your PhoneGap project will be created within Xcode. However, there are a few more steps you need to complete before your project is up and running.

All of the HTML and JavaScript used to create the interface for your PhoneGap project will be contained within a www folder. Initially, this www folder will not exist within your PhoneGap project. To create it, you first have to run the application.

7. Run the application by clicking Run in the upper left hand corner of the window (see Figure 7). Alternatively, you can choose Product > Run.

Xcode will attempt to launch the PhoneGap application in the iOS simulator. For the first launch, you will see the error message "ERROR: Start Page at 'www/index.html' was not found." Do not worry, this is normal! During this first step, the www folder will be created. After you add it to your project, you should not encounter this error again.

8. To add the www folder to your project, Ctrl-click the project root and select Add Files To "Hello" (see Figure 8).

9. In the dialog box that opens, select the www folder inside of the newly created project. Be sure to select the actual www folder, not a parent folder or contents inside of the folder.
10. Select Create Folder References For Any Added Folders (see Figure 9). If you do not select this option, your will encounter errors with your project.

11. Click Add.

You should now see the www folder under your project root (see Figure 10).

12. Click Run to launch the project again.

At this point, your project should be correctly configured and should launch in the iOS simulator. If you haven't changed any of the HTML files inside of the www folder, you will see the default PhoneGap starter page inside of your application running within the iOS simulator (see Figure 11).

If you see this, then you are now ready to begin developing iOS applications within Xcode using PhoneGap.

With your PhoneGap environment properly set up, reviewing some Xcode and PhoneGap basics will help you make the most of this development environment.

In general, Xcode should be fairly easy to navigate. On the left side of the screen you will see the project hierarchy, and in the center of the screen you will see the main content area. As you select files on the left side, the content will be displayed within the main editor area.

Here is one simple tip that trips up a lot of people: single-clicking a file in the project hierarchy displays that file's contents in the same window; double-clicking a file opens the file in a new window.

If you select the project root, you will see the project summary screen. From this screen, you can easily set the bundle identifier, application version, target devices, icons, splash screens, and supported orientations among other options (see Figure 12). This screen is useful in configuring your application for deployment.

At the top of the Xcode window, near the Run button, there is a Scheme menu that lets you change the project compilation schemes and target devices or simulators. To target a specific device or change the iOS Simulator target, simply click the project name and then select an alternate device or simulator target (see Figure 13). The next time that you run the application, it will be deployed to the newly selected target.

Keep in mind that the entire interface of a PhoneGap application is developed using HTML and JavaScript. Maintain all of the HTML assets used within the interface in the www folder. If you want to add additional files from a remote location, you will need to white-list that location inside of the PhoneGap.plist file, otherwise any external requests will be blocked with a security exception.

By default, the content area of Xcode will display source code based upon the files you select in the project hierarchy (see Figure 14).

If you prefer to open and edit multiple files side-by-side, don't fret. This is possible, although it's not immediately obvious how to do it.

To edit files side-by-side, click the Show The Assistant Editor button located in the top right side of the Xcode window (see Figure 15). Once the second editor instance is visible, you can drag files from the project hierarchy on the left into the new editor window. This is particularly helpful when you want to view separate HTML and JavaScript files at the same time, or when you want to view a native plugin and its JavaScript interface at the same time.

Now that you have Xcode set up with PhoneGap, you are ready to start building some serious applications for iOS using PhoneGap. Next, you may want to read Extending PhoneGap with native plugins for iOS.

Remember, PhoneGap applications are built using HTML, CSS, and JavaScript for the user interface. This enables you to create great looking applications with ease using traditional web development skills. To learn more about rich experiences created with HTML, CSS, and JavaScript, check out the Adobe Developer Connection HTML5 and CSS3 developer center.