Peter Lubbers - Pro HTML 5 Programming

CHAPTER 4 ■ USING THE HTML5 GEOLOCATION API
• The successCallback function parameter tells the browser which function you
want called when the location data is made available. This is important because
operations such as fetching location data may take a long time to complete. No
user wants the browser to be locked up while the location is retrieved, and no
developer wants his program to pause indefinitely—especially because fetching
the location data will often be waiting on a user to grant permission. The
successCallback is where you will receive the actual location information and act
on it.
• However, as in most programming scenarios, it is good to plan for failure cases. It
is quite possible that the request for location information may not complete for
reasons beyond your control, and for those cases you will want to provide an
errorCallback function that can present the user with an explanation, or perhaps
make an attempt to try again. While optional, it is recommended that you provide
one.
• Finally, an options object can be provided to the HTML5 Geolocation service to
fine-tune the way it gathers data. This is an optional parameter that we will
examine later.
Let’s say that you’ve created a JavaScript function on our page named updateLocation() in which
you update the contents of the page with the new location data. Similarly, you’ve created a
handleLocationError() function to handle the error cases. We’ll examine the details of those functions
next, but that means that your core request to access the user’s position would be the code shown in the
following example:
navigator.geolocation.getCurrentPosition(updateLocation, handleLocationError);
The updateLocation() Function
So, what happens in the updateLocation() call? It’s actually quite simple. As soon as the browser has
access to the location information, it will call updateLocation() with a single parameter: a position
object. The position will contain coordinates—as the attribute coords—and a timestamp for when the
location data was gathered. While you may or may not need the timestamp, the coords attribute
contains the crucial values for the location.
The coordinates always have multiple attributes on them, but it is up to the browser and the
hardware of the user’s device whether they will have meaningful values. The following are the first three
attributes:
• latitude
• longitude
• accuracy
These attributes are guaranteed to have values and are fairly self-explanatory. latitude and
longitude will contain the HTML5 Geolocation service’s best determined value of the user’s location
specified in decimal degrees. accuracy will contain a value in meters which specifies how close the
latitude and longitude values are to the actual location, with a 95% confidence level. Due to the nature of
HTML5 Geolocation implementations, approximation will be common and coarse. Make sure to check
the accuracy of the returned values before you present them with any certainty. Recommending a user
to visit a “nearby” shoe store that is actually hours away could have unintended consequences.
97