I’ve split the presentation I gave up into three separate blog posts, which I’ll be putting up over the next few days. This one will cover basic use of the navigator.geolocation API, with the next two showing you how to use the data that gives you to find out where the user actually is, and to plot that data using Google’s static maps API.

To start, I should explain that Beer Near Me was only ever intended to be used as a platform to be used to help me learn about the navigator.geolocation API and how it works. All the data that gets shown by the site was initially kind of secondary to me, as was the map that I use to show it off.

Of course, navigator.geolocation turned out to be far easier to work with than I expected.

Support for navigator.geolocation

The first thing to be aware of is that right now, support for navigator.geolocation is pretty poor. If you’re using Firefox 3.5+ or Mobile Safari you can use it out of the box, and you can turn on geolocation support in Chrome, but apart from that you’re plain out of luck. Since the idea behind Beer Near Me was to learn about navigator.geolocation that means that right now I’m not supporting any other APIs.

It’s not all doom and gloom though. There are implementations of the API available for use in other browsers as plugins – for example Geode will get you support in earlier versions of Firefox 3, and Google Gears opens up the ability to play with geolocation in some other browsers. There’s also Loki (a Skyhook based plugin) that will get you support over a whole bunch of browsers but uses a differently specified API. Of course, I’ve not actually used any of these, so your guess is as good as mine as to whether they are any good or not. I seem to remember Loki looking interesting a couple of years ago.

Finding a location

So, how to actually use navigator.geolocation? Well, a good place to start would be checking whether the browser supports it. We’ll do this in JavaScript, since that’s the only place we can reliably perform the check.

if (navigator.geolocation) {
    // do geolocation
} else {
    // say sorry to the user
}

Pretty simple. It’s your standard JavaScript functionality check. If we have the functionality available then we can actually do something with it.

navigator.geolocation.getCurrentPosition(
    foundLocation, // a user generated function
    noLocation,    // yup, user generated too
    {
        enableHighAccuracy: true,
        maximumAge: 1800,
        timeout: 30
    }
);

Here, we’re calling getCurrentLocation() with two callback functions and some options. Once the browser (and the user) has decided whether or not to return a location, either the foundLocation or noLocation functions that you get to write are called, and the user’s location is passed into them.

Before we get to those callback functions though, lets talk for a minute about the options we’re passing into getCurrentPosition(). Essentially, what we’re saying in the code above is:

Try to give me highly accurate positioning if possible. I’d like to actually know where I am.

Oh, and if you have a position cached that’s no older than 30 minutes, could you give me that immediately please? I know that kind of contradicts what I said a moment ago, but I know better than you.

And one more thing – if it takes you longer than 30 seconds to work out where you are, just give up. There’s a good fellow.

And that’s it really, with that little bit of code we’ve set up the browser to do some magic and try and work out where it is.

Watching for changes to the user’s location

The only problem with this is that the iPhone in particular seems a bit rubbish at following these instructions. The first result it sends back seems to be uniformly Not Good, and generally quite old. So what can we do about that? Thankfully, there’s an easy answer provided to us in the API – the watchPosition() function. This uses exactly the same parameters as getCurrentLocation() and can simply be dropped in as a replacement for it.

watchPosition does what you’d expect it to do. Instead of finding a location once, it will keep watching the user’s location and call the success function whenever the location changes. The thing that watchPosition() is most useful for though, is getting more accurate locations as the user’s device tries different location finding techniques.

You see, different devices will try and locate themselves in different ways. Some of the techniques they’ll use will be be quick, some slow, and some very expensive when it comes to battery life. For example, here’s what the iPhone does, as I understand it:

1. First, the iPhone will look to see if there’s a location cached in its memory and give you that if available.

2. If you’re still watching for new locations, it will then try and grab a general location from the cell towers it knows about.

   Depending on the number of towers available, this might give you really good, or really bad accuracy. For example, in Bedford (where I live), using cell tower triangulation I get an accuracy which basically covers the entire town. Not particularly useful. It is quick though, and doesn’t really cost much in terms of power.

3. If the cell tower triangulation wasn’t awesome then the iPhone will gather information about all the WIFI hotspots it can see.

   This data gets sent to Skyhook, which does a whole bunch of triangulation and sends back a result. This is obviously slower than just hitting the cell towers, but it can give you a really accurate result depending on where you are (better than GPS in some built up areas).

4. Finally, if you’re still looking for a location, the iPhone will fire up the GPS.

   This is expensive, slow, and drains the battery, so is left as a last resort. It generally gives the best quality results though.

So, you see, things aren’t necessarily as simple as asking for a position. A whole bunch of stuff can be going on in the background, and grabbing the best location the user’s device knows about as time goes on can be very useful.

Using the location we’ve found

So, now that we’re requesting a location, what do we do once we actually get one? Lets have a look.

foundLocation = function(position) {
    // position.coords.latitude
    // position.coords.longitude
    // position.coords.accuracy
    // and more…
}

As you can see, the function we call on location finding success gets passed a single parameter – position. This object contains a coords object, and a timestamp representing the time the location was determined. It’s the coords object we’re interested in right now, since that contains the latitude, longitude and accuracy (measured in metres) of the user’s current location – all the information a grown chap could need for finding some beer. Other applications might make use of the altitude, heading and speed information, but that’s not vital when looking for beer, so I’m ignoring it for now.

Putting it all together

Quickly putting all this together, here’s some JavaScript you can copy and paste into a page to see this all in action.

/*global document, navigator */
var beerLocation = {
    foundLocation: function (position) {
        beerLocation.setPara(
            "Lat = " + position.coords.latitude + 
            ", lon = " + position.coords.longitude + 
            ", accuracy = " + position.coords.accuracy + "m");
    },

    noLocation: function () {
        beerLocation.setPara("Boo! You didn't share your location!");
    },

    noGeoLocation: function () {
        beerLocation.setPara(
            "Sorry, but your browser doesn't support geolocation.");
    },

    setPara: function (text) {
        var p = document.getElementById('location-info');
        if (!p) {
            p = document.createElement('p');
            p.id = 'location-info';
            document.body.appendChild(p);
        }

        p.innerHTML = text;
    }
};

if (navigator.geolocation) {
    navigator.geolocation.watchPosition(
        beerLocation.foundLocation, 
        beerLocation.noLocation,
        {
            enableHighAccuracy: true,
            maximumAge: 120000
        }
    );
} else {
    beerLocation.noGeoLocation();
}

Alternatively, take a look at it in situ and in action on my geolocation test page. The location shown by this page will keep updating as you move around or your device’s accuracy improves. For best results, try it out on an iPhone.

And finally

And that’s how easy it is to find a user’s location and keep updating it. You just need to do something with the latitude and longitude once you’ve found it.

In Beer Near Me I do two things with the location once it’s been found – I tell the user the street address of the location, and I display it on a map. And, of course, I’ll be writing about how I’m doing that in the next couple of posts.

So, I went back to scratch and tried installing it on a web-server. Since my normal stack is Apache, MySQL and PHP I didn’t have any of the Java-based web-servers suggested by the W3C. My first attempt at getting the validator working was to use Jigsaw – the same web-server as the W3C uses to run their version on. Unfortunately, it didn’t work for me. Bugger.

So, I tried Tomcat. After following Basil Bourque’s instructions on Apache’s Tomcat wiki pages, I got Tomcat working. I then followed the rest of the CSS Validator installation instructions for Tomcat, and the validator worked in my browser. Excellent.

There was a fly in the ointment though. Whilst the validator worked in my browser, the same could not be said of my attempts to get it working via cURL calls from PHP using POST data. I was using the same code as I’d used to validate against the W3C’s HTML validator, so I knew that I was able to successfully push POST data across to servers. If I tried using GET requests to send the data to my local validator, then that worked. I verified the same thing was happening on the live CSS validator to make sure the problem wasn’t with my installation. I know you’re thinking “well, if GET worked, why not just make requests that way?” Unfortunately, I know that later I’ll be asking to validate much larger CSS rulesets — ones that will be far too large to fit on a URL. So, I needed to use POST.

After a fair bit of poking, I realised that the in-browser version of the CSS Validator was setting an enc attribute value of multipart/form-data on the form when it was uploading files or sending textual data. Conversely, it turns out that PHP was sending application/x-www-form-urlencoded as the encoding type instead, and the W3C CSS Validator just isn’t set up to accept that. After a long time of trying to work out how to send things in multipart/form-data format using PHP’s cURL functions, I happened upon a comment on PHP’s curl_setopt function which told me that if I gave PHP an array instead of a string it would automagically start using multipart/form-data. As if by magic, my problem was solved.

My problems setting up my programmatic connection to the CSS Validator could easily have been solved by clearer documentation. Nowhere that I could find in the Validator’s documentation was there any mention of needing to make POST requests using multipart/form-data. If this had been stated somewhere I would at least I have known the path I needed to be looking down. Likewise, lack of anything other than user-generated documentation for the PHP CURLOPT_POSTFIELDS cURL option made life far more difficult than it should have been.

Still, in the end I have a local version of the W3C’s CSS validator running on my laptop, and I’m able to connect to it programmatically to run tests. Which is nice.

I’m currently working on the CSS portion of the First Phase, so I’ve been looking at getting the W3C CSS Validator running locally on my machine. Since there was a tiny bit more to it than there seemed from the W3C’s setup instructions, I thought I’d better write down how I did it.

1. Download the Jigsaw web server and unzip it to a location of your choice. We’ll be needing the servlet.jar file from it later (it’s in Jigsaw 2/classes/servlet.jar)

2. Open a terminal window, and change directory to somewhere you’re happy to put the CSS Validator. The CVS password, when prompted, is “anonymous”.

   CVSROOT=:pserver:anonymous@dev.w3.org:/sources/public cvs login
   CVSROOT=:pserver:anonymous@dev.w3.org:/sources/public cvs checkout \
   2002/css-validator
   cd 2002/css-validator
   mkdir lib
   cp {your servelet.jar location} lib
   ant jar
   

3. Assuming nothing goes wrong, you’ve got yourself a self-contained, offline CSS Validator. Awesome.

4. Test the validator by running the following:

   java -jar css-validator.jar --output=soap12 http://www.w3.org/
   

5. By running the following, you can see the options available to you from the validator:

   java -jar css-validator.jar
   

   These options are explained in the CSS Validator User Manual.

And that, as they say, is all there is to it. From this, it shouldn’t be too difficult to set the validator up to run as a website if you want to, but that wasn’t necessary for me right now, so I didn’t do it myself.