Getting started with PhoneGap, part 2

The first part of this mini-series showed you what PhoneGap is, and how it can help you develop mobile applications with familiar technologies.

In this second part we’ll look at some more device APIs.

The geolocation API

This API is used on a variety of websites to make the site (or in this case the mobile application) location aware.

A simple example that would get you the user’s latitude, longitude and altitude coordinates and show them on the screen would look something like:

document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
    navigator.geolocation.getCurrentPosition(success, error);
}
function success(position) {
    var div = document.getElementById('geolocation');
    div.innerHTML = 'Latitude: ' + position.coords.latitude + '
' + 'Longitude: ' + position.coords.longitude + '
' + 'Altitude: ' + position.coords.altitude;
}
function error() {
    alert('We were unable to retrieve your location');
}

The first part of this code should look very familiar to you, that is the part where we check if the device is ready and if it is, we use the geolocation API to get the device’s current position.

If we succeed in getting the location we just need to place the coordinates we want in a div with the ID of geolocation and as you can see getting this value is pretty intuitive seeing as their names are self-explanatory. Finally if we don’t retrieve the user’s location we show an error.

In the example above I’ve used the getCurrentPosition function and this function only gives us the location when the success function is fired, if we want something that constantly watches the coordinates and updates them on the fly we would use the watchPosition function which also takes a third parameter specifying the frequency with which we would like to update the coordinates. Not a lot would need to change in our code:

var watchID = null;
function onDeviceReady() {
watchID = navigator.geolocation.watchPosition(success, error, {       frequency: 5000 });
}

As you can see if you want your coordinates to update every 5 seconds the onDeviceReady function is all that would change.

Camera API

One thing we use daily on our smartphones is the camera, and there thousands of apps that take advantage of the functionality.

PhoneGap also gives us a simple way to capture images and use them in our application, the method for doing this is camera.getPicture().

This method takes three parameters, the third one being the options, of which there are many:

• Quality — The quality of the image ( from 0 to 100 ).
• destinationType — Choose the format of the return value. It could be DATA_URL and that returns the image as base64 encoded string or FILE_URI and that returns the URI of the image.
• sourceType — this option sets the source of the picture from three options: camera, photolibrary or savedphotoalbum.
• allowEdit — If set to true this option allows the user to edit the image before it’s saved.
• encodingType — Here you can set whether you want your image to be a PNG or JPG.
• targetWidth and targetHeight — The width and height of the image if you want it scaled. (Must be used together.)
• mediaType — If you selected your PictureSourceType as photolibrary, here you can specify the type of media that can be selected, you can choose from : picture, video or all media.
• saveToPhotoAlbum — If set to true, this option will save the captured image to the photo album after capture.
• correctOrientation — If set to true, it rotates the image to correct for the orientation of the device during capture.

As you can see with all these options you can do anything you please with the camera.

To use this in a simple manner, taking a picture, allowing the user to edit it and then showing the image up in the screen we would use something like:

var pictureSource;
var destinationType;
document.addEventListener("deviceready",onDeviceReady,false);
function onDeviceReady() {
    pictureSource = navigator.camera.PictureSourceType;
    destinationType = navigator.camera.DestinationType;
}
function getPhoto(imageData) {
    var image = document.getElementById('image');
    image.style.display = 'block';
    image.src = "data:image/jpeg;base64," + imageData;
}
function capturePhoto() {
    navigator.camera.getPicture(getPhoto, error, {allowEdit :true, quality: 90 });
}
function error(errorMessage) {
    alert(errorMessage);
}

and the HTML would be:

Capture Photo

As always we wait for PhoneGap to be loaded and when it is, we set the destinationType and sourceType ( by default they are camera and data_url). After this we wait for the user to click the button and when she does the capturePhoto function fires and here we place our options and also the error and success callbacks.

If the function succeeds our getPhoto function fires and we set the img element’s display value to block and then place the image in its src attribute. And since our allowEdit option is true the user will be able to edit the image before it shows up in the app.

Conclusion

In this second part we looked at two more API’s we have at our disposal with PhoneGap, the Geolocation API and the Camera API, and how easily these two can be used to our benefit.