The geolocation plugin provides information about the device's current location that can be retrieved via Global Positioning System (GPS), network signals, and GSM/CDMA cell IDs. Note that there is no guarantee that the API returns the device's actual location.
In order to use the geolocation plugin in our Apache Cordova project, we need to use the following cordova plugin add command:
> cordova plugin add https://git-wip-us.apache.org/repos/asf/cordova-plugin-geolocation.git
In order to access the geolocation demo, you can click on the Geolocation list item. You will be introduced to the Geolocation page. You can click on the Get Current Position button in order to get your device's current position, as shown in the following screenshot:
Getting the device's position
The following code snippet shows the "geolocation" page:
<div data-role="page" id="geolocation">
<div data-role="header">
<h1>Geolocation</h1>
<a href="#" data-role="button" data-rel="back" data-icon="back">Back</a>
</div>
<div data-role="content">
<h1>Welcome to the Geolocation Gallery</h1>
<p>Click 'Get Current Position' button below to know where you are.</p>
<input type="button" id="getCurrentPosition" value="Get Current Position"/><br/>
<div id="position">
</div>
</div>
</div>As shown in the preceding "geolocation" page code snippet, it contains the following:
- A page header that includes a back button
- Page content that includes a
"getCurrentPosition"button to get the device's current position and a"position"div in order to display it
The following code snippet shows the "geolocation" page view controller JavaScript object that includes the event handlers of the page (geolocation.js):
(function() {
var geolocationManager = GeolocationManager.getInstance();
$(document).on("pageinit", "#geolocation", function(e) {
e.preventDefault();
$("#getCurrentPosition").on("tap", function(e) {
e.preventDefault();
var callback = {};
callback.onSuccess = onSuccess;
callback.onError = onError;
geolocationManager.getCurrentPosition(callback);
});
});
function onSuccess(position) {
console.log("position is retrieved successfully");
$("#position").html("Latitude: " + position.coords.latitude + "<br />" +
"Longitude: " + position.coords.longitude);
}
function onError(error) {
$("#position").html("Error code: " + error.code + ", message: " + error.message);
}
})();As shown in the preceding code snippet, the "pageinit" event handler registers the "tap" event handler on the "getCurrentPosition" button. In the "tap" event handler of the "getCurrentPosition" button, the device's current position is retrieved by calling the geolocationManager.getCurrentPosition() method.
The geolocationManager.getCurrentPosition(callback) method takes a callback object as a parameter that contains two attributes (onSuccess and onError) that refer to the following callbacks:
onSuccess(position): This callback will be called if the operation succeeds. It receives a position object (which represents the device's current position) as a parameter. Inside the success callback, the position's longitude and latitude information are displayed in the"position"div.onError(error): This callback will be called if the operation fails. It receives anerrorobject that contains the error information (error code and error message) as a parameter.
The following code snippet shows the geolocation manager JavaScript object that interacts with the Apache Cordova geolocation API (GeolocationManager.js):
var GeolocationManager = (function () {
var instance;
function createObject() {
return {
getCurrentPosition: function (callback) {
navigator.geolocation.getCurrentPosition(callback.onSuccess,
callback.onError,
{
timeout: 15000,
enableHighAccuracy: true
});
}
};
};
return {
getInstance: function () {
if (!instance) {
instance = createObject();
}
return instance;
}
};
})(); As shown, GeolocationManager is a singleton object that has a single method, getCurrentPosition(callback), as highlighted in the preceding code. This method uses the Cordova navigator.geolocation.getCurrentPosition() method in order to retrieve the device's current position.
The navigator.geolocation.getCurrentPosition(geolocationSuccess, [geolocationError], [geolocationOptions]) method has the following parameters:
geolocationSuccess: This represents the successful callback that will be called when the operation succeeds. It receives aPositionobject that holds the current position information as a parameter. InGeolocationManager,geolocationSuccessis set tocallback.onSuccess.geolocationError: This is an optional parameter that represents the error callback that will be called when the operation fails. It receives aPositionErrorobject that holds the error information (the code that represents the error code and the message that represents the error message) as a parameter. InGeolocationManager,geolocationErroris set tocallback.onError.geolocationOptions: This is an optional parameter that represents the geolocation options.
The geolocationOptions object has the attributes shown in the following table:
The Position object has the attributes shown in the following table:
|
Attribute name |
Description |
|---|---|
|
|
This represents a |
|
|
The Coordinates object has the attributes shown in the following table:
Note that navigator.geolocation has the following two more methods:
watchPosition(geolocationSuccess, [geolocationError], [geolocationOptions]): This can watch for changes in the device's current position. It returns a watch ID that should be used withclearWatch()to stop watching for changes in position.clearWatch(watchID): This can stop watching the changes to the device's position referenced by thewatchIDparameter.
We are now done with the geolocation functionality in the Cordova Exhibition app.