Cordova-Angular-Browserify Workflow

• Grunt used for automation.
• Uses Ionic for out of the box components.
• Bundled using Browserify!
• All dependencies managed via npm or Bower. npm is always the preference in a browserified project to stick to a CommonJS style.
• Sensible and/or common Cordova defaults applied.
• Uses ngCordova to ensure sensible and stable Cordova plugin use.
• Test structure for AngularJS is already setup and ready.
• Run tests in browser with Karma or from a webserver on your machine!
• Code Quality via JSHint, Lintspaces and Column Width Checks.
• EditorConfig file included to automatically configure editors.
• Localised Cordova version setup to avoid version mismatches.

Current Project Issues / Tasks

• The fh-js-sdk is currently not available through npm and the bower version doesn't contain the /dist folder. See this ticket
• grunt-browserify isn't correctly applying transforms. Current fallback is to use grunt-shell to invoke Browserify.
• If new client dependencies are added using bower we need to inject these into the Karma conf file similar to index.html.

Why?

This repository is intended to provide as base structure for starting and working with a Cordova application. It uses AngularJS as an application framework and Browserify is used to compile the application into a single bundle. This aids rapid development by allowing the developer to focus on writing code in the www directory and having automation handle updating their bundled JavaScript and index.html.

Working with Browserify and Angular is not as seamless as possible owing to the fact that AngularJS isn't designed with CommonJS (Node.js style requires) or AMD (Require.js) JavaScript patterns in mind. What does this mean for us? Well, in an ideal world we could have just a single script tag in our index.html and manage everything in JavaScript and all dependencies via npm. OK, that's my ideal world, but it'd be nice! Unfortunately this isn't possible with Angular yet due to the lack of it's support for CommonJS and AMD module loaders. This project works around that with its structure and makes it possible to compile an AngularJS project into a single JavaScript file albeit with Angular dependencies managed via Bower.

What do we get!?

Code Structure

Using EditorConfig, Lintspaces, and JSHint enforces better code quality and ensures higher standards. Keep them included and be stringent!

Manging Cordova Correctly

Many Cordova projects I've worked on assume you have Cordova installed globally and will use that to do builds causing a major headache due to version mismatches. Building should be accomplished by using a localised Cordova version installed as part of the project and as a result this project has a relative symbolic link setup to accomplish this. Simply use ./cordova in the root of this project to perform all Cordova tasks as this will use the version installed locally in the node_modules folder.

Angular Friendly Cordova Plugin Interfaces

Cordova plugins are awesome as they allow you to use native functionality via JavaScript calls! The issue is that in AngularJS applications we need to call out to these APIs using the JavaScript lib provided by the developer and then ensure that changes applied in our callbacks are applied correctly within the Angular lifecycle. Using ngCordova is an excellent way to resolve this issue and provide a simple interface to these plugins without the need to write our own wrappers. Bear in mind ngCordova is a very young project and if functionality you'd like is missing then fork it, add the function and submit a pull request!

A Single JavaScript Bundle

Part of the reason for using Browserify in this project is for speed enhancements. Compiling all files into a single bundle will improve application load time and performance. For release builds the bundle file can have source maps disabled and also be uglified to further improve performance and reduce the disk space required by the compiled project.

Inlined Templates for Improved Performance

Another neat feature I want to encourage as part of this project is inlining templates within your AngularJS application. You should do this using brfs as shown in the example below, Browserify and the Grunt build will handle the rest. This removes AJAX/File calls when your application is running and will improve performance. The only caveat is that the transform that inlines the template expects the format __dirname + '/some/path.extname' or __filename + '/some/path.extname'.

'use strict';

var fs = require('fs');
var tmp = fs.readFileSync(__dirname + '/../../templates/RandomNumber.html'
  , 'utf8');

module.exports = function () {
  return {
    restrict: 'E',
    template: tmp,
    link: function link ($scope) {
      $scope.number = Math.round(Math.random() * 100);
    }
  }
};

Setup

Simply download the ZIP file of this repo and you're ready to rock. If you don't have Node.js, Less, or Bower installed read the next section.

Prerequisites

To use this project you need to have Node.js and npm installed. Get both in a single download here. This project setup was designed using Node version 0.10.24.

Once you have Node.js and npm installed you'll need to install bower by entering the following in a terminal:

npm install -g bower [email protected]

Common Tasks

Note that all these commands are using the locally installed version of Cordova. To change the Cordova version being use just run:

npm install cordova@[VERSION] --save-dev

Copy Working www Files to Cordova Projects

./cordova prepare [ios/android]

Compile Current Projects

./cordova compile [ios/android]

Copy Files and Build

./cordova build [ios/android]

Emulate Platforms

These functions are provided by Cordova. In the root directory use the following commands.

./cordova emulate [ios/android]

Grunt Tasks

These are the current grunt tasks built into the Gruntfile.

test

Running this task will automatically open a browser and run all tests in the tests directory using Karma.

prepare:[debug | release]

This task will install all dependencies if required, browserify all source code into a single bundle, and inject bower dependencies into index.html.

If the release flag is used instead of debug then all CSS and JS are bundled and the www/ folder is updated.

build

Run prepare and copy all files from www/ to added Cordova platforms and compile. Basically cordova build with some extra sugar.

format

Run code quality checks to find syntax errors, style issues, and highlight lines over 80 characters.

serve

Serve code for local debugging. The code is "watched" meaning if any changes are made the 'build' task will be run and the code running in your browser will update without the need for a refresh.

Debugging

To make debugging this project easier you should enable source maps in your dev tools. This will allow you to inspect the source files in Chrome as usual on the Sources tab despite the fact that the files and concatenated using Browserify. Much win!