11. Windows Development with Cordova
Cordova provides good support for the Windows platform, supporting Windows 8.x and Windows Phone 8.x. In this chapter, I show you how to use the Microsoft development tools to build and test Cordova applications for the Windows platform. What’s unique about this chapter is that it covers smartphone as well as desktop OS development as Cordova supports both for the Windows platform. The Cordova project currently supports two Windows targets: windows (targets Windows 8, Windows 8.1, and Windows Phone 8.1) and wp8 (targets Windows Phone 8).
Windows development is done using Microsoft Visual Studio. A free version of Visual Studio is available from Microsoft and is pretty easy to use. I’ll also cover some new tools from Microsoft that make cross-platform development for Cordova easier.
Windows versus WP8 Projects and Cordova
Before we get too far into this topic, I want to fill you in on how the different Windows platforms are supported by Cordova. Cordova supports Windows Phone 8 as well as another platform Cordova calls simply windows. You’re creating a project for Windows Phone 8 when you issue the following Cordova CLI command:
cordova platform add wp8
When you open the project in Visual Studio, you’ll see something similar to what is shown in Figure 11.1.
Notice that the Cordova project (the Debug.csproj file shown in the figure) is a C# project. Even though the default project type in Visual Studio for Windows Phone 8 applications was a JavaScript project, for Windows Phone 8 on Cordova, the development team implemented the Cordova container as a C# application instead. What this means for Cordova developers is that you won’t be able to use the JavaScript debugging capabilities of Visual Studio to debug your application. Instead, you’ll have to use something like weinre (described in Chapter 5, “The Mechanics of Cordova Development”) to debug your applications.
Microsoft has since shifted to a universal app approach (http://goo.gl/d5suuO) for Windows applications that allows you to support multiple Windows targets for a single project. The Cordova windows platform creates a universal Windows app project for your Cordova application when you use the CLI to add a platform to your project using the following command:
cordova platform add windows
The project will support both Windows 8 and Windows 8.1 (desktop operating systems) as well as Windows Phone 8.1. When you open the project in Visual Studio, you will see a dialog similar to the one shown in Figure 11.2.
In this example, notice that there are multiple projects in the platform folder and they’re all JavaScript projects. The CordovaApp.Phone.jsproj is the project file for the Windows Phone 8.1 project, and the other .jsproj files are for Windows 8.1 desktop (CordovaApp.Windows.jsproj) and Windows 8 desktop (CordovaApp.Windows80.jsproj).
For these projects, you’ll be able to leverage the JavaScript debugging capabilities of Visual Studio to help troubleshoot your Cordova applications. I’ll show you more about how those work later in the chapter.
You’re going to select the target platforms for your application based on the specific requirements for your application, but there’s a huge difference between the debugging capabilities available to Cordova Windows 8.1 projects and what’s available for Windows Phone 8 applications. I am going to cover only the Cordova windows platform support in this chapter as I imagine the Cordova team will drop support for Windows Phone 8 sometime soon.
Windows Phone Limitations and Security Restrictions
Now that you understand a bit about the different platform options available to you, I need to let you know about some limitations of running Cordova applications on the Windows platform.
JavaScript alert Not Supported
As you know, I use the JavaScript alert method in my applications to help me troubleshoot problems with the applications. Cordova fails silently when there’s a JavaScript error in an application, so while doing initial testing of an application, I always put in a call to alert just so I can tell that the web application body has loaded:
function onBodyLoad() {
console.log("Entering onBodyLoad");
alert("onBodyLoad fired");
document.addEventListener("deviceready", onDeviceReady, false);
}
Well, that doesn’t work as the JavaScript alert method is not supported in universal Windows apps. When you try to execute the onBodyLoad function in Visual Studio, the debugger will wake up and deliver the error message shown in Figure 11.3.
Microsoft’s answer on this topic is that a Windows app is not a browser, and alert is a function of the browser. Microsoft suggests that you use the MessageDialog class described at http://goo.gl/AeAD4X, and this book’s technical reviewer, Ashwin Desai, gave me the following example:
function myAlert(message) {
if (typeof (Windows) !== 'undefined') {
new Windows.UI.Popups.MessageDialog(message, 'Alert').showAsync().done();
} else {
alert(message);
}
}
Application Security Model Limitations
Because Windows, more than any other mobile platform, is heavily used in corporate environments, Microsoft has implemented a suite of security enhancements that are designed to protect customers from malicious software. On Windows 8.1, Cordova creates a universal Windows app based on the Visual Studio JavaScript template for Windows Store apps. For these apps, the Cordova app does not contain a WebView; instead, the app’s web content runs in the WWAHost process on the device. The WWAHost process implements a sandbox around the web application content, and that causes some issues for dynamic Cordova applications. You can read about some of the restrictions at http://goo.gl/z750or.
The biggest impact on Cordova developers seems to be from third-party JavaScript libraries trying to inject dynamic content into a Cordova application. To help accommodate developers using these tools, Microsoft released the JavaScript Dynamic Content shim for Windows Store apps which can be found at http://goo.gl/pWTGyu. All you need to do is add a reference to the shim’s JavaScript file, winstore-jscompat.js, toward the beginning of your Cordova application’s code (before any other scripts are loaded or executed), and it will relax the manner in which checks are performed by the WebView.
Many of these restrictions are expected to go away with Windows 10.
Windows Development System Requirements
Before we start talking about the tools, it’s important to understand a bit about the development environment you will need to create Windows applications for Apache Cordova. The Cordova team recently dropped support for Windows 7 and Windows Phone 7 applications, so you can really only create Windows 8.x applications using the current version of Apache Cordova.
The Android developer tools will run on Windows 7 or Windows 8, and for iOS development you must have a system running Macintosh OS X. In order to develop applications for the latest version of Windows, you will need to have a system running Windows 8 (you can build Windows 8 apps on Windows 8; you’ll need to be running Windows 8.1 in order to build apps for Windows 8.1).
As a developer, you have several options. You can use two systems—one running Windows 8.1 and the other running OS X—or you can run both environments on an OS X system using virtualization software like VMware Fusion. You can install Xcode and the iOS development tools on the OS X system, install the Android tools on either OS X or Windows, then install the Microsoft tools on the Windows 8.1 system. Understand, though, that there’s no way to configure one developer workstation and a single OS for Cordova development for all of the supported platforms. If you add Ubuntu Touch development to the mix, described in Chapter 10, “Ubuntu Development with Cordova,” you’ll need yet another OS (physical or virtual) to develop applications.
For this book, I did most of the development on a Mac Mini and did all of my Windows testing on separate VMware Fusion VMs running on the Mini. One VM ran Windows 7 and another Windows 8.1 (both legal licenses, of course). I installed the iOS, Android, and Firefox OS tools on the OS X partition and Android, Firefox OS, and Windows tools on the Windows virtual machines.
The problem with Windows Phone development, though, is that the device simulators have some pretty hefty requirements. When I wrote PhoneGap Essentials, I couldn’t even get the simulators to run in a VM; I had to do all of my Windows Phone development on one of my lab machines. For this book, I was able to configure the virtual environment so that the simulators will run. Microsoft provides some pretty detailed instructions for how to configure VMware Fusion to run Visual Studio and the device simulators at http://goo.gl/fqms6P. Unfortunately, those instructions are for when you’re creating a brand-new Windows 8.1 VM in Fusion; for my development environment, the VMs already existed, so I had to refer to the article at http://goo.gl/aBuJ7d for information on how to make the necessary changes to an existing VM. Either way, problem quickly solved; thanks, Microsoft!
Windows Phone Development Tools
To build Cordova applications for Windows 8.x, you will need to install Microsoft Visual Studio. For developing Windows Phone applications, you’ll need the Windows Phone SDK. There are different versions of Visual Studio available to you. Visual Studio Express is free and includes the tools you need to create Windows Phone applications. You can download Visual Studio Express from the Windows Phone Dev Center located at http://goo.gl/FeXc2r. Download the software and install it on your development workstation, running Windows 8.1, of course. When you launch Visual Studio for the first time, you will be prompted to register with Microsoft for a free developer license as shown in Figure 11.4.
To obtain a license, you’ll have to have an existing Microsoft account or create a new one. If you don’t have one, don’t worry—the account is free; all you’ll need to do is register to get one. After you have logged in with your Microsoft account, Visual Studio will obtain a license, then display the confirmation dialog shown in Figure 11.5. At this point, Visual Studio Express is installed and all ready to go.
Another option is to use the commercially licensed Visual Studio Professional. You may wonder why you would want to use the Professional version of Visual Studio when the Express edition is free; that’s because the hybrid development tools Microsoft provides work only with Visual Studio Professional (today). To use Visual Studio Professional, you’ll need to acquire a license, then install the software on your development system.
Windows App Store Setup
Next, there are some administrative steps you must follow in order to be able to deploy Windows Phone applications into the Windows Phone Store or onto a physical device. To help you get started with the process, take a look at “How to Deploy and Run an App for Windows Phone 8” on Microsoft’s web site at http://goo.gl/AoSCk6.
First you’ll need to create a Microsoft account. Accounts are free and can be obtained at https://signup.live.com. Next, you’ll need to register as a member of the Windows Phone Dev Center at https://dev.windowsphone.com/join. Joining the program isn’t free, but it doesn’t cost that much. With your registration, you get the ability to deploy your applications to a physical device and into the Windows App Store.
Configuring a Windows Phone Device for Application Testing
The Visual Studio development environment allows you to easily deploy and test Windows Phone applications onto a Windows Phone emulator. However, you should always test your Cordova applications on a physical device before publishing them to an app store. For Windows Phone development, before you can test your applications on a physical device, you must first register the device for development with Microsoft. The registration process is pretty simple; you can find Microsoft’s instructions for the process at http://goo.gl/NloJmR.
To register a Windows Phone device, first you will need to power on the device and connect it to your Windows 8 desktop via a USB cable. Since each registered device has to have a unique name, open Windows Explorer on your desktop system and change the name of the device to something you know is unique, perhaps using your initials in the device name as shown in Figure 11.6.
In Windows 8 or later, bring up the All Apps view and under Windows Phone 8 SDK open the item labeled Windows Phone Developer Registration. You will see a screen similar to the one shown in Figure 11.7.
In this example, my Windows Phone device is locked, so I have to unlock the device and click the Retry button to allow it to connect to the device. With this completed, you should see a screen similar to the one shown in Figure 11.8.
When you click the Register button, you will be prompted to log in with your Microsoft account. Once you are logged in, you will see the screen shown in Figure 11.9. At this point, the device is registered with Microsoft and can be used to test your Windows applications.
You can manage your registered devices from the Account summary page of the Windows Phone Dev Center located at http://goo.gl/kKbXmb as shown in Figure 11.10. Microsoft allows you to register only three devices for development, so if you have to support testing an application across a wide range of devices, you may be spending a lot of time on this page. To remove a registered device, click the Remove link to the right of the device you wish to remove.
Cordova Development Workflow Using Visual Studio
In this section, I’ll show you how to use Microsoft Visual Studio to test your Cordova applications. The instructions given here are essentially the same regardless of whether you’re running Visual Studio Express or Visual Studio Professional. Later in the chapter, I’ll show you a dramatically different development workflow using some cool tools Microsoft has provided.
Creating a Project
Before you begin, you must first have a Cordova application to work with. Using the Lunch Menu application example I’ve shown elsewhere in this book, create a new Cordova application project by opening a terminal window, navigating to the folder where you want the project created, then issuing the following commands:
cordova create lunchmenu com.ac4p.lunchmenu "Lunch Menu"
cd lunchmenu
cordova platform add windows
cordova platform add wp8
In this case, I’ve created the Lunch Menu application and added both universal Windows app (windows) and Windows Phone 8 (wp8) platforms to the project. I’ve added the platforms through separate commands just for demonstration purposes; I could just as easily have added both platforms in a single command using
cordova platform add windows wp8
At this point, you’ll have a Cordova project all ready to be opened in Visual Studio so you can test the application. You’ll be able to run the Windows application directly from Visual Studio. For the Windows Phone application, you’ll be able to run the application on device simulators or physical devices connected to the development system (properly registered, of course, as described in the previous section).
When working with Windows applications, as with all other Cordova projects, you’ll be editing the web application code for your project in the project’s www folder—be sure to execute the cordova prepare command before trying to work with the project in Visual Studio:
cordova prepare
The CLI will copy the web content over into the platforms/wp8/www and platforms/windows/www folders. You can see an example of the files that are created in Figure 11.11.
For the remainder of this section, I will focus on universal Windows app development using Visual Studio. The steps are essentially the same for Windows Phone 8 applications, except for the debugging capabilities I will show.
Opening a Cordova Project
Now that you have created a Cordova project for Windows Phone 8, open Visual Studio. When the development environment opens, it will display a screen similar to the one shown in Figure 11.12.
To open the Cordova project, click the Open Project link shown on the left of Figure 11.12, or open the File menu and select Open Project. Visual Studio will display the Open Project dialog shown in Figures 11.1 and 11.2 (depending on which platform you will be working with). Select the Microsoft Visual Studio Solution file (the file with the.sln extension) as shown in the figures and click the Open button to continue.
For some reason, the default Windows solution has the Windows 8 project selected as the default startup project. Because of this, when you open a Windows 8 solution in Visual Studio 2013, you may be prompted to upgrade the project as shown in Figure 11.13.
Since that project is targeted at Windows 8, you really won’t want to retarget it to Windows 8.1. You can open the project in an older version of Visual Studio in order to build the project for Windows 8. The project already has Windows 8.1 and Windows Phone 8.1 projects, so you can get around this warning by right-clicking one of those projects and selecting Set as StartUp Project as shown in Figure 11.14. That will change the default project and eliminate the warning.
When the project opens, the Solution Explorer will show you all of the files in the project as shown in the right side of Figure 11.15. From here you can open the different web content files generated by the CLI; keep in mind, though, that the files shown here are copied from the Cordova project’s www folder. Any changes you make to the web application content here will need to be copied back to the Cordova project’s www folder before they can be applied to other platform projects. In this example, I’ve opened the Windows Phone 8 project’s index.js file and set some breakpoints.
Running a Cordova Application in Visual Studio
To test applications in Visual Studio, use the options highlighted at the top of Figure 11.15. Click the Play symbol to the left of the device name to run the application. The drop-down list to the right of the Play icon allows you to select the emulator or a physical device where the application will run.
To run the application on a physical device, make sure the device is powered on, unlocked, and connected to the development system using a USB cable. When running on an emulator, the emulator window will open, start the emulated OS, and run the application as shown in Figure 11.16. The emulator looks and works like a regular device. You can swipe, click, and work with the application just as you would on a physical device.
Controlling the Windows Phone Emulator
The icons to the right of the figure provide developers with some additional control over the emulator. You can change the orientation of the device, expand the size of the emulated device, or change the zoom level. The double bracket (>>) at the bottom of the list is used to open an Additional Tools window that provides the developer with some additional capabilities for manipulating the emulator. I’m going to cover only a few here; poke around in the emulator to see what else it can do.
The Accelerometer pane of the Additional Tools window is shown in Figure 11.17; it allows a developer to manipulate the orientation of the emulator along three axes. You can hold the primary mouse button down over the dot in the middle of the device image and move it around to position the emulated device. You can also select preset orientations or play back recorded orientation changes. This is a simple way to test mobile applications that leverage the accelerometer and an excellent way to test applications that use the Cordova Device Motion API.
Figure 11.18 shows the Location pane; from here you can manipulate the emulator’s location. You can search for a specific location or address and push it into the emulated device’s GPS coordinates. You can also play back recorded trips. This is a simple way to test mobile applications that leverage the device’s geolocation capabilities and an excellent way to test applications that use the Cordova Device Orientation (Compass) API.
When writing documentation for your application, you can easily grab device screen shots using options in the Screenshot pane shown in Figure 11.19.
Capture a screen shot by clicking the Capture button, then save the file to disk using the Save button.
Debugging Cordova Applications Using Visual Studio
Microsoft Visual Studio offers a robust set of debugging capabilities. Since a Cordova project for the windows platform is a universal Windows app project and the default application type for universal Windows apps is a JavaScript project, the debugging capabilities of Visual Studio can be leveraged. As a developer, you’ll have full access to all the developer and debugging tools Visual Studio offers. And, when I talk about the Visual Studio Tools for Apache Cordova later in the chapter, you’ll see that Microsoft has figured out how to apply these tools to Android and iOS projects as well.
When you open a source file in Visual Studio, you can click in the margin to set breakpoints in the application’s JavaScript code as shown in Figure 11.20. Then, while the application is running in a simulator or on a physical device, when the application hits one of those breakpoints, the application will halt and you can use capabilities of the Visual Studio debugger to step through the code, set watches, view the contents of local variables, and more.
When the application halts when it hits a breakpoint, you can use the debugging controls highlighted in the upper-right corner of Figure 11.20 to control how the application runs from there. Figure 11.21 describes the purpose of each control.
When debugging an application, Visual Studio automatically opens the Locals panel shown in Figure 11.22. In this window, you can view the properties of all local application objects, including global objects. You can even click on one of the object’s values and change the value before continuing execution of the application.
With the Watch panel shown in Figure 11.23, you can right-click on one of the variables or properties in the application and define a watch for it. Then, as the application executes, you can see the value currently assigned to the object in the panel.
There’s a lot more you can do with the debugging capabilities of Visual Studio; as this is a book on Apache Cordova and not Visual Studio, I’ll leave it up to you to dig more into the capabilities. For more information, see Mario Hewardt, Advanced .NET Debugging (Boston: Addison-Wesley, 2009), and Mario Hewardt, Advanced .NET Debugging LiveLessons (Boston: Addison-Wesley, 2011).
Using Visual Studio Tools for Apache Cordova
Now that I’ve shown you the out-of-the-box capabilities of the Microsoft Windows development tools you can use with your Cordova applications, it’s time to show you some tools Microsoft has produced that are specially tailored for Cordova applications.
A while back, Microsoft announced the Multi-Device Hybrid Apps Extension (MDHAE) for Visual Studio; the tools are still in beta, but they’re cool enough and functional enough that I can cover them here. The tools are currently in Community Preview 2, and I’m not sure whether they will be released by the time you read this. I’m pretty excited about these tools as they solve a lot of problems for Cordova developers and they’re from Microsoft of all places, a company that is well known for its professional-grade development tools.
Note
After I wrote this, Microsoft renamed the plugin to Visual Studio Tools for Apache Cordova and released Community Preview 3. Some of the options described herein may have changed by the time you read this.
You can read more about the tools at http://goo.gl/5S4lOR. Go to that link or search the Internet for “Microsoft Multi-Device Hybrid” to download the installer. I’ll describe how to install and use the tools in this section, but you can also find details, and perhaps another perspective, at http://goo.gl/dtMq2C.
Visual Studio runs only on Microsoft Windows (today), and the extension works only with the commercial license for Visual Studio (not Express). So you will be able to install this extension only on Windows and only after you have already installed a working version of a compatible version of Visual Studio Professional. Once you’ve downloaded the extension, launch the installer and follow the prompts to install it on your development workstation.
One of the most interesting aspects of the extension for Cordova developers is that it installs a complete, functional Cordova development environment along with the extension. When you start the installation, one of the first things you’ll see, after agreeing to the license terms, is the dialog shown in Figure 11.24. Notice that Ant, Git, Java, Node, the Android SDK, and more are preselected for installation. This essentially makes everything I covered in Chapter 3, “Configuring a Cordova Development Environment,” obsolete.
Now, before you go off and rip out everything you did in Chapter 3, let me explain the implications of this. The MDHAE installation installs all of this stuff because it needs all of the tools in order to do what it does. It also installs a copy of the Cordova CLI, but it installs an older copy of the CLI than you may have installed in Chapter 3. So, the MDHAE components are tightly connected, and you can install them as your only Cordova developer tool chain, or you can install them alongside an existing installation of the Cordova development tools.
If you let the installer install everything as shown in the figure, you’ll end up with a complete development environment that works seamlessly within Visual Studio. For my installation, I knew I wanted to use the latest version of the Cordova CLI, and I already had many of the tools installed, so I deselected the stuff I already knew I had installed as shown in Figure 11.25. Because I took a custom approach, there was some additional configuration that I had to do; I’ll show you this in a little while.
Once you’ve completed the installation, you should have some new project options available to you in Visual Studio. To see this, open Visual Studio and create a new project by opening the File menu and selecting New. In the dialog that appears, select the JavaScript project type and you should see a new option, the Blank App (Apache Cordova) option shown in Figure 11.26.
Populate the project properties in the bottom of the dialog and click the OK button to create the project; Visual Studio will create the project, then open it for you.
Since I didn’t allow the MDHAE to install some of the required components, as I had already installed them, Visual Studio will create the project, but when it opens the project, it will display the warning page shown in Figure 11.27. This happens because there are some additional steps that must be performed first. Remember, this is happening only because of the way I installed the tools. If you followed the default installation, you shouldn’t see this warning.
It’s telling me that it can’t find the Android SDK, Git, and Java; I know I have those tools installed, so this can be easily fixed. After each warning message, there’s a link to instructions you can follow to resolve the warning. In my case, they all led me to the Visual Studio Options dialog shown in Figure 11.28.
Remember from Chapter 3 that I had you set the ANT_HOME and JAVA_HOME environment variables. Apparently I could have added ADT_HOME and GIT_HOME variables as well. What I did here was close Visual Studio, then add an ADT_HOME environment variable pointing to my ADT installation. When I opened Visual Studio again and opened the Options dialog, I could see that the fix worked.
Next, I could have done the same with a GIT_HOME variable, pointing it to my Git installation, or I could check the override checkbox and populate the input field with the path pointing to my Git installation.
With those changes in place, I can open Visual Studio, open the Lunch Menu application I created, and see a screen similar to the one shown in Figure 11.29. At this point, what I have is a regular Visual Studio project with some additional stuff in it that I will describe next.
The MDHAE doesn’t create the standard Cordova project folder as shown in Chapter 4, “Using the Cordova Command-Line Interfaces,” and Chapter 5; if you look at Figure 11.30, you’ll see the project folder it created. Notice that the project doesn’t have a www folder; everything is simply stored in the project folder. You do have the merges folder, though, and, although I didn’t test it, you could probably add a hooks folder (described in Chapter 6, “Automation and the Cordova CLI”) here as well.
As with the typical Cordova project, the project’s config.xml file describes the project to the CLI; I described many of the settings in Chapter 5. You can edit the file in Visual Studio by double-clicking it, which will open the editing pane shown in Figure 11.31. The Application pane, shown in the figure, contains general settings for the application and allows you to configure which orientations the application supports as well as to enable full-screen operation.
The Domain Access pane shown in Figure 11.32 allows you to define the endpoint whitelist for the application, giving you control over what remote resources the application can connect to.
The Plugins tab shown in Figure 11.33 allows you to specify the Cordova plugins you want to add to the project. The HDMAE doesn’t add the plugins when you make changes here; instead, it stores this information in the config.xml, then adds the plugins using the Cordova CLI during the build process for each target platform.
The Packaging tab shown in Figure 11.34 hosts some additional settings for Windows 8 and Android projects.
In the project folder, there are a few other files of interest. The getting-started guide shown in Figure 11.29 is the Project_Readme.html shown in Figure 11.30. You can open it at any time directly from the project folder.
The MDHAE doesn’t use the default web application project files the Cordova CLI provides; instead, it provides its own. Listing 11.1 shows the contents of the project’s index.html file. This is the app’s startup page, and it’s a really simple page that displays nothing but a text string.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>LunchMenu</title>
<!-- LunchMenu references -->
<link href="css/index.css" rel="stylesheet" />
</head>
<body>
<p>Hello, your application is ready!</p>
<!-- Cordova reference, this is added to your app when it's built. -->
<script src="cordova.js"></script>
<script src="scripts/platformOverrides.js"></script>
<script src="scripts/index.js"></script>
</body>
</html>
Of interest is the platformOverrides.js file. Notice the merges folder in Figure 11.30; the hybrid project includes a mechanism for having custom JavaScript code for each target platform through this overrides file. The platformOverrides.js in the project folder is essentially empty, but the merges folder contains a folder for each target platform and a platformOverrides.js file with platform-specific code. Take a look at each merges folder to see what overrides are included with the project.
The project’s index.js file is different from the default Cordova project as well; you can see this in Listing 11.2. The JavaScript code sets up the deviceready event listener as well as ones for pause and resume, plus it includes a link pointing to the documentation for the application.
// For an introduction to the Blank template, see the following
// documentation:
// http://go.microsoft.com/fwlink/?LinkID=397704
// To debug code on page load in Ripple or on Android
// devices/emulators: launch your app, set breakpoints,
// and then run "window.location.reload()" in the JavaScript Console.
(function () {
"use strict";
document.addEventListener('deviceready', onDeviceReady.bind(this), false);
function onDeviceReady() {
// Handle the Cordova pause and resume events
document.addEventListener('pause', onPause.bind(this), false);
document.addEventListener('resume', onResume.bind(this), false);
// TODO: Cordova has been loaded. Perform any initialization that
//requires Cordova here.
};
function onPause() {
// TODO: This application has been suspended. Save application
//state here.
};
function onResume() {
// TODO: This application has been reactivated. Restore
//application state here.
};
})();
At this point, you have an application all ready to run. You should update the index.html, index.js, and other application files to suit your application’s needs. When it comes time to run the application, you can execute it using the Visual Studio Run button I showed earlier in the chapter. If you look at Figure 11.35, you’ll see that there are a few more options than were available previously—there are now options for the Ripple Emulator as well as options for executing on a generic device and Android emulators.
This is part of the real power behind this tool. By doing one simple installation and creating a project in Visual Studio, I now have access to debug my Cordova application on a Windows device or emulator (phone or desktop), Android, and Ripple.
To demonstrate Ripple integration, I clicked the Ripple—Nexus (Galaxy) option and Visual Studio opened the Ripple Emulator window shown in Figure 11.36. You can learn more about Ripple in Chapter 5.
Back in Visual Studio, if I pick Device in the Run menu, I can select from a multitude of devices from the device drop-down window shown in Figure 11.37.
Now, here’s where it gets interesting. Notice that iOS is listed in Figure 11.37; that’s because through this tool Visual Studio has the ability to build and deploy to iOS devices as well. Pretty cool, eh? Microsoft accomplishes this using a remote agent running on a Macintosh computer; you can read more about how to install the agent at http://goo.gl/GVb2tk, but I’ll show you how here.
The agent must be installed on a network-connected Macintosh that is visible from the system running Visual Studio. You can run Visual Studio on a Windows VM and connect to the host Macintosh computer, or you can have two systems, one running OS X and another running Windows.
To install the agent, log on to your Macintosh computer, open a terminal window, and execute the following command:
sudo npm install -g vs-mda-remote --user=$USER
There’s a lot of stuff that gets installed, so it might take a while, but when it’s all done you should see the terminal output shown in Figure 11.38. Notice that it installed Cordova 3.5.0; that’s because it’s configured to use its own Cordova files to operate, instead of what you may already have installed, and it locks you into an older version of the CLI than is currently available. This is probably the only drawback I see with using this tool. According to Microsoft, this limitation is going away with a future release of the tools.
With the remote agent installed, you’ll have to manually start it when you want to use it. To start the agent, open a terminal window (or use the one that’s already open) and issue the following command:
vs-mda-remote --buildDir <build-directory>
The build-directory parameter refers to the target folder the remote agent will use as its working directory. Visual Studio will pass it files, which it will write to this folder before kicking off a build. So, for my development workstation I used the following:
vs-mda-remote --buildDir /Users/jwargo/builds
When you execute the command, the agent will launch, then display the configuration information shown in Figure 11.39. Don’t close the terminal window; you’ll need to have it running in order to be able to run iOS applications from Visual Studio.
Notice in the figure that the Remote build Express server (the remote agent) is listening on port 3000. You’ll need that port as well as the system’s IP address in order to configure Visual Studio. To get the IP address, open the Macintosh Settings application, then select the Network option; you should see a screen similar to the one shown in Figure 11.40. In this example, my Macintosh has a wired Ethernet connection and I’ve highlighted the system’s IP address in the figure.
You can also get the IP address from the terminal (not the one running the remote agent; you need to leave that terminal window alone until you’re done with it); simply execute the following command:
ifconfig | grep "inet " | grep –v 127.0.0.1
You can see the output from this in Figure 11.41. The command filters the lines beginning with inet and skips lines that refer to localhost (127.0.0.1).
Write down the port number and IP address and switch back to the system running Visual Studio. Open the Tools menu and select Options, then navigate to the Remote Agent Configuration shown in Figure 11.42. Enable remote iOS processing by setting that value to true as shown in the figure, then populate the Macintosh system’s IP address in the Host field and the port in the Port field and click the OK button.
When this is complete, you can select iOS in the device list shown in Figure 11.37, then the Run menu will have a few extra options in it as shown in Figure 11.43. The Ripple options should be there regardless of whether or not you configured the remote agent, but now you have the ability to run on an iOS device or simulator.
Select Simulator—iPhone, for example, and Visual Studio will kick off a remote build on the Macintosh system running the remote agent. The remote agent terminal window will update, showing you what it’s doing during this process as shown in Figure 11.44.
After the remote build completes, the remote agent will launch the device simulator, then deploy and launch the application as shown in Figure 11.45.
What you’re seeing here is an iOS build and deploy to a simulator initiated by Visual Studio running on a Windows system. As I write this, you can’t remotely debug this application from Visual Studio, but you can use the Visual Studio debugger to do real-time debugging of the application running on Android and Windows as I described earlier in the chapter. At PhoneGap Day 2014, Microsoft announced that the next release of the hybrid tools would support remote debugging of iOS applications, so perhaps by the time you read this it will have become a reality.
Wrap-Up
In this chapter, I showed you how to use the free developer tools from Microsoft to test your Cordova applications for Windows Phone 8 and several other mobile device platforms as well. As I’ve described, this is pretty powerful stuff. Now, with a single installation and the robust Visual Studio, you can build, deploy, test, and debug cross-platform Cordova applications from a single IDE.