9. iOS Development with Cordova
For developers building Cordova applications for the iOS platform, Apple provides a suite of tools used to design, package, and deploy iOS applications. Even though the Cordova CLI takes care of most of the process of creating, managing, and testing iOS applications, there will be times when you will want to have more control over the process. Even though the CLI can launch a Cordova application in the iOS simulator, when you encounter problems with an application, and you want to know more about what’s going on as the application runs, you’ll need to use the development tools that Apple provides. Additionally, when coding, testing, and debugging native plugins for iOS, you’ll do the majority of your work using Apple’s tools.
In this chapter, I’ll show you how to use Xcode, Apple’s IDE for iOS development, to test Cordova applications for iOS devices. I’ll also show you how to use the Safari browser to debug Cordova applications.
Working with Xcode
Assuming you’ve used the Cordova CLI to create a project and added the iOS platform to it, working with a Cordova application in Xcode is pretty straightforward. When you have your web application’s content all ready, use the cordova prepare command to copy the project’s web application source code over to the project folder for each target platform.
The Cordova CLI creates a project that can be opened directly in Xcode. Simply start Xcode, open the project, and go to work. If the Xcode welcome page is configured to open on startup, you’ll open a project by selecting the Open another project option on the welcome page. If not, simply open the File menu and select Open.
In the Open dialog that appears, navigate to the Cordova project’s platforms/ios folder as shown in Figure 9.1, then select the file with the .xcodeproj extension and click Open.
When the project opens, you should see a screen similar to the one shown in Figure 9.2. From here, you can run the application in any of the iOS simulators as you would for any other iOS application.
Xcode isn’t designed to be used to edit web applications—Apple created Dashcode for that purpose—so you’re not going to get a lot of context-aware editing help with Xcode. That’s why I use Adobe Brackets to edit my web applications and switch to Xcode only when I need to be able to see what’s happening as the application runs.
For the most part, you can run the Cordova application as is; the default settings in Xcode should be sufficient for your application. By default, though, a Cordova project for iOS is configured only for portrait operation; if you’re expecting the user to be able to rotate the device and have the screen update accordingly, you’re going to have to make one small change. In Xcode, click on the application project title in the upper-left corner of the project navigation pane shown in Figure 9.2—it’s “Example 14.1” in the figure. When you do that, general properties of the application project will open as shown in Figure 9.3.
Notice the Device Orientation option highlighted in the figure; to support additional orientations, enable the appropriate checkboxes, such as Landscape Left and Landscape Right to enable landscape orientation, for example.
When it’s time to test the application, Xcode can launch an iOS device simulator and deploy the application to it once it launches, or you can deploy the application to a physical device connected to the development system via a USB cable.
There are a few differences between debugging on a simulator and a physical device. So at some point in your development process, you are going to want to run your app on a device. Apple has some complicated processes you must follow before you can run an application on a physical device. As there are hundreds of books and web sites dedicated to iOS development, I’m not going to dig into the details here. You can find detailed instructions on the Apple Developer web site at http://goo.gl/SF2qNV. You’ll have to follow the instructions provided there before you can work with a physical device.
Once you’ve completed the setup of your device, you can connect it to the computer running Xcode with a USB cable and run the application on the device directly from Xcode. In this environment, Xcode provides the same debugging capabilities for a physical device as it does for the simulators.
In the upper-left corner of the Xcode application window are buttons you can use to launch the application and to specify the target device (simulator or physical device) where the application will run. Figure 9.4 highlights the buttons and their purpose.
To compile and run the current application project, click the Run button highlighted in the figure. Xcode will build the application, then, depending on the selected target, will deploy the application to a physical device or launch the specified simulator and deploy the application to the simulator.
While the application is running, you can click the Stop button to terminate the application on the target device.
The Active Scheme button is used to select the scheme, a collection of build targets, defined for the application. You can find more information about this option at http://goo.gl/GJ8rlM.
The Target option shown in Figure 9.4 opens a list of available target devices available in Xcode. The list will show any physical devices attached to the system running Xcode, plus it will list any simulators installed in Xcode. A sample list of targets is shown in Figure 9.5, in this case a list of all targets on my development workstation.
When you’re ready to test the Cordova application, click the Target button, select the device where you want the application to run, then click the Run button to build and deploy the application. That’s all there is to it.
Testing Cordova Applications in Xcode
iOS applications are written in Objective-C, a variant of C that was used by NeXT to develop applications for the NeXTSTEP operating system back in the 1980s. While Xcode will let you edit HTML5 source files, because iOS applications are written in C, Xcode does not have the ability to debug web applications running in the Cordova container. You can use weinre or the console object to help debug applications as described in Chapter 5, “The Mechanics of Cordova Development,” to debug your iOS applications. Later in this chapter, I’ll show you how to debug a Cordova application using the Safari browser.
Using Xcode, you can debug native application code, so you’ll be able to work directly with the native Cordova container and any native plugin the application is running. As this is a book on Cordova development and not Xcode development, I’m not going to cover native application debugging. Refer to Chapter 28 of Fritz Anderson’s Xcode 6 Start to Finish (Boston: Addison-Wesley, 2015) for details on how to debug a native iOS application using Xcode. In reality, when you’re debugging native plugins, you’ll most likely use two debuggers: the Xcode native debugger for the plugin’s native code and the Safari browser for the application’s HTML and JavaScript code.
When you run an iOS application in Xcode, the IDE opens up a console window at the bottom of the screen where you can see messages generated by the simulator as well as the Cordova application. Using the sample application from Chapter 14, “Working with the Cordova APIs,” you can see the output from the code that uses the console object written to the IDE console screen in Figure 9.6.
Notice how error messages are tagged with additional text so you can identify them more clearly in the console window; the same is true for warning messages. Unfortunately, Xcode doesn’t color-code them to make them easier to see; perhaps Apple will add more robust capabilities in the future.
On many other platforms, you can filter the console messages based on type, application ID, or other properties, but that’s not possible in the Xcode console window. The only thing you can really do here is click the arrow button shown in the top of the figure to have Xcode push a specific location to the simulator (for testing applications that make use of the device’s geolocation capabilities).
If you look at the console output shown in Figure 9.6, you should see that the Compass API returned an error (we’ll cover the Compass API in Chapter 14, and I’ll show you more about the sample application in Chapter 15, “Cordova Development End to End”). That’s because the iOS simulator doesn’t provide support for the compass and several other native capabilities; you can find detailed information about the iOS simulator limitations at http://goo.gl/vs3Hi4.
In order to make it easier for the user of the application, I had the application display an alert whenever an error was detected within the application as shown in Figure 9.7. You could, using the Cordova Device API, detect whether the application is running on a simulator and disable features within the application in that situation as well, to avoid showing the user an error dialog.
When working with iOS device simulators, you can easily grab screen shots using any Macintosh-compatible screen capture utility. When working with a physical device connected to the system running Xcode, you can use the Devices utility to grab screen shots from the device. To access the Devices utility, in Xcode open the Window menu and select Devices; Xcode will open a window similar to the one shown in Figure 9.8. Click the Take Screenshot button to capture the current device’s screen. Images captured this way will be automatically saved directly to the desktop.
Using the Safari Web Inspector
Beginning with iOS 6, Apple added some capabilities to Safari (both on the desktop and in iOS) that allow a web application to be remotely debugged in the desktop Safari browser. The cool thing about this capability is that it works with the UIWebView used within a Cordova application. You can find detailed information about this remote debugging capability on Apple’s web site at http://goo.gl/XP3Gai.
The first thing you must do is enable the developer menu in the desktop version of Safari for Macintosh OS (this process doesn’t work on Windows and probably never will). Open the Safari application preferences and select the Advanced tab as shown in Figure 9.9. Enable the checkbox at the bottom of the figure labeled Show Develop menu in menu bar.
What this does is add a Develop menu item to Safari that you can use to interact with a device or even a device simulator. With that change in place, close preferences and you should see the new menu in Safari.
Next, you need to enable the Web Inspector on the device on which you will be doing your debugging. On an iOS device (or iOS simulator) open the Settings application, select Safari, then click the Advanced option at the bottom of the Settings screen. On the screen that appears, enable the Web Inspector option shown in Figure 9.10.
Note
With the initial implementation of this feature, Web Inspector was supported only on physical devices, but in my testing, I could access some of the capabilities on a simulator, although I couldn’t step through my application’s JavaScript code.
With those settings in place, launch the simulator or connect the device to the computer with a USB cable, then launch the Cordova application. You can run the Cordova application from Xcode or preload the application on the device and run it manually from the device’s home screen.
With the Cordova application running, switch to your desktop computer, fire up the Safari browser (remember, this works only on Macintosh OS X), and open the Develop menu. You should see your simulator or iOS device listed in the menu that appears. Figure 9.11 shows an example of this; my iPhone, appropriately named John’s iPhone, shows as an option in the menu. You should see the application running; select the index.html file as shown in the figure.
Safari will connect to the remote application, then open a new window as shown in Figure 9.12. From this new window, you have access to the code running within the Cordova container and the ability to interact with different parts of the application as it runs. In this example, I’m showing you one of the example camera applications from my Apache Cordova API Cookbook.
Figure 9.12 shows the contents of the index.html file; you can expand the different parts of the page and even edit the contents on the fly. As with the other examples I’ve shown in this book, when you highlight content in the HTML editor, the corresponding element will be highlighted on the screen. You can also view console output in the Console tab shown at the top of the figure.
Click on any of the code within the HTML file and you can edit the content directly. When you complete the changes, they will be immediately reflected in the mobile application. In Figure 9.13 you can see that I’ve changed the text on a button within the application while the application is running.
In real time, on the device, the Cordova application will update to show the new content as shown in Figure 9.14.
Very important to Cordova developers and something that’s not available on most other platforms is the ability to set breakpoints and step through the JavaScript code in a Cordova application. Figure 9.15 shows the application’s index.js with some breakpoints set.
When debugging an application and JavaScript execution halts at a breakpoint, you can control how the debugger continues execution of the code using buttons located at the top of the debug window; these buttons are highlighted in Figure 9.16.
You can remove all breakpoints so your JavaScript code executes without interruption by clicking the Clear Breakpoints button. By clicking the Continue button, you’re instructing the debugger to continue execution until the next breakpoint is encountered. Use the Step Over button when the debugger is stopped on a line of code that is making a call to a subroutine and you want the subroutine to execute without debugging. The debugger will execute the subroutine, then halt at the line of code that follows the call to the subroutine. The Step Into button does the opposite—it executes the subroutine and halts execution at the first line of executable code in the subroutine. When you’re done looking at the subroutine’s code, click the Step Out button to finish executing the subroutine’s code and return to the calling function.
While debugging the code, you can hover the mouse over any of the variables in the application and view the current value for the object as shown in the middle of Figure 9.17. You can also use the object inspector pane on the right side of the window to edit the current values associated with an object; this is highlighted in the upper-right corner of Figure 9.17. You can use this feature to simulate error conditions or change the values to adjust the flow of the application to allow you to test conditions that might not normally appear during testing.
I’ve only skimmed the surface of what you can do with the Web Inspector. Before you go too far with iOS development for Cordova, spend some time with this tool to understand all it can do for you. You’ll likely save time and frustration by using a tool like this for your testing and troubleshooting.
Wrap-Up
In this chapter, I’ve shown you how to test and debug your iOS Cordova applications in an iOS simulator and on a physical device. Using these tools should help simplify the development process and allow you to more quickly identify issues with your applications. Don’t forget that when you’re testing and debugging native plugins (described in Chapter 16, “Creating Cordova Plugins”), you’ll likely use both of these tools during your debugging efforts.