Tidying my map embedding examples

Posted by Harry Wood on 19 February 2013 in English (English)

First of all... It's the London OpenStreetMap pub meet-up TONIGHT. Come join us!

I've been working a bit more on the map embedding examples I have on my website. For a long time that URL would take you to an apache directory listing of a bunch of files, including various junk experiments. But I kept linking people to it in discussions, and it was getting a bit embarrassing. Time to tidy it up a bit.

At the hack weekend I set-up a php script which allowed me to leave these files (mostly HTML files) arranged in directories, but launch a view of them which presented the examples with nice editor/preview panels (This is done with a neat javascript tool called codemirror)


More recently I've set this up to use URL rewriting, give nice ".view.html" URLs and simultaneously fix problems with relative file references. I've also set it up to pull out some explanatory text from the HTML file. I know there's a tonne of other approaches to this using jsfiddle, github gists or others, but I'm quite pleased with the result for my own website.

The examples themselves... need some work still. Some excuses/caveats:

  • They started life as bunch of little junk files/experiments, and they kind of still are.
  • They're generally intended to be very minimal, illustrating one particular trick while not doing other things (even things that arguably you should always do) although I haven't been consistent with this.
  • Some of them are examples lifted directly from tutorials or example resources on other websites e.g. the OSM wiki, and I've deliberately not changed anything (even where I'd like to) so we can cross-link for consistency.
  • Some of them are based off examples I'd found / developed a couple of years back. I've noticed javascript coding style has since changed particularly in the examples given on
  • Should web developers download a javascript mapping library before using it, or point at a hosted option? It's a pretty key question when presenting basic examples, but I haven't been consistent about this. What's the answer? Well some smart technical people will say it's a silly question. Of course it's better to download. I could write a whole blog post on this topic, but let me just say for now, anyone who thinks that it's obvious, might be failing to empathise with the target audience. There are actually several considerations to balance.
  • Giving credit to OpenStreetMap is another area I may not have been entirely consistent with. In general I would say that examples like this should really follow the [instructions on the copyrights page](a href=" to the letter. In many examples I'm doing the minimal thing, and sticking with defaults. In particular note that the OpenLayers developers have not rolled out the default OSM credit text change to the hosted OpenLayers yet. Not sure when that's on the roadmap for. I don't think we need stress about it. The other thing is, I have been meaning to put together a set of examples/code/graphics for giving really awesome credit to OpenStreetMap. Alex Barth beat me to this idea recently. Basically the same idea, though I was imagining it slightly differently.

All said and done, there's a fair amount of wrongness in my examples, and I guess you can contact me if you'd like to suggest fixes. They're far from perfect, but taking on board everyone's feedback might count against simplicity. And besides we have the wiki for that. It's quite interesting to look at what's happened to the 'OpenLayers Simple Example' wiki page which I created way back in September 2007. At the time I predicted problems, and I wrote a section at the bottom begging people not add stuff to it which makes it more complicated. Since then various people have done just that, but there have been a few nice simplification edits too. I think a bold edit or two would whip it into shape, but maybe only in line with the way I see it, and only until somebody else edits it because they see it differently. Providing simple examples is not an exact science.


Discuss at the pub TONIGHT!? We're at the Blue Posts near Tottenham Court Road station from 7pm onwards (possibly hidden upstairs!)

Login to leave a comment