Geolocation

Description

Geolocation functionality allows pages to determine location information on supporting devices. The mwf.standard.geolocation library (includable as the touch library geolocation) provides a straightforward interface for this purpose whereby browser-side scripts can determine if a given device supports and allows a geolocation method and, if so, can ascertain the current longitude and latitude of the given device.

Implementation

Geolocation Methods

This library supports two geolocation methods:

• HTML 5 - [1] - iPhone OS, iOS, Android 2, some Android 1 devices, etc.
• Google Gears - [2] - Windows Mobile 6, Symbian OS, some Android 1 devices, etc.

A script may determine which of these methods is available through mwf.standard.geolocation.getType() where 1 represents HTML 5, 2 represents Google Gears, and 0 represents unavailable. Similarly, one may merely determine if geolocation is supported through mwf.standard.geolocation.isSupported(). Although this library supports two different methods with different underlying standards, it abstracts them into a common interface so, besides determining which library is supported, it does not matter which the device supports.

This API also supports both high accuracy and low accuracy retrievals of the position. By default, this library requests a high accuracy location. However, this behavior can be changed to take a low accuracy setting as follows:

mwf.standard.geolocation.setHighAccuracy(false);

Initial Retrieval of Location

To employ the framework's Javascript-driven geolocation library, the geolocation library must be specified as a parameter in the script tag that includes js.php:

<script type="text/javascript" src="../assets/js.php?standard_libs=geolocation"></script>

Geolocation does not happen instantly for two reasons:

1. Many devices prompt the user to determine if they're willing to disclose their location.
2. Geolocation equipment on most devices is only available on-demand to conserve power.

This means that, when a script attempts to retrieve geolocation information, the device will not respond immediately and instead there must be a way of retrieving this information when it becomes available. To handle this situation, the MWF Geolocation API employs callback functions, executed upon either a successful or unsuccessful retrieval of geolocation data:

mwf.standard.geolocation.getCurrentPosition(onSuccessCallback, onFailureCallback).

Consider the following example:

mwf.standard.geolocation.getCurrentPosition(
    function(pos){ alert("Latitude:"+pos['latitude']+", Longitude:"+pos['longitude']+", Accuracy:"+pos['accuracy']); }, 
    function(err){ alert("Err:"+err.message); }
);

In this case, this line will fire and then script execution will continue. Then, when geolocation succeeds, it will present an alert box with the latitude and longitude, or when it fails, it will present the error in an alert box.

Cached Retrieval of Location

On a page, more than one script may seek to leverage geolocation information, or it may need to on a recurring basis. However, such scripts may not always seek to go through the retrieval process. Therefore, in the event that mwf.standard.geolocation.getPosition(...) is called more than once, if the geolocation data has already been retrieved, this library will instead immediately return it to the callback.

A timeout on the cache can be set as follows, where ms is the number of milliseconds where the cached version will continue to be valid:

mwf.standard.geolocation.setTimeout(ms);

Continuously Retrieving Location

When determining a device's location through getCurrentPosition, consider the following issues:

• A device's location may change as the user moves

• Devices will return location data as quickly as possible. As a result, the device may initially return inaccurate data to ensure performance

To continuously poll a device's location data and execute a callback when a device's location changes or the location data becomes more accurate, use watchPosition:

mwf.standard.geolocation.watchPosition(onSuccessCallback, onFailureCallback)

watchPosition returns a unique ID number that can be passed to clearWatch to discontinue polling:

mwf.standard.geolocation.clearWatch(watchID)

The following example demonstrates how to poll a device's position until the level of accuracy reaches a certain threshold (30 meters):

var watchID = mwf.standard.geolocation.watchPosition(function(pos) {
	if(pos['accuracy'] <= 30) {
		mwf.standard.geolocation.clearWatch(watchID);
		alert("Accuracy within 30 meters, Latitude: " + pos['latitude'] + ", Longitude: " + pos['longitude']);
	}
},
function(err) {
	alert(err);
});