ucla/mwf — Issue #90: Wiki: Updates to Geolocation Page
Author: loganfranken
Created: 2012-02-03 04:05:09+00:00
State: open

Hey, I'm not sure if there's a better way of going about this, but here are some suggested updates to the geolocation page:

1. Remove this part about the `isSupported` internals: "though this is the same as a non-zero check on mwf.touch.geolocation.getType()."

2. Change "Geolocation equipment on most devices is on-demand only to conserve power." to "Geolocation equipment on most devices is only available on-demand to conserve power."

3. Change "Given such a situation, Javascript is inclined not to block but rather to employ callbacks for an event-driven approach. While HTML 5 Geolocation and Google Gears support slightly different approaches for registering these callbacks, both geolocation layers do provide a mechanism for registering callbacks and this library abstracts them into a single interface call:" to "To handle this situation, the MWF geolocation API employs callback functions, executed upon either a successful or unsuccessful retrieval of geolocation data:"

4. Add the following text for `watchPosition`:

### 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.touch.geolocation.watchPosition(onSuccessCallback, onFailureCallback)
```

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

```
mwf.touch.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.touch.geolocation.watchPosition(function(pos) {
if(pos['accuracy'] <= 30) {
mwf.touch.geolocation.clearWatch(watchID);
alert("Accuracy within 30 meters, Latitude: " + pos['latitude'] + ", Longitude: " + pos['longitude']);
}
},
function(err) {
alert(err);
});
```