Create your first app using Apache Cordova

Apache Cordova is an open-source mobile development framework. It allows you to use standard web technologies - HTML5, CSS3, and JavaScript for cross-platform development. Applications execute within wrappers targeted to each platform and rely on standards-compliant API bindings to access each device's capabilities such as sensors, data, network status, etc. To know more about Apache Cordova, please check out the documentation.

Here, we will have a quick walkthrough of steps and challenges faced in the installation, first app creation, and building of it using Apache Cordova.

The majority of the content is based on the documentation and added the notes extra based on my experience also here along with that.

Installing the Cordova CLI

on OS X and Linux:

   $ sudo npm install -g cordova

 on Windows:

   C:\>npm install -g cordova

Create the App

Go to the directory where you maintain your source code, and create a cordova project:

$ cordova create hello com.example.hello HelloWorld

This creates the required directory structure for your cordova app. By default, the cordova create script generates a skeletal web-based application whose home page is the project's www/index.html file.

Below help content comes up on running cordova command.

Synopsis

 

    cordova command [options]

 

Global Commands

    create ............................. Create a project

    help ............................... Get help for a command

    telemetry .......................... Turn telemetry collection on or off

    config ............................. Set, get, delete, edit, and list global cordova options

 

Project Commands

    info ............................... Generate project information

    requirements ....................... Checks and print out all the requirements

                                            for platforms specified

 

    platform ........................... Manage project platforms

    plugin ............................. Manage project plugins

 

    prepare ............................ Copy files into platform(s) for building

    compile ............................ Build platform(s)

    clean .............................. Cleanup project from build artifacts

 

    run ................................ Run project

                                            (including prepare && compile)

    serve .............................. Run project with a local webserver

                                            (including prepare)

 

Learn more about command options using 'cordova help <command>'

 

Aliases

    build -> cordova prepare && cordova compile

    emulate -> cordova run --emulator

 

Options

    -v, --version ...................... prints out this utility's version

    -d, --verbose ...................... debug mode produces verbose log output for all activity,

    --no-update-notifier ............... disables check for CLI updates

    --nohooks .......................... suppress executing hooks

                                         (taking RegExp hook patterns as parameters)

 

Examples

    cordova create myApp org.apache.cordova.myApp myApp

    cordova plugin add cordova-plugin-camera

    cordova platform add android

    cordova plugin add cordova-plugin-camera --nosave

    cordova platform add android --nosave

    cordova requirements android

    cordova build android --verbose

    cordova run android

    cordova build android --release -- --keystore="..\android.keystore" --storePassword=android --alias=mykey

    cordova config ls

Add Platform

All subsequent commands need to be run within the project's directory, or any subdirectories:

$ cd hello

Add the platforms that you want to target your app. We will add the 'ios' and 'android' platform and ensure they get saved to config.xml and package.json:

$ cordova platform add ios
$ cordova platform add android

To check your current set of platforms:

$ cordova platform ls

Install pre-requisites for building

To build and run apps, you need to install SDKs for each platform you wish to target. Alternatively, if you are using browser for development you can use browser platform which does not require any platform SDKs.

To check if you satisfy requirements for building the platform:

$ cordova requirements 

This will give a Gradle related error if in case Gradle is not installed or it is not detected by Cordova.

Cordova uses Gradle to build. So install Gradle by following the manual installation steps for Windows. Best way to get Gradle in Windows is to install Android Studio as it comes with Gradle.

Build the App

By default, cordova create script generates a skeletal web-based application whose start page is the project's www/index.html file. Any initialization should be specified as part of the deviceready event handler defined in www/js/index.js.

Run the following command to build the project for all platforms:

$ cordova build

You can optionally limit the scope of each build to specific platforms - 'ios' in this case:

$ cordova build ios

Test the App

SDKs for mobile platforms often come bundled with emulators that execute a device image, so that you can launch the app from the home screen and see how it interacts with many platform features. Run a command such as the following to rebuild the app and view it within a specific platform's emulator:

$ cordova emulate android

Following up with the cordova emulate command refreshes the emulator image to display the latest application, which is now available for launch from the home screen:

Alternately, you can plug the handset into your computer and test the app directly:

$ cordova run android

Before running this command, you need to set up the device for testing, following procedures that vary for each platform.

Add Plugins

You can modify the default generated app to take advantage of standard web technologies, but for the app to access device-level features, you need to add plugins.

A plugin exposes a Javascript API for native SDK functionality. Plugins are typically hosted on npm and you can search for them on the plugin search page. Some key APIs are provided by the Apache Cordova open source project and these are referred to as Core Plugin APIs. You can also use the CLI to launch the search page:

$ cordova plugin search camera

To add and save the camera plugin to package.json, we will specify the npm package name for the camera plugin:

$ cordova plugin add cordova-plugin-camera
Fetching plugin "cordova-plugin-camera@~2.1.0" via npm
Installing "cordova-plugin-camera" for android
Installing "cordova-plugin-camera" for ios

Plugins can also be added using a directory or a git repo.

Use plugin ls (or plugin list, or plugin by itself) to view currently installed plugins. Each displays by its identifier:

$ cordova plugin ls
cordova-plugin-camera 2.1.0 "Camera"
cordova-plugin-whitelist 1.2.1 "Whitelist"

Using merges to Customize Each Platform

While Cordova allows you to easily deploy an app for many different platforms, sometimes you need to add customizations. In that case, you don't want to modify the source files in various www directories within the top-level platforms directory, because they're regularly replaced with the top-level www directory's cross-platform source.

Instead, the top-level merges directory offers a place to specify assets to deploy on specific platforms. Each platform-specific subdirectory within merges mirrors the directory structure of the www source tree, allowing you to override or add files as needed. For example, here is how you might use merges to boost the default font size for Android devices:

·        Edit the www/index.html file, adding a link to an additional CSS file, overrides.css in this case:
<link rel="stylesheet" type="text/css" href="css/overrides.css" />

·        Optionally create an empty www/css/overrides.css file, which would apply for all non-Android builds, preventing a missing-file error.

·        Create a css subdirectory within merges/android, then add a corresponding overrides.css file. Specify CSS that overrides the 12-point default font size specified within www/css/index.css, for example:
body { font-size:14px; }

When you rebuild the project, the Android version features the custom font size, while others remain unchanged.

Updating Cordova and Your Project

After installing the cordova utility, you can always update it to the latest version by running the following command:

$ sudo npm update -g cordova

Use this syntax to install a specific version:

$ sudo npm install -g cordova@3.1.0-0.2.0

Run cordova -v to see which version is currently running. To find the latest released cordova version, you can run:

$ npm info cordova version

To update platform that you're targeting:

$ cordova platform update android --save
$ cordova platform update ios --save
...etc.