PhoneGap Hardware Manipulation

Accessing the device native APIs

Kamen Bundev

Telerik Academyacademy.telerik.com

Senior Front-End Developerhttp://www.telerik.com

Table of Contents

The Device Object

Notification API

Connection API

Events deviceready event pause/resume

events online/offline events Battery events Button events

Compass

Accelerometer

Geolocation

Camera

Contacts

Summary

Last time you've learned what PhoneGap is and how to compile your first mobile application with its SDK. Today we will delve deeper into its APIs to try and test its capabilities.

The Device Object Holds the description of the device

hardware and software, the application is currently running on:{ name = Device Model Name, phonegap = PhoneGap version, platform = returns the OS platform name, uuid = returns an unique device ID, version = returns OS version}

Notification API The Notification API

Initialized as navigator.notification

Holds several utility functions, oriented at showing or playing different user notifications

The available methods are:navigator.notification = { alert(message, alertCallback, [title], [buttonName]), confirm(message, confirmCallback, [title], [buttonLabels]), vibrate(milliseconds), beep(times)}

Connection API

The Connection API

Available under navigator.network Holds a single property – type Can be used to determine the

network/internet connectivity

Connection API (2)

When the application is initialized, network.connection.type can be:

Connection.NONE - No network connection detected Connection.ETHERNET - LAN network connection Connection.WIFI - Wireless B/G/N connection type Connection.CELL_2G - 2G connection type- GPRS or EDGE (2.5G)Connection.CELL_3G - 3G HSPA connection type Connection.CELL_4G - LTE or WiMax connection type Connection.UNKNOWN - the connection type cannot be determined

Connection API (3)

function checkConnection() {    var networkState = navigator.network.connection.type;

    var states = {};    states[Connection.UNKNOWN]  = 'Unknown connection';    states[Connection.ETHERNET] = 'Ethernet connection';    states[Connection.WIFI]     = 'WiFi connection';    states[Connection.CELL_2G]  = 'Cell 2G connection';    states[Connection.CELL_3G]  = 'Cell 3G connection';    states[Connection.CELL_4G]  = 'Cell 4G connection';    states[Connection.NONE]     = 'No network connection';

    alert('Connection type: ' + states[networkState]);}

checkConnection();

Events There are numerous events fired at different stages of PhoneGap's lifecycle One of these events is fired during

initialization,

Others - when certain hardware events happen

You can attach event handlers to these events in order to handle your application init or feedback

The deviceready event Fired when PhoneGap finishes its initialization You can use it to run the various

PhoneGap specific functions that require their back-ends to be ready

document.addEventListener("deviceready", onDeviceReady,

false);

function onDeviceReady() {// Fill out the PhoneGap version $

("#phonegap_version").text(device.phonegap);}

The pause/resume events

Due to limited resources on mobile phones (mostly RAM), when you switched out of an application

The OS freezes the app in background

(pauses it) and later restores it when you

focus it back

If the OS needs additional resources during

this frozen state, it may kill the application

completely

These two events are fired when the state

changes, the developer can for instance stop

some battery consuming services on pause

or maybe check for new data on resume

The pause/resume events (2)

document.addEventListener("pause", onPause, false);

document.addEventListener("resume", onResume, false);

function onPause() { navigator.compass.clearWatch(compassId);}

function onResume() { compassId = navigator.compass

.watchHeading(function (heading) {

// do something});

}

The online/offline Events

Fired when the user connects or disconnects to internet

Naturally you will use them only if you want to be aware when internet connection is availabledocument.addEventListener("online", onOnline,

false);document.addEventListener("offline", onOffline,false);

function onOnline() { // Handle the online event }function onOffline() { // Handle the offline event }

The batterystatus / batterylow /

batterycritical events Group of events, fired when a battery incident arises The batterylow and batterycritical

events are fired when the battery state reaches a certain level (device specific)

The batterystatus event is fired when the battery level changes with 1% or when the device's charger is plugged or unplugged

The batterystatus / batterylow /

batterycritical events (2) All these events receive an object

with two properties, when fired - level (battery level from 0-100) and isPlugged - boolean.window.addEventListener("batterystatus",

onBatteryStatus, false);

function onBatteryStatus(info) { console.log("Level: " + info.level +

" isPlugged: " + info.isPlugged); }

The Button Events Called when the user presses one of the phone's hardware buttons These events are available only in

Android and BlackBerry, limited to which buttons are available in the platform.backbutton (Android and BlackBerry)

menubutton (Android and BlackBerry)searchbutton (Android)startcallbutton (BlackBerry)endcallbutton (BlackBerry)volumedownbutton (BlackBerry)volumeupbutton (BlackBerry)

Compass (1) Most smartphone devices these days and even the newer featurephones have an embedded magnetometer Can be used to obtain the current

device heading according to the magnetic North of planet Earth

Compass (2) The Compass object dwells under the window.navigator object and sports the following properties and methods:navigator.compass = {

getCurrentHeading(compassSuccess, [compassError], [compassOptions]), int watchHeading(compassSuccess, [compassError],

[compassOptions]), clearWatch(watchId), int watchHeadingFilter(compassSuccess, [compassError], [compassOptions]), // Only on iOS. clearWatchFilter(watchId) // Only on iOS.}

Compass (3) compassSuccess receives one parameter - the current heading object, which consists of:

CompassHeading = { magneticHeading: The heading in degrees from 0-

359.99,trueHeading: The heading relative to the

geographic North in degrees 0-359.99. A negative value indicates that the true heading could not be determined. Some platforms return directly the magnetic heading instead,

headingAccuracy: The deviation in degrees between the reported heading and the true heading,

timestamp: The timestamp of the reading}

Compass (4)

compassError also receives one parameter with only one property:

compassOptions can contain additional options passed to the magnetometer:

CompassError = {code: The reported error code. Can be one either

COMPASS_INTERNAL_ERR or COMPASS_NOT_SUPPORTED}

CompassOptions = {frequency: How often to retrieve the compass

heading in milliseconds - default: 100,filter: The change in degrees required to

initiate a watchHeadingFilter success callback // Only on iOS.}

Compass Example

function onSuccess(heading) {var element = document.getElementById('heading');

element.innerHTML = 'Heading: ' + heading.magneticHeading;}

function onError(compassError) {alert('Compass error: ' + compassError.code);

}

var options = { frequency: 3000 }; // Update every 3 seconds

var watchID = navigator.compass.watchHeading(onSuccess, onError, options);

Accelerometer (1) Accelerometers lately are getting

cheaper by the dozen and are even more common than magnetometers in modern phones.

The accelerometer object is instantiated under window.navigator and includes the following methods and properties:

navigator.accelerometer = {getCurrentAcceleration (accelerometerSuccess,

[accelerometerError]),int watchAcceleration (accelerometerSuccess,

[accelerometerError],[accelerometerOptions]),

clearWatch (watchId)}

Accelerometer (2) When accelerometerSuccess gets called,

PhoneGap passes it an object with several properties:

accelerometerError gets called when the acceleration reading fails. It doesn't have arguments.

In accelerometerOptions you can specify the frequency to retrieve the Acceleration in milliseconds. The default is 10 seconds (10000ms).

Acceleration = {x: Amount of motion on the x-axis - range [0, 1],y: Amount of motion on the y-axis - range [0, 1],z: Amount of motion on the z-axis - range [0, 1],timestamp: Reading timestamp in milliseconds

}

Accelerometer Example

function onSuccess(acceleration) {alert('Acceleration X: ' + acceleration.x + '\n' +

'Acceleration Y: ' + acceleration.y + '\n' +'Acceleration Z: ' + acceleration.z + '\n' +'Timestamp: ' + acceleration.timestamp + '\

n');}

function onError() {alert('Error!');

}

var options = { frequency: 3000 }; // Update every 3 seconds,watchID = navigator.accelerometer.watchAcceleration

(onSuccess, onError,options);

Geolocation (1) PhoneGap includes Geolocation API to connect to the device GPS and read the latitude and longitude of the current geographic location.

Besides the device GPS, common sources of locationinformation can be GeoIP databases,

RFID, WiFi and Bluetooth MAC addresses,

GSM/CDMA cell IDs , The returned location can be inaccurate due to the current device positioning method.

Geolocation (2) The Geolocation API resides in the

window.navigator object.

navigator.geolocation = {getCurrentPosition (geolocationSuccess,

[geolocationError], [geolocationOptions]),

int watchPosition (geolocationSuccess,[geolocationError],[geolocationOptions]),

clearWatch (watchId)}

Geolocation (3) When PhoneGap calls

geolocationSuccess, it feeds it with the following position object:Position = {

coords: {latitude: Latitude in decimal degrees,longitude: Longitude in decimal degrees,altitude: Height in meters above the ellipsoid,accuracy: Accuracy level of the coordinates in

meters,altitudeAccuracy: Accuracy level of the altitude

in meters,heading: Direction of travel, specified in

degrees clockwise relative to the true north,speed: Current ground speed of the device, in

m/s},timestamp: The timestamp when the reading was taken.

}

Geolocation (4) When an error occurs, PhoneGap

passes the following error object to geolocationError callback:

PositionError = {code: One of the predefined error codes listed below,

message: Error message describing the details of the error

encountered, can be one of PERMISSION_DENIED, POSITION_UNAVAILABLE, TIMEOUT

}

Geolocation (5) You can adjust the accuracy of the

readings using the geolocation options as the last argument:

GeolocationOptions = {frequency: How often to retrieve the position in

milliseconds, deprecated, use maximumAge instead - default 10000,

enableHighAccuracy: Provides a hint that the application would like to receive the best possible results,

timeout: The maximum timeout in milliseconds of the call to geolocation.getCurrentPosition or geolocation.watchPosition,

maximumAge: Don't accept a cached position older than the specified time in milliseconds}

Geolocation Example

// onSuccess Callbackvar onSuccess = function(position) {

alert('Latitude: ' + position.coords.latitude + '\n' +'Longitude: ' + position.coords.longitude +

'\n' +'Altitude: ' + position.coords.altitude + '\

n' +'Accuracy: ' + position.coords.accuracy + '\

n' +'Altitude Accuracy:

'+position.coords.altitudeAccuracy+'\n'+'Heading: ' + position.coords.heading + '\n'

+ 'Speed: ' + position.coords.speed + '\n' +'Timestamp: ' + new Date(position.timestamp)

+ '\n');};

// onError Callback receives a PositionError objectfunction onError(error) {

alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n');

}

navigator.geolocation.getCurrentPosition(onSuccess, onError);

Camera (1) Provides access to the device camera Resides in window.navigator and

has just one method to work with:

Takes a photo using the camera or retrieves a photo from the device's album. The image is returned as a base64 encoded String or as the URI of the image file.

navigator.camera.getPicture(onSuccess, onFail, [Settings]);

Camera (2) Optional parameters to customize the camera settings:

cameraOptions = { quality: Quality of saved image - range [0, 100], destinationType: DATA_URL or FILE_URI, sourceType: CAMERA, PHOTOLIBRARY or SAVEDPHOTOALBUM,mediaType: PICTURE, VIDEO, ALLMEDIA,allowEdit: Allow simple editing of image before

selection,encodingType: JPEG or PNG,targetWidth: Width in pixels to scale image,targetHeight: Height in pixels to scale image

};

Camera Example

navigator.camera.getPicture(onSuccess, onFail, {

quality: 50,destinationType: Camera.DestinationType.FILE_URI

});

function onSuccess(imageURI) { var image = document.getElementById('myImage'); image.src = imageURI;}

function onFail(message) { alert('Failed because: ' + message);}

Contacts (1) Provides access to the device

contacts DB. Initialized as navigator.contacts.

Use the create() method to create a new contact object and then the save() method in it to save it to the phone database

Use the find() method to filter contacts and get the fields you need.

navigator.contacts = {create(properties),find(contactFields, contactSuccess,

[contactError], [contactFindOptions])}

contact = navigator.contacts.create({"displayName": "Test User"});

Contacts (2) contactSuccess returns an object or

array of objects with the following fields (if requested)Contact = {

id: Unique identifier,displayName: User friendly name of the contact,name: A ContactName object containing the persons name,nickname: A casual name to address the contact by,phoneNumbers: A ContactField array of all phone

numbers,emails: A ContactField array of all email addresses,addresses: A ContactAddress array of all addresses,ims: A ContactField array of all the contact's IM

addresses,organizations: A ContactOrganization array of all

organizations,birthday: The birthday of the contact,note: A note about the contact,photos: A ContactField array of the contact's photos,categories: A ContactField array of all user

categories,urls: A ContactField array of contact’s web pages

}

Contacts (3) There are also three methods in the

Contact object :

ContactName object consists of:ContactName = {

formatted: The complete name of the contact,familyName: The contacts family name,givenName: The contacts given name,middleName: The contacts middle name,honorificPrefix: The contacts prefix (example Mr. or

Dr.),honorificSuffix: The contacts suffix (example Esq.)

}

{save(onSuccess, [onError]) – saves the contact in the

device,clone() – clones the contact and sets its ID to null,remove(onSuccess, [onError]) – removes a contact

}

Contacts (5) ContactAddress consists of the

following fields:ContactAddress = {

type: A string that tells you what type of field this is (example: 'home'),

formatted: The full address formatted for display,

streetAddress: The full street address,locality: The city or locality,region: The state or region,

postalCode: The zip code or postal code,country: The country name

}

Contacts (6) ContactOrganization field consists of

the following properties:

And finally ContactField has only two:

ContactOrganization = {type: The field type (example: ‘remote'),name: The name of the organization,department: The department the contract works

for,title: The contacts title at the organization.

}

ContactField = {type: The field type (example: ‘office'),value: The value of the field (such as a phone

number or email address)}

Contacts (7) contactError receives an error object

with one of the following error codes:

contactFields is a requred parameter of the find() method, specified as an array of strings:

contactFindOptions is optional, but you can specify additional find settings with it:

["name", "phoneNumbers", "emails"]

ContactFindOptions = {filter: Search string to filter contacts - default "",multiple: Should return multiple results – default

false}

ContactError.UNKNOWN_ERROR, ContactError.INVALID_ARGUMENT_ERROR,ContactError.TIMEOUT_ERROR, ContactError.PENDING_OPERATION_ERROR,ContactError.IO_ERROR, ContactError.NOT_SUPPORTED_ERROR,ContactError.PERMISSION_DENIED_ERROR

Contacts Example

function onSuccess(contacts) { alert('Found ' + contacts.length + ' contacts.');};

function onError(contactError) { alert('onError!');};

// find all contacts with 'Bob' in any name fieldvar options = new ContactFindOptions();

options.filter="Bob“,fields = ["displayName", "name"];

navigator.contacts.find(fields, onSuccess, onError, options);

Summary

Today we covered part of the PhoneGap APIs, but there are still some left. As a homework, take a look at http://docs.phonegap.com

Read about the following APIs: Storage

Capture

Media

File

Homework

Write a small PhoneGap & jQuery Mobile application which should present a form to enter all data of a contact and then add it to the phone database. All the new contacts should have the same note.

Show in a list the saved contacts (filter them with the note) with a detail view, where all the previously entered data is shown.