Apache Cordova (PhoneGap 3)

TAMZ 1

Lab 10

Native Applicationswith

Apache Cordova

Apache Cordova basics

Web-oriented (HTML5+JS+CSS3)But it's used for building embedded applications (with installation packages instead of mobile web)Large scope of platforms (Android, IOS, WP, Blackberry, Tizen, Ubuntu, Firefox OS, …)Common JavaScript API over different platforms, frameworks programming languages & IDEsUses features from HTML5 But you have to prepare the basic project for deployment to individual platforms

Instead of building locally, it is possible to use cloud-based build (may require public-available sources on Github)

How to use Apache Cordova

You add Cordova libraries into your project:the common platform-independent corethe platform-dependent API adaptation code

You use the native IDE for given platformSome IDEs, like NetBeans, offer support for seamless use of Apache Cordova

You can sell the application using platform-dependent store (App Store, Google Play, Windows Marketplace, …)It is possible to use (3rd-party) plugins

Plugin may be available only for some platforms, e.g. Android & iOSExamples: Calendar plugin, SMS plugin, …

Apache Cordova InstallationPlatform independentInstallation requires following tools and applications

Java Platform (JDK) - http://www.oracle.com/technetwork/java/javase/downloads/index-jsp-138363.html in environment properties define „JAVA_HOME“ with path to JDKNode.js - http://nodejs.org/download/Apache Cordova – using Node.js package manager: „npm install -g cordova“Apache Ant - http://ant.apache.org/bindownload.cgiGit - http://git-scm.com/ add environment „PATH“ to binaries

Based on the target platforms, you need to install development SDKs

Android SDK – add environment „PATH“ to Android SDK directoryWindows Phone SDK (VisualStudio)iOS SDK

Other platforms are supported as well (e.g. BlackBerry 10, FireFox OS, Tizen, HP WebOS,…)

Apache Cordova InstallationOn Linux in the laboratory please enter the following commands:

sudo su password : cisco

npm -g remove cordova npm -g install cordova@3.3.1-0.1.2

Check the installationcordova -v

Should return 3.3.1-0.1.2

Running Android Emulator (using CLI)emulator -avd Telefon

Using Apache Cordova Cordova is integrated in NetBeans

Create a New ProjectHTML5 => Cordova Application

You can also use Cordova CLINew project creationcordova create <project_PATH> [ID [NAME [CONFIG]]]

e.g. cordova create ex cz.vsb.mor03.Ex Examplecordova platform [{add|remove|update} <PLATFORM> | ls]

e.g. cordova platform add androidcordova plugin [{add|remove} <PATH|URI> | ls | search kw]

e.g. cordova plugin add org.apache.cordova.devicecordova build [PLATFORM] (alternative prepare → compile)cordova run [PLATFORM]cordova emulate [PLATFORM]cordova serve [PORT]

Basic Project Structure

Project contains several directories: platforms

Contains project for each selected platform Each project must be compiled in appropriate IDE (VisualStudio, Xcode, Android SDK).It is possible to installing IDE by using Phonegap Build.

pluginsContains source codes of all installed plugins for each platform.

wwwContains HTML5+JS+CSS3 application and configuration XML file, described later on.

Apache Cordova config.xmlThe configuration file is placed in the main web project directory or in a subdirectory based on given platformUses Widget specification mentioned earlier

extra namespace xmlns:cdv="http://cordova.apache.org/ns/1.0" for widget tag

The supplied configuration preference may alsoadd fullscreen setting: <preference name="fullscreen" value="true"/>enforce screen orientation:<preference name="Orientation" value="landscape" />

Values: default (both orientations), landscape, portrait

disable rubber-band scrolling bounce: <preference name="webviewbounce" value="true"/>be set to prevent overscrolling on iOS & Android:<preference name="DisallowOverscroll" value="true"/>

Some platform-specific preferences may be also included

Executing native code Apache Cordova offers a system of Native Plugins

There is a set of basic (core) plugins which should be available for all/most platforms.You can create a wrapper JavaScript class to provide missing/additional API.The native calls are executed by cordova.exec()

e.g. cordova.exec(function(winParam) {}, function(error) {}, "service", "action", ["firstArg", "secondArg", 42, false]);

Plugin repository has a plugin.xml file in top directory, which describes the plugin

platforms, their source files and configuration, …The native code differs platform-to-platform, e.g. Android

extends CordovaPlugin overrides method: public boolean execute(String action, JSONArray args, CallbackContext cCont) throws JSONException

You can publish your plugins for others via plugmanYou have to create an account first.

Basic Plugins

Battery StatusCameraConsoleContactsDeviceDevice MotionDevice OrientationDialogsFile (System)

File TransferGeolocationGlobalizationIn-App BrowserMediaMedia CaptureNetwork InformationSplashscreenVibration

GeolocationProvides information about the position of the device (e.g. latitude, longitude ...)Including navigator.geolocation

Methods: getCurrentPosition(accSuccess, [accError], [Options]) – accSuccess callback returns object position.id = watchPosition(accSuccess, [accError]) monitors changes in GPS position of the device. AccSuccess callback returns object position.clearWatch(id) stops the monitoring of the location changes. id must be the same as returned by watchPosition.

accSuccess : get the object position containing information with longitude, latitude, altitude, its precision, speed, azimuth and current time. Settings: {timeout: 30000} triggers error callback, if the position is not available for 30 seconds. Use enableHighAccuracy: true to get data from GPS receiver (otherwise, network-based location is used on Android and some other platforms).

Accelerometer & Compass pluginsIn both cases, the API copies geolocation API approach:

Acceleration – adds navigator.accelerometer Methods: getCurrentAcceleration(accSuccess, accError), id = watchAcceleration(accSuccess, accError[, opts]), clearWatch(id)Success: we get acceleration object with x, y, z including the effect of gravity (e.g. 0, 0, 9.81) and timestamp fieldOptions: we can specify freq. in [ms], e.g. { frequency: 3000 }

Compass – compass heading through navigator.compassMethods: getCurrentHeading(compassSuccess, compError), id=watchHeading(compassSuccess, compassError[, opts]), clearWatch(id)Success: we get heading object with magneticHeading, trueHeading (geographic to the North Pole, negative - can't be determined), headingAccuracy (deviation in [°] between reported and the true heading) and timestamp fieldsError: we get error object with code being

CompassError.COMPASS_INTERNAL_ERRCompassError.COMPASS_NOT_SUPPORTED

Options: we can specify frequency (see above) and filter (iOS)

Task (1b)Geolocation & Compass

Create one of the following applicationCreate a dashboard applications showing

Date and TimeGPS position (+ tolerance)Altitude (if available)Heading (based on compass or GPS)

+0.5b graphics with angles (automatically rotating to north )

Navigation to selected point (+1b)Useful equations: http://www.movable-type.co.uk/scripts/latlong.html