App development with Cordova – how to

This is an ongoing post, meaning it will most likely change in the future.

This isn’t exactly a tutorial on how to develop mobile app with Cordova, but more of a list of checklists, hints and how-tos. Everytime I come back to the Cordova and app development I stumble upon outdated or scarce documentation on how to do things, so I decided to put all the knowledge I found in this post.

Development and deployment

I was working on an app about a year ago and then when I returned after all that time to work on a new app, I found out that a lot has changed since the last time I messed with cordova and phonegap. Official android documentation suggest developers should use their Android Studio, while I like to keep my options open – meaning I’d like to use more or less the same tools on Win and Mac environments, so that’s using the CLI (command line interface) way of working on apps, because it’s easier to jump between the two OSes – CLI commands are the more or less the same on every device. I COULD use Phonegap which promises a “code once deploy all” idea, but the execution leaves a lot to be desired.

So I thought to myself “well, I’ll use Eclipse on Win, because it builds app and directly deploy it to the device” and went with it, until I’ve hit the first possible block – installing cordova plugin and using it. That’s when I found out that Eclipse doesn’t really BUILD the .apk when I execute the Run command in IDE, it just… runs the app? I’m not really sure what it does, but it didn’t copy the config.xml settings, it didn’t compile installed plugins correctly (see the next two sections about www and config files) and when I ran the application nothing really worked – I was getting ReferenceError: Camera Is Not Defined error, while envoking the take picture function of cordova, which made me believe something went wrong while installing the camera plugin. So I totally switched to CLI building and plugin/camera actually worked!

So my workflow went something like this:

  1. CLI command: cordova create myApp
  2. CLI command: cordova platform add android
  3. CLI command: cordova plugin add org.apache.cordova.camera
  4. modified config.xml (in myApp root directory) and AndroidManifest.xml – see below
  5. plug the phone to the computer, accept RSA fingeprint
  6. CLI command: cordova run android

And when I envoked the take picture function (see below) I actually got the camera working without any issues, so I’m sticking to CLI environment now.

After installing the plugin I added the code below to config.xml (in root directory of my app)

    
<feature name="Camera">
  <param name="android-package" value="org.apache.cordova.CameraLauncher"/>
</feature>

Added this to AndroidManifest.xml:

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

I used the getPicture function as described here.

NOTE: Don’t forget to include cordova.js in your application HTML – make sure it’s relative to your app run location (without “/”).

What’s up with multiple WWW folders in Cordova app?

User MBilau said this over at stack overflow:

You should be editing the files in the /www/ file. When the CLI tools run prepare, which happens a lot, these files are copied into the appropriate platform’s /www/ file. (This is because each platform can have it’s web assets in a different location.) So do all of your work in the main /www/ folder – this is the one you should be putting into version control.

For more information try reading the documentation guide about The config.xml file which describes some of this: http://cordova.apache.org/docs/en/3.1.0/config_ref_index.md.html#The%20config.xml%20File

I’ve also written up a pretty long answer in another question that is pretty similar: Should a phonegap plugin be declared in the config.xml file?

Too bad I found this out when I already ran cordova plugin add command and overwrote about 20 hours of my work (yes, I know, backups and all that) in android/assets/www folder, that gets overwritten any time you run a cordova command.

Whats up with multiple config.xml files?

There is a pretty good explanation here, again by MBilau, some excerpts:

/myApp/
/www/
This is where your “cross-platform’ files go. The build tools copy these files over to the correct asset folder for each platform, like /assets/www/ for android or just /www/ for iOs. This is where you should be doing most/all of your work and is what should probably be version controlled.

/platforms/
/android/
/ios/
These will only appear after `cordova platform add`. You should generally not touch these file as they are recreated quite often, although changes will persist.

/plugins/
/android/
These will only appear after `cordova plugin add`. They pretty much just contain the native and web plugin code for all platforms that a plugin supports.

/ios/
/merges/
This is where you can place platform-specific code that you write that will get merged in with your cross platform source, see the “customize each platform” section of: http://cordova.apache.org/docs/en/3.0.0/guide_cli_index.md.html

www folder in your app root location is your go-to location when working on a app:

You should make all of your changes to files in /www/, which is the “cross platform” source code. Whatever is in this folder will generally get copied and propagated to the platform level www folder when you use the command line tools (whether its /assets/www for Android or just /www/ for iOS). This way, you only need a single source folder for your app – this is the folder that you should have under version control.

 Useful Cordova CLI commands

  • cordova run --list displays all devices you can run your app on (plugged devices and emulators)
  • cordova run --target=XXXXX runs on one of the devices, listed with –list command
  • cordova emulate android runs your application on emulator
  • android list avd displays all installed android emulators
  • emulator.exe -avd emulator_name starts the specified emulator_name
  • android avd starts android virtual device manager
  • adb start-server starts adb, so you can run apps on plugged mobile devices

Genymotion emulator, VirtualBox and Unable to load R3 module error

I’ve been using Genymotion emulator because it seriously kicks ass (lightning fast compared to default Android emulator) and encountered a strange VirtualBox error when starting Genymotion devices (or any for that matter) – Unable to load R3 module. It seems VirtualBox cant run virtual devices if you have altered windows installation that runs VB. I’ve actually altered some of my win .dll files when installing various windows theme patchers, so that could be the problem – the other computer I use don’t have any altered .dll files and VB runs without any issue. VB version 4.3.12 and older should work okay.

org.apache.cordova.camera

Android version 4.4 broke some stuff regarding getting the images from gallery, where you’d get an invalid image location that could’t be resolved when used in <img> src attribute (for example).

Here’s a fix for that issue:

if (imageURI.substring(0,21)=="content://com.android") {
	photo_split = imageURI.split("%3A");
	imageURI = "content://media/external/images/media/"+photo_split[1];
}

With this snippet you get the actual file location in the system.

Signing your APK

To sign your .apk file use Cywgin and following two commands:

keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg RSA -keysize 2048 -validity 10000

Enter your (developer) information and then follow it up with the jarsigner:

jarsigner -verbose -sigalg SHA1withRSA -digestalg SHA1 -keystore my-release-key.keystore my_application.apk alias_name

Zipalign your APK

To zipalign your apk file use the following command (where unaligned_app.apk stands for your current built file and aligned_app.apk for the new aligned apk file. You can also use -f parameter to overwrite the original filename):

zipalign -v 4 unaligned_app.apk aligned_app.apk

Make sure you have the zipalign in system PATH variables (normally in android-sdk/build-tools/sdk_version/).