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.
