Chapter 8: Using the PhoneGap framework within Xcode – iPhone Application Development


Using the PhoneGap framework within Xcode

This chapter provides a step-by-step guide through the process of making your completed Dashcode project available to library users from the iTunes App Store. The reason you may want to be on the iTunes App Store is that this is a popular delivery platform which may reach users who never think to check your library’s website, or for users who might just search on the iTunes App Store for something related to their geographic region or other such local affiliation, and then happily stumble upon the library’s iPhone environment. The option for getting the Dashcode components onto the App Store is by way of the PhoneGap framework (available at that we will use within the Xcode module. PhoneGap is an open source, freely available cross-platform framework.

You may have read of the seemingly strict regulations of getting an application available on the iTunes App Store, or otherwise have read about using outside tools for creating apps, and wondered how this may impact our development process. Despite the hearsay, rumors and controversy with regard to the use of development tools outside of the SDK that would somehow make your app ineligible for the iPhone App Store, PhoneGap’s process doesn’t get in the way of Apple’s development environment; this tool is actually run from inside the SDK and doesn’t suffer from the restriction of being outside an Apple-sanctioned tool. Indeed, at the time of writing, there are two versions of the PhoneGap framework which are sanctioned for use by Apple – many of the example apps in this book are available on the iTunes App Store; these were made possible because of the PhoneGap framework. PhoneGap will also help you develop for other platforms – so there is usefulness for the framework beyond iPhone development. There are other cross-platform frameworks for mobile development. The virtue of the PhoneGap framework is that it remains freely available at this time, and widely accepted as the cross-platform mobile framework for application design.

Overall, the continuum of development utilized in this book is:

1. design our library apps within Dashcode,

2. open the PhoneGap project inside of the Xcode module,

3. use the PhoneGap files inside of Xcode to generate a binary which then can be uploaded to the iTunes App Store.

Essentially, that is the sort of broad design outline for your library app workflow, encompassing everything from the Dashcode chapters previously discussed. If you’ve read every chapter along the way, you should have five iPhone apps for your library ready for the iTunes App Store – and should you choose to, you could make different content area apps for each of the templates we’ve covered, signifying an important shift in your ability to produce an array of iPhone apps for the iTunes App Store.

The skills required for the iTunes App Store are basic; essentially, you need only to be able to export files from Xcode and then upload that exported file to the store in order to get iPhone apps onto the App Store. As the ‘store’ portion of the word in App Store suggests, you have the option of charging for your app. Your library users would have to purchase your app in order to use it. That is not the development strategy pursued here; all of the apps that I’ve created for my library are available as a free download. I chose not to charge library users anything to make use of them. Perhaps your library is pursuing alternative cost recovery options and you feel your users would actually pay for a library app; these apps can certainly be set to download to the device for a fee. Choosing to charge for your app does not significantly alter the layout and design process of application development.

A feature of the SDK module which you will want to be aware of is the notion of in-app purchase. The in-app purchase configurable portion of code allows you to make sales from within the application, even if you choose to make the app freely downloadable. For a complete overview of the cost options and available configurations, see Another feature of Xcode makes it possible to directly install applications to your device if you want to simulate the application from your device, or would rather not make the application web-–accessible or through the App Store. Direct device distribution might be useful for a library which is solely interested in creating applications for specific devices, i.e. only for the iPod touch that you keep at the Circulation Desk, or apps which you would only provision to the iPhone that you keep at the Reference Desk. In other words, you could chose to create apps solely for staff side tasks. Librarians like concrete, practical examples; here you can find an example of a mobile application that is just for library staff: The ShelfLister app is a web-based tool which can run on any mobile device that has a browser; it is designed for use by library staff primarily as an inventory assistance tool.

Native applications are not quite the same as web-based applications. In some ways you have a lot more freedom to develop in Xcode; as with the Dashcode module, you still have the option of configuring existing objects. The Xcode module essentially allows new levels of customization; for example, the iPhone has a number of sensors like the accelerometer and GPS and WiFi that we cannot completely take advantage of with the Dashcode module. Many of the interesting apps of the iPhone (and mobile applications, in general) are compelling to use because of their use of the full range of being mobile and using some of the sensors to do interesting tasks, for example turning the iPhone camera into a barcode scanner and then feeding the identified information into a number of bibliographic services; the RedLaser app is one such: As a tangential aside regarding fascinating experimental research in mobile computing for location-based service is the ability to locate and then position the mobile device inside the library building based on Wi-Fi signal strength.1 There could be apps developed within Dashcode that also make use of the user’s location in the library as a means for delivering information. If you chose to, you could make the video application dependent on the user actually standing in a certain part of your library and then deliver video content that relies on their position in the library as a means for contextual learning and a more engaging user experience in the library. The phone tour (the infopoint chapter) is also somewhat dependent on the user’s location in the building. It should not be forgotten that as you design apps for your library the most compelling uses of mobile are making possible those tasks that do not have a desktop-based equivalent. Think of it this way: why directly compete with the exact functionality of a desktop PC, when that desktop will always be better at being a desktop than the functionality of the phone. Alternatively, the iPhone with its mobility and permanent Internet connection, offers possibilities that a desktop computer cannot – the sheer portability and its touch screen interface make possible tasks that desktops aren’t readily able to accomplish.

The PhoneGap framework does make possible certain aspects of location-based services to be used for development – let us begin to explore this framework for transforming web-based iPhone applications into native applications. If you decide you’ve had enough iPhone application development, you can certainly use the Dashcode module for all your development work and then port those into the application store by way of a framework.

To get started in moving your application from Dashcode into the Xcode development environment, download the latest release of the PhoneGap framework (essentially a set of files, for our purposes), available from PhoneGap actually provides other mobile frameworks besides just the iPhone. There is also a helpful wiki that provides useful guides for frequently asked questions and community discussion (; in fact, wiki FAQs will be more up to date than the step-by-step guide provided in this book, simply due to the nature of electronic publishing versus paper. We can cover in this chapter some of the foundational steps necessary for getting your app into the iTunes store.

The PhoneGap folders

The PhoneGap developers have noted on the website which releases have been successful for getting applications onto the iTunes App Store – so if that is what your goals are for the app, be certain to utilize the specified release for that; at the time of writing the ‘Apple approved’ versions of the PhoneGap tool are 0.8.0 and 0.9.0. It’s probably a good idea to download the file first to your systems desktop, and then unzip the folders there as well. Using the Finder tool of your Mac, navigate to the iPhone folder inside the PhoneGap download. The phonegap.xcode project is the one that we can open in the Xcode module. Still in the finder view, proceed with opening the PhoneGap project in Xcode. Figure 8.1 shows an example of what is included in the folder (I have opened the file view of release version 0.8.0) in the Finder view.

Figure 8.1 This is the iPhone folder found in the downloaded files

Notice that I’ve highlighted the PhoneGap.xcodeproj file that I am going to open with the Xcode module of the iPhone SDK. This file will not work in the Dashcode module. Dashcode cannot open.xcodeproj file extensions. These kinds of file extensions will only open in Xcode.

Let’s take a look at the Xcode screen and try to understand what we are seeing.

Our conceptualization of building applications within the Xcode module is essentially a series of folders, with each folder having different tasks of the application you are designing. Another way to think about this is that each folder has different functions, even though they all look alike.

Place your Dashcode files into the PhoneGap WWW folder

The Dashcode-generated web files that you uploaded to your library server are necessary here; locate those previously created application files in your Mac’s Finder window.

Next, open your WWW PhoneGap folder in Finder.

Figure 8.2 The PhoneGap framework is a preconfigured set of files running inside of Xcode. It is essentially a template

Finally, pull your completed Dashcode components – HTML, CSS and JS files into the WWW folder.

What the PhoneGap framework will now allow is for your web-based app be fully operational in the native development environment. We can test this out by building the app.

In order to build the app, click the build and run button in the center of the toolbar. Notice in the Status Bar the operations that are being completed as the module builds the binary. This happens fairly quickly after you hit the build and run button, so, you may miss it if you don’t know what you are looking for. If there are build errors, the Status Bar will tell you and will link the error to the relevant line of code. Sometimes it is a line of code that stops the application from building properly, but it could also be an error with the project settings.

If the Xcode defaults haven’t been tweaked by you and if there have not been any build errors reported in the Status Bar, the iPhone simulator will launch your Dashcode application. What you are looking at is your Dashcode application running inside the Xcode module. This is a great accomplishment, now that you are now able to run the application from inside the Xcode module; you can export this application from Xcode as a binary, and then upload the file to iTunes Connect, where it will be reviewed by Apple staff, and if approved, will then be available for download from the App Store.

Getting the binary onto the iTunes App Store

We have now come as far as we can without paying for anything. To be able to upload to the iTunes App Store through iTunes Connect, you have to pay for this by signing into the iPhone developer center: In order to upload anything to the App Store, you need to join the iPhone Developer Program. Depending on your institutional affiliation and company size, you may qualify for a University Program account. Otherwise most users will probably fall under the Standard Program. If you are a librarian in a corporate library and you think your applications will solely be for in-house use, then the Enterprise program is the one you want to enroll in. The available developer membership criteria may change over time, so it is best to consult the Apple Developer website for current information on the developer program.

The final steps for getting your native application onto the iTunes application store involve taking the ‘built’ file (for those of you with a programming background, the compiled binary) and uploading this as a compressed file to the iTunes Connect website at which point Apple staff will review the application and either approve it for the iTunes App Store or suggest tweaks to make it acceptable for the iPhone experience. You can only get access to the iTunes Connect website if you have a developer account which allows access.

I had hoped to be able to avoid discussing the exact signing certificates, signing keys, public keys and private keys that are associated with (1) you, the developer and (2) your application, but it seems sensible to give you some brief details. You are required to assign a provisioning profile and distribution key to your app in order for it to be considered for the App Store. In fact the application will not even build properly without a provisioning key (for distribution) that you issue to yourself from the Apple store (this is confusing, but there are plenty of help guides from the iPhone Developer Center, and there are a number of sources in blogs that describe the cross-platform framework, too).

All of this has been external to the focus of the book thus far, because what we have been working solely from the iPhone simulator. The simulator is a powerful tool for giving application designers a good idea about how the app is going to look on the actual iPhone. If you have an iPhone, or iPod touch, we can start simulating directly to the device.

Setting the Active SDK and Active Configuration for Distribution

Distributing your application is the objective of this last section. Because we have managed to get it running in Xcode we are nearly finished with getting it into the App Store. First, set the ‘Active SDK’ of the Xcode to one of the Device settings, which will be one of the flavors of the actual iPhone ‘Active SDK’ [by flavors I mean the kind of iPhone software you want your app to be able to run on: we currently have available 2.2.1, 3.0 (Base SDK), 3.1 and 3.1.2]; it must be set to the iPhone device (rather than any of the simulator flavors listed here). You cannot distribute an app for simulation – the apps can only be distributed for devices.

After you’ve set the Active SDK to an iPhone device, the next crucial configuration option is the ‘Active Configuration’, set this to Distribution.

What you must get from the Apple Developer Center is an iPhone Distribution Certificate (once, rather than for every app). For the app itself, you need to set up an ApplelD and download a certificate known as a Provisioning Profile – make certain you are downloading the one that is set ‘for distribution’.

This may seem somewhat counterintuitive; you must use your Mac’s keychain software to request the Distribution Certificate from Apple. Also, the actual request for the provisioning profile is initiated by you, and the profile is downloaded by you, the user of the Developer Center.

The distribution profile that you download is then associated with your provisioning profile and the AppleID of the provisioning profile. The code will not build for distribution without this. And, should you associate a provisioning profile that is already in use, the Apple iTunes Connect website will again reject your binary from the store. For a comprehensive overview of the process consult the Distribution help guide available from the Apple Developer Center. It will be more up to date than the material here, given the rate of technological advance in this domain.

Consider also what screenshots you want to use for your app -once you successfully get a binary of the app uploaded to the iTunes Connect webpage you will then be required to upload an icon of your app, and then also sample screenshots of the application as well. You will want to create an icon that will make the app stand out from the crowd of others and also perhaps use icons of your library to indicate some continuity between your library services in person and through iPhone applications. You can upload up to four screenshots. You can get these screenshots from your device, or you can also use the ‘Grab’ application that is included in the Mac OX suite of tools.

The online help manuals offer substantial documentation for distribution of the app on the iTunes store. It may also change from the time of this book’s publication to the time you are planning to distribute. That distribution guide is accessible through the developer login. Additionally, the profile distribution process makes more sense once you have an app developed. If you’ve been reading this book but haven’t actually built anything from any of the Dashcode modules, the process of uploading those files is not going to make a lot of sense outside the development context. In some ways, you really have to have the Dashcode-generated web files before you can see this portion through to the end: getting your app available on the iTunes App Store. The iTunes App Store will mean a greater audience for your app and it will be delivered in a way that your users are accustomed to when loading applications onto their device. It will place your library within the range of information access tools available from the iTunes App Store.


A ‘Distribution’ document regarding the submission process is available from the iPhone Developer Program user guide:

MobiForge Blog

1.Aittola, M., Ryhänen, T. & Ojala, T. (2003) SmartLibrary – location-aware mobile library service. Proceedings of the 5th International Symposium on Human Computer Interaction with Mobile Devices and Services, pp. 411–16, available at (accessed 15 September 2010).