Mobile Development with Cordova (Phonegap): Chapter 3

Chapter 3: Creating Your Project

Creating the Empty Project

Open a Terminal, and "mkdir" and "cd" your way into a folder where you'll want to start placing your projects. For me, I created a "Mobile Projects" folder underneath my home folder.

This command boostraps your app, copying in some template files for a very Hello, Cordova sort of app:
    cordova create exampledir biz.example.firstapp "Example Application"

The 3 parameters are:
- the name of the folder to create, e.g. exampledir will be the name of the folder
- the application name in "reverse DNS" convention, e.g. org.greeninfo.myfirstapp
- The name of the app itself as it will be named in the store and on the device, e.g. include spaces but not version numbers, and keep it brief and snazzy

Tip: It's very tedious to change the name of an app after it has gotten underway, so you really need to get this right the first time. Yes, really. Just like in that Dilbert episode.

There's a certain list of platforms and plugins that we will always use (Android and iOS, File access, FileTransfer, Network Status, etc.) so let's just get them out of the way now:

    cd exampledir
    cordova platform add ios
    cordova platform add android
    cordova plugin add org.apache.cordova.file
    cordova plugin add org.apache.cordova.file-transfer
    cordova plugin add org.apache.cordova.geolocation
    cordova plugin add org.apache.cordova.network-information

You should get familiar with the cordova command-line utility, as well as what plugins exist. In Cordova 3, virtually everything is implemented as a plugin.

A Quick Rundown

This is a brief overview of some of the files and folders. There's a lot more that I can't cover in detail here, just some highlights:

www
This folder houses your HTML, JavaScript, and CSS. This is where you'll do 99% of your work.

config.xml
This provides build options and metadata about your app. You will definitely want to edit this, especially to set the author attribution, the app description and name, and so on.

platforms/ios/ProjectName.xcodeproj
This is the Xcode project file (actually a folder, but OS X treats it specially). Open this to set special iOS-specific settings, such as hiding the status bar. This will be covered in a different article, where we describe tips and tricks for doing the actual programming.

platforms/ios/ProjectName/Resources
For the iOS platform, this stores additional assets such as icons and splash screens.

platforms/android/ant.properties
This configuration file will be used by ant when compiling the Android version of the app. This file does not exist by default, and is covered in more detail in a different article.

platforms/android/res
For the Android platform, this stores additional assets such as icons and splash screens.

platforms/android/assets/www
platforms/ios/www
These folders hold a temporary copy of your www folder content. This is used during the build process. It is not necessary to edit these copies in addition to the main www folder; they are automated copies.

Setting Up Certificates (iOS, Xcode)

Remember, the key store and certificates and provisioning profiles you set up a long time ago? Let's go ahead and configure these utilities to use them, signing your app with the keystore (Android) or Provisioning Profile (IOS).

In Finder open up your project folder, then open up two files, one for iOS and one for Android.

Android:
Start by creating a file under your project platforms/android folder, named ant.properties
It should have these two lines, of course customized to the keystore you generated earlier:
    key.store=/users/USERNAME/android.keystore
    key.alias=keystorealias

Tip: Every time you use cordova run android --device it will prompt for the passphrase. This is a little annoying, but not very compared to some of the problems you'll have. :-) For myself, I prefer to have my APKs always signed so I don't run into problems later, when I forget to sign a build, or send someone an unsigned APK.

iOS:
Open platforms/ios/PROJECTNAME.xcodeproj This will open Xcode.

Select the project itself (probably the first item on the upper-left panel) and set some project properties, most notably the Team. When you select a Team you'll be prompted to enter an Apple identity; it will then download a certificate and provisioning profile for you, saving them into the application's Xcode settings.

Run It On Emulators

Let's start by running the Hello Cordova app on iOS and Android emulators. If you won't be using emulators, I suppose you can skip this step.

The Cordova CLI apps make it pretty easy to start up the app in an Android or iOS emulator:
    cordova emulate android
    cordova emulate ios

A poorly-documented feature, is that you can specify the device for testing: iPad, iPhone 4, etc. with the --target parameter.
    cordova emulate ios --target="ipad (retina)"

For iOS there's a specific list and you may find this set of aliases quite handy. Add these to your .bash_profile and start a new Terminal, and your emulation commands will be quite simple:
alias emipad='cordova emulate ios --target="ipad (retina)"'
alias emiphone3='cordova emulate ios --target="iphone (retina 3.5-inch)"'
alias emiphone4='cordova emulate ios --target="iphone (retina 4-inch)"'
alias emiphone='cordova emulate ios --target="iphone"'

For Android, target names are the names of AVDs (as listed in adb devices) and you can make up a similar set of "emulate android" aliases for your particular AVDs and devices.

Run It On Hardware: iOS

First, plug your iPad into your Mac. You may be prompted as to whether the iPad should trust this computer, allowing the computer to inject applications onto it, etc. Naturally, you should accept.

Refresh the iOS platform directory which will form the app:
    cordova prepare ios
If you skip this step, you'll be running an older version of your app, and that can get confusing if you're  debugging something not visually obvious.

Then in Xcode, look in the upper-left where you'll see a list of platforms, e.g. iPhone Retina 3.5" Select your hardware device from the list. Now go to Product / Run  This will compile the app and then inject it onto your iPad and then launch it. Very simple and reliable.

Tip: Every time I plug in my iPad or Android, a photo application pops up. I don't know that there is any way to stop this, and it's very annoying.

Run It On Hardware: Android (ADB)

Make sure that your Android device has "USB Debugging" enabled. This is buried in your Settings panel, in a submenu called Developer Options. Then plug your tablet into the Mac's USB port, and the Android should report "USB Debugging Connected" at the same time as it does its usual USB behavior (offering to enable SD card sharing, or to Charge Only).

On the Mac, in a Terminal, you should be able to see the device when you run adb devices
Your device has an ID that may or may not be intuitive, may or may not contain the manufacturer name. But, that's the ID# and it'll stay the same for that device.

You should now be able to cordova run android --target=ABC123456 and have the app run on that specified device. Again, see adb devices for the listing. This does allow you to run on multiple Android devices simultaneously.

If your device doesn't show in adb devices, then fuss with it a bit:
- Unplug it and plug it back in.
- While leaving it plugged in, toggle USB Debugging off and on.
- Unplug it and plug it back in. (again)
- Try another USB cable. (some low quality cables have issues)
- Try another USB port. (nobody knows why)
- Try connecting directly to the computer's USB port instead of to the USB hub. (some hubs lose enough power that USB Debugging malfunctions)
- Try another device.

Tip: On some devices such as my LG SPectrum, it's so flaky that I gave up completely on using adb. I use the other technique described next. But I went to Fry's and bought a $60 Blu brand phone, and it works perfectly with adb.

Run It On Hardware: Android (Manual Copy, Slow But Works)

Compile the Android app, forming an APK file:
    cordova build android --release

The resulting APK is in  platform/android/ant-build

Plug in your Android to the Mac, and turn on USB Storage mode. On the Mac, copy the APK file onto the Android, eject the Android device, turn off USB Storage, and install the APK by opening it.

Tip: Android 4.x has App Installer, which makes short work of finding and installing the APK. It will scan local storage, find all APK files, and present you with a list. Three taps and you're testing.

Now Get Hacking !

If everything has worked out so far, then you're ready to start actually writing your own application. Start replacing content in the www  folder, installing plug-ins, making adjustments to config.xml, and figuring out the myriad problems involved in any complicated app. :-)