Your First Cordova App

Part 2 of 2. Part 1 can be found here: Write Once, Ship Everywhere.

  1. Install Cordova
  2. Build an app
  3. ???
  4. Profit!

1. Install Cordova

  1. Install Cordova-CLI
  2. Install SDKs for each platform you want to support
    • Android: SDK
    • Windows: SDK
    • Windows Phone: SDK, msbuild
    • iOS: SDK, XCode
  3. Install the tools
    • Google Chrome
    • Apache Ripple
    • Apache ANT
    • Java 7
    • Apple iTunes
    • SQLite
    • WebSocket4Net
  4. Configure the environment
    • Setup the command line targets
    • Configure the environment variables (PATH, etc)

Well, you could do all the above, but wouldn't you much rather want to install Visual Studio Tools for Apache Cordova. Visual Studio Tools for Apache Cordova packages up all those dependencies and configuration into a nice installer ensuring that you avoid those moments of "Did I already install XYZ? Shit, is the path set correctly?"

If you don't already have Visual Studio, the community edition is free!

2. Build an App

The Cordova application that I will build will be the Cordova version of an HTML-based presentation: http://jpoon.github.io/Cordova-Reveal/. The source code can be found here, and as you can see, is completely HTML/JavaScript/CSS.

New Project

Once Visual Studio and the Visual Studio Tools for Apache Cordova are installed, you should see a new project template:

After creating a new project, Visual Studio will do some basic sanity checks to ensure that your environment is setup properly. If everything is kosher, you should see the screen below. Otherwise, Visual Studio will display a warning with a call to action.

Alright! Before we dive any deeper, let's take a look at how the default project is organized:

  • /css - CSS files.
  • /images - Image assets.
  • /merges - Platform specific web assets. Files deployed under /merges will override matching files. For instance, /scripts/platformOverrides.js will be replace on the Android platform with /merges/android/scripts/platformOverrides.js if it exists.
  • /res - Platform specific resources and customizations (icons, screenshots, ANT properties).
  • /scripts - JavaScript files.
  • /plugins - If you have any plugins installed, they will appear under this directory.
  • config.xml - Cordova configuration file
  • index.html - Entry point to the application. Can be overridden using the config.xml.

You can follow the above convention of organizing your files. In my case, as I want a quick and dirty solution to prove the concept, I'm going to put all of my source code for the app under /reveal such that I can do a git submodule to the original repo: https://github.com/jpoon/Cordova-Reveal.

There are a couple of changes that I had to make in order to convert the web app to a hybrid (Cordova) app:

  • All file references must be local. For instance, we can no longer download JQuery via a CDN, the file must be local to the project.
  • If your web app contains /node_modules that are not crucial to serving the page, you can remove them from the Android build like so. This has the added benefit of making your build faster and your APK smaller.

App Configuration

If you open the config.xml within Visual Studio, a nice UI will pop-up to allow you to configure common metadata for the project.

This is also where you can install plugins. As my hybrid application requires device information, notification, and camera information, I will install those three plugins.

Debugging

As is common with Visual Studio, the debugging experience is amaze-balls. With the Visual Studio Tools for Apache Cordova, you can debug the application across 4 different platforms:

  • iOS
  • Android
  • Windows
  • Windows Phone

Within each of these platforms, there are further debugging options that you can choose from including using ripple, an emulator, or a device.

Ripple

The Apache Ripple emulator runs as a web app inside a Google Chrome and can be used to simulate your app on a number of devices and platforms and provides basic support for core Cordova plugins like Geolocation and Device Orientation.

The Ripple emulator provides a quick and dirty first step in building your app. Anything more than this, I would recommend using platform-specific emulation or the actual device.

iOS

In order to build for iOS, one must have an OSX machine. Run the vs-mda-remote agent on a Mac and this will allow you to build, run, and debug your application on a Mac via your Visual Studio instance running on your Windows machine.

Android

Visual Studio Tools for Apache Cordova comes pre-packaged with two different emulators: Google Android Emulator, VS Android Emulator.

What's the difference? As most can attest, the default Android emulator suffers from performance issues (e.g. slow) and it uses VirtualBox for emulation. As a result, if you were to also develop for Windows Phone (which uses Hyper-V for emulation), you would have to go back and forth between turning on/off Hyper-V. Here's where the Visual Studio Android emulator comes in. It is faster and uses Hyper-V which means you can run your Windows Phone and Android emulator at the same time.

Windows Phone

You'd get the same options here as you would expect: emulator or device.

Windows

You have several deployment options: simulator, local machine, or remote machine. The simulator uses your local machine but also makes it easy to emulate device capabilities like location and orientation.

3. ???

4. Profit!

Be sure the share the wealth.