So, since PHP Code Sniffer can also run JSLint, we thought we’d turn on JavaScript sniffing as well. It all sounds so easy, doesn’t it?

Ultimately, it is pretty easy to get PHP Code Sniffer running JSLint, but there were a whole bunch of hurdles that ended up taking me a couple of days to get over. So, I thought a blog post was in order. Here’s what you need to do:

1. Have a working installation of Java.

2. Have a working copy of PHP Code Sniffer, installed via PEAR.

3. Have a working installation of Rhino.

   Depending on your system you’ll want to do one of two things:

   • The simplest option is to install a Rhino binary, by doing something like the following on your system:

     apt-get install rhino
     

     This will put a rhino script on your executable path, and you’re good to go.

   • Alternatively, you’ll need to download Rhino from Mozilla’s website. Unfortunately, this download doesn’t contain a rhino passthrough script (which PHP Code Sniffer will later need), so we’ll need to create one. Thankfully it’s pretty simple, and can look like this:

     #!/bin/sh
     java -jar `dirname $0`/js.jar $@
     

     Here, we’ve made the assumption that we’ve put the rhino shell script and the js.jar file (the only file we need from the download) into the same directory.

4. Create a JSLint file that Rhino can use.

   For this, you’ll need to travel back in time to before Crockford stopped supporting Rhino.

   1. Download the last version of the rhino.js file from GitHub.

   2. Download the latest version of fulljslint.js from Github.

   3. Concatenate the two files together.

      cat fulljslint.js rhino.js > ultimatejslint.js
      

5. Tell PHP Code Sniffer where your rhino and ultimatejslint.js files are:

   phpcs --config-set rhino_path /path/to/rhino
   phpcs --config-set jslint_path /path/to/jslint.js
   

6. Run PHP Code Sniffer with a standard that knows about JSLint.

   • Either use the Squiz standard:

     phpcs --Standard=Squiz .
     

   • Or, add the Squiz JSLint Sniff to your own standard.

     In your standard’s getIncludedSniffs() function, add the following Sniff to the returned array:

     'Squiz/Sniffs/Debug/JSLint.php'
     

And that’s it. There’s a few steps, but once you’ve done them once, JSLint issues will show up as warning in your reporting. If you want to change the flags that JSLint has turned on, you’ll need to update the array at the start of the rhino.js file.

One of the processes that I introduced to the team about six months ago was that of a formal “dev check” after every task that we completed from our backlog. Whilst we call this process a dev check within our team, it could just as easily be called a peer review, or mini code review.

Up until the point that I introduced the dev check it had not been uncommon for a single person to work on a task, and for code to go through the testing environments and onto live without a single other human ever reading their code. Not the best situation to be in, and it meant that we ended up having more annoying bugs showing up on our test environments than we should have. These bugs were often things that a simple bit of human scrutiny would have caught, and we ended up wasting time going back and fixing them after the fact. Working this way also meant that we ended up with certain areas of the homepage that could only ever be worked on by certain people, because they were the only ones who had ever seen the code.

Like I said; not the best situation to be in.

So, six months ago, we introduced the formal dev check – a step to be completed for every single code related task in our backlog. And, I’m happy to say it’s been a very successful process for us – we now have far fewer bugs getting to test, and we have a lot more shared knowledge within the team.

What is a Dev Check?

Before any task is committed to trunk, a developer who didn’t work on it must say that they are happy with how it’s been completed.

I’m hoping that if you’re still reading at this point that you’re wanting to find out what goes into a successful dev check…

1. The task is “completed” by Rachel.

   At this point she has not committed anything to the trunk of the project. Depending on the size of the task, she might have created a development branch which she’ll have been committing to.

2. Rachel asks another member of the development team to come and do a dev check. On this occasion she asks Jon.

3. Jon comes over to Rachel’s desk where she will talk through all the changes she has made.

   As part of the discussion, Rachel may realise that some of the things she thought made sense in fact didn’t. This is great, and she’ll make the changes necessary and continue with the dev check.

4. After Rachel has finished explaining what she’s done for the task, and Jon’s asked as many questions as he feels is necessary he’ll either give the go ahead to commit the code to the trunk, or he’ll request various changes to be made to the codebase.

5. Rachel will then commit to trunk, build in the team’s test environment and pass off to the testers.

And that’s a dev check.

Out of this process Jon has learnt about a bit of the codebase that he might not otherwise have seen, Jo realised that she needed to shore up a couple of her tests, and the codebase has come out feeling more healthy. This is A Good Thing™.

What sort of things will the dev checker ask?

Up above there in the “What is a Dev Check” section you’ll have read about Jon asking “as many questions as he feels is necessary”, and I’m sure you’ll have said to yourself “But Neil, what are those questions? How will I know what’s sensible to ask?”.

Well, you’re in luck. By a process of trial and error, as a team we’ve come up with a bunch of questions that, if asked, will help to make sure that you both understand what’s going on and can confirm that the code written is of a high quality.

• Have new tests been written?

  These might be Unit Tests, or Automated Front-End Tests, or Security Tests. What matters is that valid tests have been written to cover the new functionality. You should also make sure that any pre-existing tests make sense.

• Do all the tests still pass?

  It should be a no-brainer, but of course you should make sure that all the tests still pass. There’s nothing worse that breaking The Build for the entire team just because you forgot to run a bunch of tests on your development machine first.

• Are standards adhered to?

  • PHP Code Sniffer
  • HTML/CSS Validation
  • JSLint
  • Whatever else works in your team

  These are important to us. We fail our builds if our code isn’t of high enough quality. Just sayin’.

• Does what you’ve written work across all the Level One browsers?

  Obviously this one’s a bit web development specific as it is, but it’s important in other spheres as well. Every piece of software that’s written is expected to run in one or more environments, and you should at least smoke test in a known subset of them to make sure there are no nasty surprises for your dedicated testing team.

• Can I see your diffs?

  Again, fairly obvious, but you should take a look to see what’s changed since the last time the code was checked in. Don’t just rely on the developer to remember what they’ve changed – I know I can’t remember half the time. This is what machines are good at – make use of them!

• Did any of the changes that were made affect any other code?

  This one should be obvious as well, but unfortunately it isn’t. It’s all too easy to look at the lines of code that have changed without looking at the later lines which make use of them. Don’t forget to look at the whole system.

• Is there anything that concerns you?

  The final question to ask, and in many cases the most important one. Oftentimes a developer will know that something smells a bit fishy, but keeps quiet about it in the hope that they won’t get called on it. By simply asking these questions though, we’ve found that these things end up getting talked about, and we end up with better code because of it.

How long does a dev check take?

After reading all that, I wouldn’t be surprised if you’re thinking “Woah! But how long does that all take? That seems like a long list of questions…”.

Well, in my team, we find that a dev check will take a little less than 10% of the time that the code and tests took to write initially. So, if the task took an hour to complete, the dev check would take roughly 5 minutes. A three hour task would take 15 minutes, and so on. It honestly doesn’t take much time once you get into the swing of things.

The Power of Veto

One of the most important things about dev checks is that everyone on the team is equal. Rachel may be the team leader, but Jon can still challenge her code and say that actually she hasn’t done everything required to “pass” the dev check.

The person performing a dev check always has power of veto to say that things, however small, need improving before code is allowed to be committed to the trunk.

Ultimately, the team is responsible for its own output, and everyone should be invested in that.

What do dev checks achieve?

As I’ve mentioned above, there are two main benefits to dev checking:

• Fewer bugs
• More knowledge of the codebase by more of the team.

Essentially the team will be more effective.

How do you get buy in?

Whilst there are obvious benefits to dev checks, sometimes you’ll need to gain buy-in from people before you can get started. Maybe it’ll be team members who think that this extra process is unnecessary, or maybe it’ll be The Boss who thinks that it’ll all just take far too long. What do you say to them?

Getting Buy In From Team Members?

• Everyone is equal.
• Anyone is able to say that a dev check cannot yet be completed.
• The team is responsible for the quality of the team’s output, not just one person.
• You won’t end up getting stuck on a horrible portion of the codebase any more, just because you were the last person to write code for it.

Getting Buy In From The Boss?

If you’re lucky, you won’t need to get buy-in from The Boss, but in case you do, here are a couple of pointers:

• Quality is improved, leading to fewer bugs and happier users.
• The amount of time spent on dev checking is smaller than than that which would be spent fixing the bugs that would otherwise get through. The project will go live sooner, and you’ll have spent less money.

Improving the Dev Check

Any bug that is found is an opportunity to learn and improve our process.

Of course, sometimes bugs will still get through. When they do, you need to sit down and work out why that happened.

In the old world, we used to just accept that bugs happened, that they’d get found, and we would fix them. No more! Now, any bug that is found is an opportunity to learn and improve our process.

A real example of this happening came a few weeks ago. Tina had been doing her thing, updating a script that we use to help us with our release management. This was dev checked by Bradley, and as far as he was concerned the changes that had been made were good to go. So, he ticked off the dev check, and Tina carried on with her next task.

Fast forward to a week later, and Paul was getting down on the floor ready to give a presentation which required a screenshot of the script running. Unfortunately, it no longer worked – shock horror!

What had happened was that Bradley hadn’t realised that the line of code that was changed had impacted on further lines in the script. Moreover, he’d only seen the script run against the additional new requirements, and hadn’t confirmed that it still ran against the original requirements. Whoops.

What came out of this was an improvement to our dev checks – if code has changed we need to make sure that nothing else in our code has been affected by that change. It sounds simple, but it was a failing that we had, so we improved upon it.

Why not just have a big code review?

Big code reviews are great, and are something I very much enjoyed participating in when I was at Yahoo!. Unfortunately, whilst they’re very useful they’re also pretty time consuming, and require a fair amount of setup and teardown time in order to be useful.

Dev checks, on the other hand, are simple to get going with, only take a few minutes, and only have to involve a couple of people.

That’s not to say that you should get rid of larger code reviews. In my opinion they should still happen, but only for larger chunks of code. The formal dev check gives you the opportunity to review code and share knowledge often and with low cost.

Go forth and Dev Check!

And that’s it. If you’re working in a team that has bugs, or has bottlenecks of a single person being the only person who knows about certain areas of your product, then start dev checking. You won’t regret it.

Up until now I’ve used a collection of Smart Playlists which take into account my ratings, when I last listened to songs and a whole bunch of other information. At the last count, I had over 70 Smart Playlists feeding into each other to generate the playlists which finally get Synced over to my iPhone.

But there was something missing. Whilst I could generate playlists based on the mid-90s simplicity of the “Genre” tag, that tag is by design only able to identify one piece of information. So I wouldn’t be able to find, for example, all tracks in my collection that are “rock”, “funny” and performed by a “female”. And even if I could, I wouldn’t want to go and tag 40,000 tracks by hand. That way madness lies.

It turns out there’s a fairly simple solution to this – last.fm allows users to tag any and all tracks it knows about, and it keeps track of how many times each track has been tagged with each tag. So, it’s entirely possible to grab the top 15 tags for each track in my collection, add that data to my tracks somehow, and then query that.

The somehow turns out to be pretty simple too – the ID3 “comment” field is there for the taking, and by design is expected to be larger than any other field. Excellent. So that’s the “where to store” sorted, now how about “how to store so that the data is queryable”?

For this I took a trick out of Brian Suda’s book. A couple of years back I took a look at how he’d written his microformats parser using XSLT to be able to check for classes an element may or may not have – the trick being to wrap strings of classes with a space at the beginning and end so that every class always had spaces surrounding it. I used the same trick for storing my tag data, also wrapping it in a ‘lfm’ square bracketed enclosure to separate it from any other data in the comment.

So, the data I saved in the comment looked a little something like this:

[lfm: tag1 tag2 tag23 tag3 ]

You’re probably starting to see why wrapping in spaces is important now. Because iTunes’ Smart Playlist system can only perform simple string matching (Apple doesn’t seem to like regexes – AppleScript can’t do them natively either), you need some way of targetting the beginning and end of tags. Without those spaces, a query of “Comments contains 'tag2'” would return you both tag2 and tag23, which no-one wants. By requesting “Comments contains ' tag2 '” instead (note the extra spaces) you end up just being given tag2.

All this thinking is packaged up into a couple of scripts (though obviously take the latest code if you want to actually use it yourself) I wrote a couple of days ago that takes a given playlist from your iTunes library, asks last.fm for tags for each of the songs in that playlist, and then adds that data to the library using AppleScript.

Problems?

There are, unfortunately, a couple of issues with the script at the moment. First off, because last.fm allows anything and everything to be given as a tag, they can contain characters that need to be normalised out. Right now I’m doing that very simply (spaces to dashes mostly), but I should revisit the code and harden that normalisation – I’ve seen tagging bail out a couple of times because of unexpected data.

Next up, the fact that last.fm allows tags to be incredibly long coupled with the fact that under ID3 v2.x the comments field can only be 256 characters long means that it’s possible to run into issues with tagsets being too long to fit into the comments field. Add that to the fact that some songs in my collection legitimately contain comments already and that I want to add tags non-destructively, and we’re ending up with not much space for tags. So, an improvement that I’m planning on making to the script is to make sure that tags try to take up no more than the space that’s legitimately available to them.

The final issue that I’ve been having lives with last.fm’s track.getTopTags API method. Unfortunately at present the track.getTopTags API method does not perform any auto-correction of track names, which means that if you try to get the tags for something that does get auto-corrected by the system then you end up with the tags for the uncorrected track name. A subtle distinction, but it probably means that we end up with unmaintained tags that haven’t been touched for the year or so since auto-correction was turned on. A possible solution here if last.fm choose not to “fix” this behaviour (it could be argued that this is correct behaviour) would be to make a request out to Musicbrainz to get an ID for the track and then pass that into track.getTopTags instead. But that seems like a whole bunch of extra work for a not massive gain.

The final Smart Playlist

So, what about that Smart Playlist? After all, that’s the thing that all this work was done for.

In iTunes, select File, New Smart Playlist, and then enter the following:

Match all of the following rules:
    Comments contains ' female '
    Comments contains ' rock ' ...
    any of the following rules:
        Comments contains ' comedy '
        Comments contains ' funny '

This cunning playlist uses a Smart Playlist feature I wasn’t aware of until yesterday – rule groups. Up until now, I’d been pulling in other Smart Playlists as sources to perform the same job.

To create a new rule group in a Smart Playlist, simply click an ellipsis button in the Smart Playlist interface, rather than clicking on the plus button.

Essentially what these rule groups give you is the ability to nest rulesets, and generate very complex playlists that don’t have half their rules hidden in external playlists. In the playlist above we’re simply asking for all tracks tagged with “female”, “rock” and either “funny” or “comedy”. So essentially “female comedy rock”. At present this playlist returns me no items from my collection, but not everything’s been tagged yet. I’m hopeful.

If you’re anything like me, as soon as you connect your laptop to an external display you’ll end up moving your applications around into a better position and size so that you can work happily. Then, when you disconnect your external display to go back onto the road OSX will do its best to put them somewhere sensible on your smaller laptop screen, but fails horribly.

Enter Cordless Dog’s “Stay” application.

Stay is a deceptively simple (at least the way I’m using it) application that lives in your Mac’s taskbar. First, set up your applications so that they’re positioned as you want them, then choose “Store Windows for all Applications” from the app’s dropdown menu. If you then want to restore applications to their stored position just pull down the menu again and choose “Restore Windows”. Simple.

To make things even more simple though, pop open the application preferences. There aren’t many options here (and there don’t need to be), but for my money it makes sense to turn on “Start Stay at login”, “Restore Windows as displays are connected and disconnected” and “Restore Windows as applications are launched”. And suddenly, as if by magic, application positioning with multiple displays starts working in the way it always should have done.

Cordless Dog’s “Stay” application costs a measly $15, and is worth every cent. Good job, Cordless Dog chaps!

UPDATE

As David Thompson pointed out, I should probably point out that currently Stay and Spaces don’t currently live marvellously happily together. If you’re a user of Spaces (I’m not), you should probably wait for a future release of Stay.

As time went on, I started paying attention to the “Most Popular” feeds on the homepage, and even managed to get on there myself a few times. It was a good way to find interesting techy links. Then, when the friends network facility was introduced I started following the links that my friends were saving as well. All was well.

However, I never really saved as many of the links that I found interesting as I could have done. There were plenty of occasions when I remembered telling people about particular pages because they were useful, but not being able to find them again myself. Oh, how I wished I’d added them to del.icio.us.

The problem is that I’m lazy. So, I was really happy when Packratius peeked its nose up to the cage bars. The idea behind Packratius is that it’ll keep an eye on your twitter activity and automagically add any links you tweet to del.icio.us (by default with a via:packrati.us tag). It’s deceptively simple, and something that deeply interested me – I immediately signed up.

A good idea gone overwhelming

As it turns out, so did quite a few of my friends. Overnight, my del.icio.us network feed went from being a carefully curated list of links to a mishmash of Carrots Glazed with Cum, gowalla updates and twitpics.

Now, to its credit, Packratius has options to allow you to not auto-delish links tweeted by any twitter clients that you define. This allows you to not auto tweet twitpics and the like. Of course, telling it to stop tweeting those things from your own twitter account is great, but it doesn’t stop you from seeing those updates from other people (/me looks pointedly at Simon Jobling). So, I needed to find a way to split these auto-delished URLs off from the main list.

As it turns out, whilst del.icio.us’ searching abilities are pretty powerful, you can’t do a simply negative search. So whilst you could say “Show me everything in my network feed tagged with ‘kittens’ but not ‘via:packrati.us’” you can’t say “Show me everything in my network feed not tagged with ‘via:packrati.us’”. Thankfully I came up with a solution to this – I created a Yahoo! Pipe called “del.icio.us network feed minus packratius“. (Catchy, huh?)

It’s a fairly simple pipe, with the following aims:

• Provide a feed of your del.icio.us network with items tagged with via:packrati.us removed.
• Easily customisable to show different peoples’ network feeds.

If you’ve been having similar problems with Packratius overwhelming your del.icio.us network feed, then give it a go. I know James Broad has been finding Packratius overwhelming – it was his tweet that inspired me to finally write this post up, in the hope of benefitting a few more people.

How does the pipe work?

Like I said, the pipe’s fairly simple – most of the complexity comes from generating the URL to load a given user’s del.icio.us network feed.

Once we’ve obtained the network feed, the only thing we need to do is discard all the feed items that contain via:packrati.us as a tag. Handily, del.icio.us provides us this information in its feeds:

<item>
  …
  <link>

http://wwp.greenwichmeantime.com/time-zone/africa/south-africa/

  </link>
  <description>
    South Africa is in Southern Africa, 
    at the southern tip of the continent of Africa.
    http:// bit.ly/am78yK
    #statingthebleedingobvious
  </description>
  <category domain="http://delicious.com/simey_j/">
    statingthebleedingobvious
  </category>
  <category domain="http://delicious.com/simey_j/">
    via:packrati.us
  </category>
</item>

In the feed item above (cut down for space), we can see that as well as via:packrati.us, a statingthebleedingobvious tag has been automatically generated from the hashtag in the original tweet. This is a great feature of Packratius, but it did mean that I ended up having to do more than a very simple filter to filter out the via:packrati.us tagged feed items.

Instead what I did was create a Filter block in pipes with rules that looked at the first 6 tags on each feed item (the idea being that there isn’t enough space in a tweet for more than 6 or so tags). If any of them matched via:packrati.us then they’re discarded from the feed.

The filter I created looked something a little like this:

Filter

Block items that match any of the following:

• item.category.0.content is via:packrati.us
• item.category.1.content is via:packrati.us
• item.category.2.content is via:packrati.us
• item.category.3.content is via:packrati.us
• item.category.4.content is via:packrati.us
• item.category.5.content is via:packrati.us
• item.category.content is via:packrati.us

Those first six filter rules cover the instance of more than one tag being applied to the item, and the final filter covers the intances where only a single tag exists. Simple.

And that’s all there is to it. Of course, writing this Pipe wouldn’t be necessary if del.icio.us allowed us to do a simple negative search. Still, it’s good that it’s nice and easy to generate this new feed using Pipes.

Hopefully it’ll be useful to a couple of you.

Even though Beer Near Me was only ever really built as a weekend project intended to help me learn about using the navigator.geolocation API, it was still pretty important to get some data to display on a map showing where the local beer was. After all, without that what would the point be?

Gathering the Data

To gather the local beer data I make several searches using the Google Local Search API – one that covers pubs, one for cocktail bars, one for off-licences, and so on. The searches I make to Google’s local search look something a little like this:

http://ajax.googleapis.com/ajax/services/search/local
    ?v=1.0
    sll={$sll}
    radius=1
    q={$thing}%20loc:{$sll}
    key={$apiKey}

Lets walk through those query string parameters…

• sll doesn’t actually stand for anything according to the docs, but denotes the centre point of of the search you’d like to perform. It’s a comma separated latitude/longitude value, so you’d use something like 52.2282962,0.1537945 for this parameter.

• radius is the radius around the centre point that you’d like to search within, in miles.

• q is the most important parameter by far though; being the query term for the thing you’re wanting to search for.

  You’ll notice that I’ve added a loc: onto the query. It turns out that without this undocumented extra bit of data, Google really doesn’t return much from its local searches. Before last week’s post I wasn’t using this extra qualifier, and whilst my searches were being centered around the expected point they weren’t returning much data.

  A case in point was around The Bricklayers Arms. Without the loc: qualifier The Bricklayers Arms was nowhere to be found. With the qualifier it suddenly started being returned by the searches to Google, along with a whole bunch of other local pubs.

Interpreting the Data

So, if that’s the search we make, what does the data we get back look like?

{
    "responseData": {
        "results": [
            {
                "GsearchResultClass":"GlocalSearch",
                "lat":"59.334743",
                "lng":"18.063034",
                "accuracy":"8",
                "title":"\u003cb\u003ePub\u003c/b\u003e",
                "titleNoFormatting":"Pub",
                "streetAddress":"Hötorget 13",
                "city":"Stockholm",
                "country":"Sweden",
                …
                "phoneNumbers":[
                    {"type":"","number":"08-782 19 30"},
                    {"type":"","number":"08-789 19 30"}
                ],
                "addressLines":[
                    "Hötorget 13",
                    "111 57 Stockholm, Sweden"
                ]
            },
            {
                // another result
            }
        ]
    }, 
    "responseDetails": null, 
    "responseStatus": 200
}

(The data above is, by necessity, just a snippet of what’s actually returned.)

You’ll notice first of all that each result we get has a GsearchResultClass of GlocalSearch set. This allows easy checking of the data type returned. For our searches, the result class will always be GlocalSearch, but other searches would return values for web searches, images searches and more.

Moving on to the data that actually interests us, each item has the expected lat and lng attributes, along with other useful smidgens of data such as title, streetAddress etc.

Of particular note are the title and titleNoFormatting attributes. You’ll notice that within the title field the word “pub” is encapsulated in encoded bold tags. Two things to note here; first, “pub” was the thing we searched for, so this gets emboldened in the standard display that Google would like to use for results (but we’re still provided titleNoFormatting if we’d like to have access to an unformatted string). Second, any formatting applied by google in its API results will be encoded in this way. In Beer Near Me, I take the easy way out for the data I’m needing, and use titleNoFormatting.

Moving away from the data that comes from a single API request, lets take a quick look at what happens once we move into the world of performing lots of searches at once. Since with Beer Near Me I’m making multiple calls to Google to gather beer related locations, there’s the pretty large possibility that more than one of the searches will return the same place within its results. The deduping I do on Beer Near Me is very simple in this case – I simply keep track of the latitudes and longitudes of all the places that have been returned. That way if any locations turn up in a position that’s already had data assigned it it I can ignore it. It’s not perfect, but it does the job well enough.

Caching the Data

The last thing I want to briefly mention that I’m doing with the data is caching it using PHP’s APC.

This was the first time I’d attempted using APC on one of my own projects, so I had to install it on my Ubuntu based dev box. I did that following these instructions.

The reason for using APC to cache the calls to Google’s Local Search is simple – network calls are expensive and slow. With on average five calls to Local Search occurring on each page load on Beer Near Me you’d hope that they wouldn’t be having to go across network every single time. So, I implemented a very simple cache check:

$url = "http://ajax.google…q=somesearch"
$urlHash = md5($url);

// Try and pull the data from cache
$results = apc_fetch($urlHash);

// If we don't find the data in cache we'll have to make
// an expensive call across the network.
if (!$results) {
    // Get the data however you'd normally get it
    …
    $results = curl_exec($ch);

    // now store the data in APC
    apc_store(
        $urlHash, // Key to identify the cache by
        $results, // Data from our curl call to store 
        $ttl      // Seconds - how long we'll cache for
    );
}

As you can see above, I’m only using two APC methods – apc_fetch and apc_store. Really, this is all you generally need for simple caching; one method for getting the data if it already exists, and one for storing it in the cache if you had to get the data from elsewhere.

With that in place, any further requests to that same location will be a lot faster, since we’ll have stored the results locally. Result. For Beer Near Me I can afford to be fairly aggressive with our caching, since for the most parts new pubs and cocktail bars won’t spring up over the course of a few minutes and become immediately available in Google’s search results.

No more locations

And that’s it. As far as I’m concerned, that’s everything I’ve done so far on Beer Near Me. It’s been a fun little weekend project, and whilst there’s more I’d like to do with it at some point, I think I’m going to leave it alone for a few weeks now. After all, Science HackDay is in just over two weeks time, and no doubt I’ll get wonderfully caught up in something new for that. Hopefully whatever I hack on will even be useful.

Now, there are lots of tutorials out there for the JavaScript based Google Maps API. So, if you want to learn how to use the JavaScript based API, then I urge you to pop off and look at one of those. For Beer Near Me, I started off using that API. However, for various reasons (slow to download over the phone network, scrolling issues on the iPhone), I decided to move away from that and towards the Google Static Map API. The big win for me in using the Static Map API is that it means the user only has to download a single image into their browser, and all the hard work of putting the map together is done on the server-side. The negatives are that you don’t get nice clickable areas on the map for free, and you don’t get to scroll around easily.

For me, the positives outweighed the negatives, so I went with the static map.

http://maps.google.com/maps/api/staticmap
    ?sensor=true
    &size=320x300
    &zoom=15
    &maptype=roadmap
    &mobile=true
    &center=lat,lon

As you can see, although there are a whole bunch of parameters needed to put a map together, they are all fairly simply. Lets walk through them one at a time:

• sensor: Required; either true or false. This simply tells google whether or not we used a sensor to generate this maps’s position. For us, this will always be true.
• size: Very simple, just width, an ‘x’, and then height in pixels.
• zoom: How zoomed in you are. 15 gives you a pretty zoomed in map.
• maptype: For us, a roadmap is what we want. You can also choose satellite or terrain, the same as if you were using the Google Maps site.
• mobile: Setting this to true allegedly gives you slightly simplified maps that have a lower weight.
• center: Finally, where the centre of our maps should be. Simple.

Put it all together and you get something a little like this.

Adding some custom markers

But, that’s a bit boring. Normal Google Maps let you add all sorts of custom icons. Well, we can do that too, by adding one or more markers parameters to the image URL. So, to add three icons to a map, two of them the same and the third different, you’d add something like the following to the above URL.

markers=
    icon:http:%3A%2F%2Furl.encoded%2Fimage.png
    |shadow:false
    |52.2282962,0.1537945
    |52.134152,-0.486364
&markers=
    icon:http:%3A%2F%2Furl.encoded%2Fotherimage.gif
    |shadow:false
    |52.135472,-0.491835

And that’s all there is to it. After you whack a load of markers onto the URL you’ll end up with something like the Tottenham Court Road on Beer Near Me, where you can see, amongst all the other drinking establishments, The Bricklayers Arms – the home of Pub Standards (the middle thursday of every month – tell your friends).

Making the map clickable

You might also notice on that page that if you click or tap on any of the icons on the map that you end with a popup telling you about the place. But how is this possible? Aren’t we using Google’s Static map API?

The answer is “yes, we’re still using Google’s Static map API”, but we’re using a little sliver of progressive enhancement to layer data on top of it. If you turn JavaScript and CSS off for a moment, you’ll notice a couple of lists underneath the map image. The first contains links which have targets pointing to the relevant items in the second list. So, with no CSS or JavaScript clicking the links will move you through the page to the data. Useful, but not yet useful enough.

So, what if the user has CSS enabled? What can we do then? Well, what I chose to do on Beer Near me was to position each of those links over the icon they were assigned to. First off, all the icons were the same size, so I created some base CSS that I could hang the final positions off:

#map_canvas {
    position: relative;
}

#map_canvas .marker,
#map_canvas .marker a {
    display: block;
    width: 30px;
    height: 30px;
    overflow: hidden;
    text-indent: -9000em;
    list-style: none;
}

#map_canvas .marker {
    position: absolute;
}

Of course, if we just did that then all the clickable areas on the map would be dumped up in the top right of the map, and no-one would be happy. So, we need to work out where to put those top and left directives.

Warning. Hard-coded Assumptions Incoming

Now, it turns out that if you’re zoomed in to a Google zoom of 15 then each pixel equates to roughly 0.0000266667 units of latitude and 0.0000421875 units of longitude. So, we can use this to work out where we’d like to position our clickable elements.

Lets take an example:

You have created a map that is 320 pixels wide and 300 pixels high, and zoomed to a level of 15. The centre of this map is at 51.510953,-0.133012.

A public drinking establishment (De Hems) exists at 51.512081,-0.131288. Assuming a 30×30 clickable area with its centre at De Hem’s location, what should the top and left co-ordinates of the clickable area be?

On Beer Near Me, I work out the numbers using some code that looks something like the following.

$mapHeightPix = 300;
$latPerPixel  = 0.0000266667;

$centreLat    = 51.510953;
$locationLat  = 51.512081;
$latDiff      = $locationLat - $centreLat;

$topPix = ($mapHeightPix / 2) - (int)($latDiff / $latPerPixel) - 15;

Unsurprisingly, there’s something remarkably similar for longitudes. (If you’re wondering, the answer was top: 93px; left: 185px;).

Now, with that code in place to position the clickable areas on the map users can click and be taken to the relevant item further down the page. On Beer Near Me I then layered on top some JavaScript to do a simple popup (again, look at the Tottenham Court Road page), but I’ll leave that as an exercise for the reader.

And that’s essentially that. What started as a simple weekend project to learn how to use the navigator.geolocation API ballooned slightly to encompass Google’s local search API and static maps APIs, and I ended up with something slightly useful. Maybe in a year or two I’ll have even made it pretty.

After all, having a latitude and longitude is all well and good, but as humans we tend not to think that way. So, it would be quite nice to give the user a street address identifying their location. As it turns out, this is pretty easy – the Google Local Search API has this functionality baked in.

http://ajax.googleapis.com/ajax/services/search/local
    ?v=1.0
    q=lat,lon
    key=yourgoogleapikey

If you add your comma separated latitude and longitude to the structure above, Google will very helpfully return you back a load of data that tells you where it thinks you are:

{
    "responseData": {
        "results": [{
            …
            "title": "Kelly Langley…",
            "streetAddress": "Cowley Road, Cavendish House…",
            "city": "Cambridge",
            …
        }]
    }
}

This is only a chunk of the data that gets returned by Google, but hopefully it should be enough to give you a taste of what’s available. The obvious thing to do at this point is grab the street address, and maybe the city, and output them as a string to show the user. This is what Beer Near Me is currently doing.

One piece of data we haven’t used yet though is the accuracy data that is returned by navigator.geolocation.getCurrentPosition. You’ll remember from the last post that accuracy is measured in metres and shows the confidence that the browser has of the location it’s returned. So, if accuracy is given as 500, then the user might be anywhere within a half kilometre radius of the given location – not particularly accurate, and saying that they were on a specific street would be misleading. If, on the other hand, the accuracy given was 25 then the user would be expected to be within a 25 metre radius of the given location – pretty damn accurate.

So, what can we do with this? Well, if we’re not happy that the accuracy is good enough then we could tell the user they were “Somewhere in city” instead of simply showing them the street name of their location. On Beer Near Me, I could also stop the “Find me some beer” button from working until the accuracy was good enough.

So, that’s how I’m dealing with showing the user where they are in a nice human readable way on Beer Near Me – it’s pretty easy, right? In the next entry I’ll finish off talking about the navigator.geolocation API by putting the user’s location onto a static Google Map.

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.

I’ve only just got round to reading the book, but I’m glad I did. As a learning book it’s deliberately quite lightweight and easy to get through in a short time, in the same way that Steve Krug‘s “Don’t Make Me Think” is designed to be absorbed in a couple of hours on a flight. All told, I spent about three hours with this book, on my tube journeys to and from work this week.

Robin starts her journey by briefly explaining the concepts of Contrast, Repetition, Alignment and Proximity (anyone spot an acronym there?), before moving on to explore each concept in greater detail. As Robin repeatedly tells us in her book, by being able to name the concepts you’re able to identify them and use them deliberately rather than accidentally.

The second half of the book deals with type; the different styles of typefaces, how to combine them and horrible errors of judgement to avoid.

Spread throughout the book are a bunch of mini quizzes and exercises designed to get you thinking about what you’ve just read. The quizzes are a nice touch, and I’m sure I’ve retained more knowledge because of them than I would have done if I’d just read through from cover to cover.

The book covers design in general, rather than being focussed on the web, print or presentations. Whilst Williams has written a book called “The Non-Designer’s Web Book” I specifically chose to buy this one because both I wanted a general overview book and because the web book is from 2005 (a lifetime ago on the web) and has some mixed reviews. “The Non-Designer’s Design Book” did not disappoint – it’s given me that overview that I was looking for, and I now feel a bit more comfortable that my designs will actually work.

“The Non-Designer’s Design Book” costs £23.99 in all good bookshops, or currently £12.30 on Amazon.