6. Configuring an iOS Development Environment for PhoneGap

This chapter includes the instructions to follow to install and use the Apple development tools to build PhoneGap applications for iOS. You must have a Macintosh computer running Macintosh OS X in order to be able to build applications for iOS.

Registering as an Apple Developer

To access developer-related content on Apple’s web site, you must first register as a developer in Apple’s developer program. Apple keeps a very tight rein on its developer community; registration is free, but you will also need to join one of the developer programs before you can download the latest version of Xcode (Apple’s proprietary IDE for Macintosh OS and iOS development) or deploy any iOS applications to individual devices or through Apple’s App Store. The following developer programs are available:

• Individual: For individual developers creating free or commercial iOS applications for distribution through Apple’s App Store

• Company: For commercial developer organizations creating free or commercial iOS applications for distribution through Apple’s App Store

• Enterprise: For organizations building iOS applications for distribution through a private, enterprise App Store (for business applications)

• University: For higher educational institutions that include iOS development in their curriculum

There’s a yearly membership fee for each of the listed programs except for the University program. You can find more information on the different program options at http://developer.apple.com.

Installing Xcode

Once you have registered for the appropriate Apple developer program, it’s time to install Apple’s development tools on your Macintosh computer. iOS development is performed using Xcode, which is available as a free download from the Apple App Store provided you have the appropriate Apple developer program membership. To install Xcode, launch the App Store application on your Macintosh and enter Xcode in the search box in the upper-right corner of the application window. The App Store will return a list of several options; click the Xcode option, and the application will display a screen similar to the one shown in Figure 6-1. Click the Free button, and then click the Install button that appears (in the same screen location) to begin the installation process.

Figure 6-1 Installing Xcode from the Apple App Store

Xcode is a very large download, so it will take some time to download and install the application. When you click the Install button in the App Store application, Xcode isn’t actually installing; instead, the Xcode installer application is being downloaded and installed on the system. Once the Xcode installer’s installation completes, there’s still another installation that has to happen before you can start writing iOS applications using Xcode. Confused?

You’ll be able to tell when the App Store download and installation completes, because the button on the Xcode page in the App Store says Installed rather than Free or Install. At this point, you can close the App Store application, and then open the Launcher application. Then switch to the Launcher’s last page, as shown in Figure 6-2, and look for the Install Xcode application highlighted in the figure. Launch that application to begin the actual Xcode installation process, and navigate through the prompts until the installation completes.

Figure 6-2 Xcode installation icon

Once you’ve completed the Xcode installation, you must now install the PhoneGap project files and the Xcode plug-in used to create PhoneGap applications for iOS. Refer to Appendix A for complete instructions.

Creating an iOS PhoneGap Project

With Xcode and the PhoneGap plug-in installed, you’re ready to begin building PhoneGap applications for iOS. Note that the instructions and example screen shots in this section are for Xcode version 4.

When you launch Xcode for the first time, you will see a screen similar to the one shown in Figure 6-3. Select “Create a new Xcode project” to start the process. If you’ve used Xcode previously and have the checkbox for “Show this window when Xcode launches” disabled, then you will need to open the Xcode File menu and select New Project.

Figure 6-3 Xcode: welcome screen

Xcode will prompt you to select the type of project you will be creating. Select the option for iOS Applications on the left side of the window, as shown in Figure 6-4. Select the option for PhoneGap-based Application and click the Next button.

Figure 6-4 Xcode: new project window

Xcode will prompt you for a product name for your project and a company identifier, as shown in Figure 6-5. The product name and company identifier are concatenated together to form what should be a unique identifier for the particular project being created. When the appropriate options have been defined for your application, click the Next button to continue.

Figure 6-5 Xcode: defining project naming options

Xcode will then prompt you to select the destination folder for the new project, as shown in Figure 6-6. Select or create the appropriate folder location for the project, and click the Create button to continue. Note the option for creating a local Git repository for the project; as discussed later in the book, the IDE’s integration with Git can make building applications using PhoneGap Build a simpler process.

Figure 6-6 Xcode: defining the project location

At this point, Xcode will create the necessary iOS project folders and source files for the application. When completed, Xcode will display its workspace window similar to the one shown in Figure 6-7.

Figure 6-7 Xcode: new PhoneGap project

The left side of the window contains the navigator area that lets you browse the folder and file structure for the project. On the right is the editor area, which is currently displaying summary information for the application. You can switch between the tabs (Summary, Info, Build Settings, Build Phases, and Build Rules) to see the different possible options for the application’s configuration. The available options won’t be covered here; instead, we’ll focus only on the PhoneGap-related topics. There are many great books on iOS development that should be referenced for a detailed discussion of Xcode and iOS development.

In the project summary, you will want to enter a version number for the application and then select the supported device orientations for the application. Many a PhoneGap developer has forgotten to enable the necessary options here and has been frustrated when the PhoneGap application will support only a single orientation (which is the default for iOS projects). There will be good reasons for some applications to support only one or two orientations, but in general you will probably want to enable all available options here for most applications. The PhoneGap application runtime container will fire an event that will allow your web application to execute code to deal with orientation changes as they happen, but only when you enable the correct options here.

The Summary tab also displays the application icons and launch screens in use for the application. These images populate with default PhoneGap project images, but for any production application, you should provide your own custom images. To change the image for any of these options, right-click an image, and select an appropriate option from the menu that appears: Select File, Show in Finder, or Delete.

The PhoneGap Xcode project in its current state doesn’t have access to the web content it needs to provide the application with its user interface or application logic. The last part of the process includes some counterintuitive steps that may not make much sense but are still required in order to make this work. These steps are not required for earlier versions of Xcode and may no longer be required for more recent versions of PhoneGap as they are released.

Launch the new PhoneGap project by clicking the Run icon in the upper-left corner of the Xcode window. Xcode will build the application, launch the default iPhone simulator, and then display the error message shown in Figure 6-8. Don’t panic; this is expected behavior. For some reason, the PhoneGap new project wizard doesn’t create the web content files when the project is first created; instead, it creates them the first time the application is launched, and even then it creates them in what appears to be the wrong location. At this point, close the iPhone simulator by opening the iOS Simulator menu and selecting Quit iOS Simulator.

Figure 6-8 First launch of a new PhoneGap application in the iPhone simulator

Next, open Finder and navigate to the folder where you created the Xcode project, as shown in Figure 6-9. Notice the www folder highlighted in the figure; it contains the default web content files for the new PhoneGap project. What you’re going to need to do here is drag the www folder onto the project in Xcode. Do not drag the www folder onto the project’s folder in Finder, but instead drag it onto the PhoneGap project’s entry in the Xcode navigator area, as shown in Figure 6-10.

Figure 6-9 The PhoneGap project’s web content folder in Finder

Figure 6-10 Dragging a PhoneGap project’s web content into Xcode

To make this process easier, position Xcode and Finder so they take up only a portion of the screen and are positioned next to each other. Drag the folder over, and with the www folder contents positioned over the highest-level folder in the PhoneGap project (as shown in Figure 6-10), release the mouse button. Xcode will prompt you to select how copied the files are referenced in the Xcode project (Figure 6-11). Select the option “Create folder references for any added folders,” and then click the Finish button to continue.

Figure 6-11 Xcode: options for adding files to a project

At this point, the new Xcode project will now have a reference to the web content files it needs, and you should be able to see the contents of the www folder in the Navigator area shown on the left side of Figure 6-12. Simply click the index.html file in the navigator to open the file in the Editor area, as shown in the figure.

Figure 6-12 A new PhoneGap project in Xcode

As shown in the figure, the default iOS project for PhoneGap contains instructions and code designed to help a beginning PhoneGap developer build a better application. For your applications, you will simply augment the provided code with the appropriate HTML, CSS, and JavaScript for your application. For the example in this chapter, we’ll use the code from the HelloWorld3 application from Chapter 2.

Testing iOS PhoneGap Applications

You’ve already seen how to launch a PhoneGap application in Xcode. Simply select the iPhone or iPad simulator version you want to test on, and then click the Run button in the upper-left corner of the Xcode UI. Xcode will build the application, launch the selected simulator, load the application into the simulator, and start the application. With the sample application code included in the default PhoneGap project, the application will display the screen shown in Figure 6-13.

Figure 6-13 Sample PhoneGap application running in the iPhone Simulator