Gary Gale

Posts about javascript

Customising WordPress Without Modifying Core, Theme Or Plugin Files

WP Customizer and that's what this plugin is for. When WordPress does support such a way, this plugin will thankfully be obsolete.

A standard WordPress install is incredibly powerful and flexible. For a lot of people, WordPress out of the box plus one of the stock WordPress themes is enough. But the possibilities for customization are endless; you can add plugins and other themes. Sometimes these do just what you want. Sometimes you need to ... tweak WordPress.

A very high proportion of the customization advice you'll find on the web starts with these lines ... add the following to the end of your theme's functions.php or even worse, advises that you modify the source code of your theme or your plugins. This is bad for many reasons:

  • Editing your theme's functions.php makes theme specific customizations; change your theme and your customizations will no longer get loaded.
  • When your theme and plugins get updated you'll find all your careful hand crafted customizations get overwritten and lost.
  • A lot of theme and plugin authors won't offer support for changes you might have made to the source code.
  • Your customizations might work; but you might also inadvertently make some other changes which will stop things working.

WordPress doesn't yet support a way for site specific customizations to be made and loaded without touching theme, plugin or core files; that's why I wrote WP Customizer and that's what this plugin is for. When WordPress does support such a way, this plugin will thankfully be obsolete.

screenshot-1 There's another, not entirely altruistic, reason behind this plugin. One of the most common support requests I get for WP Biographia is to help with clashes between someone's theme's CSS and the plugin's CSS. Once that's been resolved, the next question is almost always how do I load this custom CSS? The answer is now straightforward. Put your CSS file in a directory in the root of your WordPress installation, install WP Customizer, tell it to load custom CSS files and where to find them and you're done. No editing of functions.php. No learning now to hook into the wp_enqueue_scripts action, no learning how to call wp_register_style and wp_enqueue_style. It should all just work.

But WP Customizer works with more than just custom CSS files. You can also load custom PHP functions and custom Javascript and jQuery files as well. What's more, you can configure these to load just for your site's publicly visible front end, just for your site's admin pages or even both.

WP Customizer uses the file system as a data-store metaphor and allows you to main a library of common customisations that are independent of the theme and plugins you're currently using. Out of the box, the plugin looks for custom files to load in the root of your WordPress installation in a set of named directories which should be relatively self explanatory, functions, admin_functions, common_functions and so on for CSS and for scripts.

But you can just as easily create your own directory structure, put together in a way that makes sense to you, perhaps something along the lines of ... site/front-end/css, site/front-end/functions, site/admin/scripts and so on

... you're limited only by the limitations of your file system and the way of organising things that make sense to you.

screenshot-5 One final word of caution though. In order to use this plugin, you have to know how to write the code that lives in the customisation files themselves. That means knowing how to write PHP functions to exercise the WordPress API. How to write JavaScript and jQuery that works with WordPress. How to write CSS. This plugin can't help you with that. But there's ample tutorials and information out there on the interwebs to help you.

Just remember, when you read something that says just add the following code to your theme's functions.php, ignore this little piece of advice and add it a local customisation file and load that through WP Customizer instead. Your WordPress site will thank you for it someday.

To download or install WP Customizer, either search for WP Customizer from the WordPress Dashboard or go to plugin’s page on the official WordPress plugin repository. If you want to fork the source code of the plugin, you can find it on the plugin’s GitHub page at https://github.com/vicchi/wp-customizer.

The Great British Map; Or Great Britain vs. The United Kingdom vs. The British Isles

another map. It tries to answer some of more perplexing and confusing facets of the geography surrounding the world's 9th largest island. I mean of course Great Britain. No, wait. I mean the United Kingdom. No, wait. I mean Britain. Or do I mean England? See, it's confusing.
  • So if the ISO 3166-2 code is GBR, how come the country is called the United Kingdom?
  • But if England is a country and the United Kingdom is a country, how come England is part of the United Kingdom?
  • What about Scotland, Wales and Northern Ireland?

This isn't the first time I've covered this topic. The first time was for a post on the now defunct Yahoo! Geo Technologies blog entitled UK Addressing, The Non Golden Rules Of Geo Or Help! My Country Doesn't Exist. The ygeoblog.com domain is now long gone and redirects to the Yahoo! corporate blog but I was able to reproduce this post here and it's also captured in the Internet Archive's WayBackMachine. The second time was when I made a variation of The Great British Venn Diagram. But this is the first time (though probably not the last) that I've used a map, which is odd as this is something that's tailor-made for a map.

Last night I made another map. It tries to answer some of more perplexing and confusing facets of the geography surrounding the world's 9th largest island. I mean of course Great Britain. No, wait. I mean the United Kingdom. No, wait. I mean Britain. Or do I mean England? See, it's confusing.

  • So if the ISO 3166-2 code is GBR, how come the country is called the United Kingdom?
  • But if England is a country and the United Kingdom is a country, how come England is part of the United Kingdom?
  • What about Scotland, Wales and Northern Ireland?

This isn't the first time I've covered this topic. The first time was for a post on the now defunct Yahoo! Geo Technologies blog entitled UK Addressing, The Non Golden Rules Of Geo Or Help! My Country Doesn't Exist. The ygeoblog.com domain is now long gone and redirects to the Yahoo! corporate blog but I was able to reproduce this post here and it's also captured in the Internet Archive's WayBackMachine. The second time was when I made a variation of The Great British Venn Diagram. But this is the first time (though probably not the last) that I've used a map, which is odd as this is something that's tailor-made for a map.

I'd been looking for a good source of geographic vector data that I could use to easily overlay polygons on a map and came across a rich source of free vector and raster map data from Natural Earth. But instead of overlaying that data on top of a standard slippy map using a JavaScript maps API to tap into a tile server's bitmap tiles, I soon wondered whether I could actually make a map from the vector data. It turned out I could and decided to revisit the structure of the group of islands I live on one more time and try to visualise the difference between Great Britain, the United Kingdom and the British Isles. The end result, punningly entitled the Great British Map, looks something like this ...

Great British Map

When the page first loads you'll see the coastlines of Britain, Ireland and towards the bottom, the Channel Islands. There's then five ways of looking at this particular map.

There's the group of geographic islands that's termed the British Isles; these show up in purplish-grey and if you're observant, the Channel Islands vanish as they're not part of this island group.

Great British Map - Great Britain

Then there's the individual geographic islands of Great Britain, Ireland, the Isle Of Man and The Channel Islands; these show up in green.

Great British Map - United Kingdom

There's two sovereign states, The United Kingdom of Great Britain And Northern Island and the Republic Of Ireland; these show up in red.

Great British Map - England

Next comes the administrative countries which make up the United Kingdom; England, Scotland, Wales and Northern Ireland. These show up in yellow.

Great British Map - Crown Dependencies

Finally, there's the Crown Dependencies, the self governing possessions of the British Crown; the Isle of Man and the Channel Islands are these and they show up as purple.

What's missing from the map? The British Overseas Territories, which is a polite way of saying what's left of the British Empire that didn't gain independence and which the United Kingdom still asserts sovereignty over. These are Anguilla, Bermuda, British Antarctic Territory, British Indian Ocean Territory, British Virgin Islands, Cayman Islands, Falkland Islands, Gibraltar, Montserrat, Pitcairn Islands, St. Helena, Ascension Island, Tristan da Cunha, the Sovereign Base Areas of Akrotiri and Dhekalia and the Turks and Caicos Islands.

If you're interested in how I actually made the map, read on.

The source data from the map are two public domain datasets from Natural Earth; the 1:10m map Admin 0 Subunits dataset and the 1:10m Populated Places dataset. This data includes shapefiles which can be converted into GeoJSON format by the GDAL ogr2ogr command line tool. I extracted the vectors for the UK, Ireland, Isle of Man and Channel Islands from the Admin 0 Subunits dataset, keying on their ISO 3166-1 Alpha-3 country codes.

$ ogr2ogr -f GeoJSON -where "adm0\_a3 IN ('GBR','IRL','IMN','GGY','JEY','GBA')" subunits.json ne\_10m\_admin\_0\_map\_subunits/ne\_10m\_admin\_0\_map\_subunits.shp

I then extracted the place data from the Populated Places dataset, again extracting data for the UK, Ireland, Isle of Man and Channel Islands, this time keying on their ISO 3166-1 Alpha-2 country codes. Not entirely sure why one dataset uses Alpha-2 and the other uses Alpha-3 but go figure; the data is free, accurate and open so who am I to complain?

$ ogr2ogr -f GeoJSON -where "iso\_a2 IN ('GB','IM','JE','GG') AND SCALERANK < 8" places.json ne\_10m\_populated\_places/ne\_10m\_populated\_places.shp

Finally, I merged subunits.json and places.json into a single TopoJSON file, with the added bonus that TopoJSON is much much smaller than GeoJSON. The source GeoJSON weighed in at 549 KB whereas the combined TopoJSON is a mere 78 KB.

$ topojson --id-property su\_a3 -p NAME=name -p name -o great-british-map.json subunits.json places.json

The main reason for use of TopoJSON is not that it's much more lightweight than GeoJSON, but that Mike Bostock's excellent D3 JavaScript library can easily slurp in TopoJSON and inject SVG straight into an HTML document. Which is precisely what the map's underlying code does. There's a lot more that D3 could do with this map, but it's early days and for a first step into a new maps library, I'm pretty happy with how it's turned out.

Speaking of code, it should come as no surprise that the map's code base is available on GitHub. The Great British Map is based on great D3 tutorial that Mike has written on vector mapping using Natural Earth, so the similarity between Mike's map and my map is entirely intentional.

You Were Here; Mapping The Places I've Been To According To Foursquare

another map. While I don't think for one moment this one will be as wildly popular as my last map was, this one is just as satisfying and a whole lot more personal.

At 8.01 PM on the 11th. of October 2009 I checked into Sushi Tomi in Mountain View, California. This was my very first Foursquare check-in. Since then I've checked-in on this particular location based service a further 12,394 times. Each check-in has been at a place I've visited. As this is a location based service, each check-in comes with a longitude and latitude.

This sounded to me like an ideal candidate for a map. But how to go about making one?

Over the weekend I made another map. While I don't think for one moment this one will be as wildly popular as my last map was, this one is just as satisfying and a whole lot more personal.

At 8.01 PM on the 11th. of October 2009 I checked into Sushi Tomi in Mountain View, California. This was my very first Foursquare check-in. Since then I've checked-in on this particular location based service a further 12,394 times. Each check-in has been at a place I've visited. As this is a location based service, each check-in comes with a longitude and latitude.

This sounded to me like an ideal candidate for a map. But how to go about making one?

Checkins - Global

I could have written some code to use the Foursquare API, but I've been running an instance of Aaron Cope's privatesquare for a couple of years now, which meant every check-in I've ever made, give or take the last 6 hours or so, is sitting comfortably in a MySQL database.

So I wrote some code to go through the database, extract each checkin and make a list of each place I'd checked into, the place's coordinates, the place's name and how many times I'd checked into that place. Armed with this information, I could then spit this out in GeoJSON format, which made making a map no more complicated than some mapping API JavaScript, in this case the Leaflet API. OK. There was some slight complication. I need to do some cleverness to make each checkin a CircleMarker, where the radius of the circle was proportional to the number of check-ins. Thankfully Mike Bostock's D3 library does this with ease.

It's not the most classy of visualisations. But I do like that the map shows me the global picture of where I've been over the last 4 or so years. As you zoom into the map, it's fascinating to see the patterns of my movements in areas I seem to go to on a regular basis, such as the San Francisco Bay Area ...

Checkins - Bay Area

... or Berlin ...

Checkins - Berlin

... or even Dar Es Salaam ...

Checkins - Dar Es Salaam

... as well as my journeys around my home country.

Checkins - UK

But there's still a lot of things that the map doesn't do.

The z-index, or stacking order, of the markers is based on each place's coordinates; ideally this will be adjusted so that the larger markers, those with the most check-ins, stack underneath the smaller ones so they're not obscured. I also want to add the ability to see some form of timeline and add some richer data about each place to the marker's popups.

But for now, it does the job I set out to do and to make life easier, should you wish to do the same, you'll find the source code up on GitHub.

What next? Well, now that I can download my Twitter history, I think all of my geotagged tweets are suitable candidates for some mapping ...

Two WordPress Plugins And The (Missing) Nokia Map

where am I" style WordPress plugins out there, but after some careful research I decided that none of them did precisely what I wanted, which was to show the last check-in I made on Foursquare, on a map, in the sidebar of my blog.

Those that did come close still didn't do the key thing I wanted and that was to use the map I work on as part of my day job. Now don't get me wrong, I've got nothing against the maps that I could have used; Google, Bing, Mapquest and OpenStreetMap produce very fine maps and they all have the JavaScript API I'd need to display my last checkin. But none of them used my map and that means a Nokia Map.

It's a glaringly obvious oversight but a few month's back I realised that given what I do for a living, there's something missing from my blog and that something is a map.

There's a whole slew of "where am I" style WordPress plugins out there, but after some careful research I decided that none of them did precisely what I wanted, which was to show the last check-in I made on Foursquare, on a map, in the sidebar of my blog.

Those that did come close still didn't do the key thing I wanted and that was to use the map I work on as part of my day job. Now don't get me wrong, I've got nothing against the maps that I could have used; Google, Bing, Mapquest and OpenStreetMap produce very fine maps and they all have the JavaScript API I'd need to display my last checkin. But none of them used my map and that means a Nokia Map.

So taking what I'd learnt about WordPress plugins during the course of producing 12 versions of the WP Biographia plugin, I rolled up my sleeves (mentally and literally) and started work on what would become WP Quadratum. I seem to have a thing about naming my plugins using a Latin derivation of their name; I have no idea why, but it seems to be better than something along the lines of WP Yet Another Foursquare Checkin Plugin. But I digress.

Several months later, after wrestling with getting a plugin to authenticate with Foursquare via OAuth 2 and learning how to write not only a WordPress plugin but also a WordPress widget, WP Quadratum appeared on the sidebar on my blog. It's over there right now, towards the top right of your browser screen, unless your reading this on a mobile device, in which case you'll just have to take my word for it for now.

Now Nokia allows free and unauthenticated use of the JavaScript Maps API, but only up to a certain number of transactions over a lifetime. So I also built in support for supplying Nokia's Location API credentials as well. But then I stopped. Why build custom support for authentication and credentials into a plugin, only to probably have to copy-and-paste the code into another plugin I write that will use the same Maps API? So I digressed again and wrote another plugin, WP Nokia Auth, that handles the Nokia credentials for me, and then made WP Quadratum play nicely with WP Nokia Auth, if it's installed, active and configured.

It took a while, but v1.0 of both plugins are now up on the WordPress plugin repository and on GitHub as well, for the usual forking, downloading, hacking and poking around. Whether they get the same number of downloads as WP Biographia has (over 7,000 to date) I somewhat doubt, but unless I release these, I'll never know, so that's just what I've done.

Farewell Yahoo! Maps API, Hello Nokia Maps API

leaving Yahoo! and joining Nokia in May of 2010 I said ...

So whilst I’m going to Nokia, I’ll continue to use my core set of Yahoo! products, tools and APIs … YQL, Placemaker, GeoPlanet, WOEIDs, YUI, Flickr and Delicious. Not because I used to work for Yahoo! but because they’re superb products.

... and I meant every word of it. The Yahoo! APIs were stable, powerful and let create web experiences quickly and easily. But now a year later a lot has changed. I still use Flickr on a pretty much daily basis, but Delicious is no longer a Yahoo! property and I transitioned my other web presence from using YQL for RSS feed aggregation to use SimplePie as YQL was frequently down or just not working. The original core set of Yahoo! APIs I use in anger is now just down to Flickr and YUI.

Yahoo's JavaScript and AJAX API was the first mapping API I ever used and it now seems hard to remember when Yahoo's API offerings were the dominant player, always iterating and innovating. The Yahoo! API set formed and continued to underpin the majority of my online presence. When I wrote about leaving Yahoo! and joining Nokia in May of 2010 I said ...

So whilst I’m going to Nokia, I’ll continue to use my core set of Yahoo! products, tools and APIs … YQL, Placemaker, GeoPlanet, WOEIDs, YUI, Flickr and Delicious. Not because I used to work for Yahoo! but because they’re superb products.

... and I meant every word of it. The Yahoo! APIs were stable, powerful and let create web experiences quickly and easily. But now a year later a lot has changed. I still use Flickr on a pretty much daily basis, but Delicious is no longer a Yahoo! property and I transitioned my other web presence from using YQL for RSS feed aggregation to use SimplePie as YQL was frequently down or just not working. The original core set of Yahoo! APIs I use in anger is now just down to Flickr and YUI.

YDN Maps Shutdown

Sadly, this trend is continuing and on September 13th, to badly mangle the quote from Cypher in The Matrix, "buckle up your seatbelts Map scripters, 'cause the Yahoo! Maps API is going bye-bye" and writing ...

var map = new YMap(document.getElementById('map'));

... will be a thing of the past. Adam Duvander, author of the excellent Map Scripting 101, has written a eulogy for the Yahoo! Maps API over on Programmable Web, including some pithy quotes from old friend Tyler Bell, whom I worked with when I was part of the Yahoo! Geo Technologies group, which sadly echo my comments on the overall demise of Geo at the company.

Thankfully all is not doom and gloom in the world of mapping APIs and Nokia's Maps API is firmly in the spotlight to take up the slack left by the addition of the Yahoo! Maps API to the deadpool. And if you're using Mapstraction with the Yahoo! Maps API, it should be relatively trivial to swap your code over to the Nokia API as Mapstraction now supports Nokia Maps. I may have had a hand in that.

WP Biographia Is But A Quarter Of The Way To WP Mappa

Matt Whatsit's fault; he writes very profane and very funny blog posts and reading his recent The Five Stages Of P****d Wife (which you should read if you haven't already, err, read it) made me laugh, hell, it made me ROFL and LMAO at the same time but it also made me think, though not necessarily about wives or drunkenness ...

Now background reading and general swotting up on a topic is all very well but to really learn how to do something you just have to roll your sleeves up and do it yourself. Though it's probably stretching a comparison too far, you don't learn to drive a car through reading the highway code; you actually get behind the wheel (preferably under supervision) and ... drive. You don't learn about what food tastes good from a recipe book; you ... taste the stuff yourself.

And so it is with writing code and using new and unfamiliar APIs. It was definitely the case with my recent (reacquaintance of, and) foray into JavaScript and the addition of support for Nokia's Ovi Maps API to the Mapstraction project, with the added benefit of having to teach myself how to move from my (by now very dated) knowledge of version and revision control under CVS to git.

In a way, this was all Matt Whatsit's fault; he writes very profane and very funny blog posts and reading his recent The Five Stages Of P****d Wife (which you should read if you haven't already, err, read it) made me laugh, hell, it made me ROFL and LMAO at the same time but it also made me think, though not necessarily about wives or drunkenness ...

Now background reading and general swotting up on a topic is all very well but to really learn how to do something you just have to roll your sleeves up and do it yourself. Though it's probably stretching a comparison too far, you don't learn to drive a car through reading the highway code; you actually get behind the wheel (preferably under supervision) and ... drive. You don't learn about what food tastes good from a recipe book; you ... taste the stuff yourself.

And so it is with writing code and using new and unfamiliar APIs. It was definitely the case with my recent (reacquaintance of, and) foray into JavaScript and the addition of support for Nokia's Ovi Maps API to the Mapstraction project, with the added benefit of having to teach myself how to move from my (by now very dated) knowledge of version and revision control under CVS to git.

May the source code be with you

So, first JavaScript and Mapstraction and the Nokia Maps API and now to PHP and the WordPress API. There's a lot of WordPress plugins that do geo-related stuff with your blog but none of them actually do what I want. WP Geo comes close, but it uses Google Maps and Google Maps only. Now I have nothing against Google Maps or the Google Maps APIs but I want maps from the company I work for on my blog.

When I came to add Nokia's Maps API to Mapstraction I at least had a head start. I'd done some JavaScript and I was at least familiar with the Mapstraction API. But writing a WordPress plugin was another thing entirely. Despite hosting my blog on WordPress since 2004 and being able to hack a moderate amount of PHP, I'd never needed to use the WordPress API. Until now.

Bearing in mind the old adage about walking before you can run I decided the best way to tackle this was to write a WordPress plugin for something much more simplistic and this is where Matt Whatsit comes in. At the foot of each post is a nice little biography; in Matt's case it read "Stole some Chewits in 1979. The guilt still haunts me".

So I searched for a plugin that would give me this capability. There's lots. But as with the desire for a geo-related plugin, none of them did exactly what I wanted. The closest I could find was Jon Bishop's WP About Author plugin. So, as all WordPress plugins are licensed under the version 2 of the GNU Public License, I took Jon's plugin and hacked it to do what I wanted it to do. The result is what I've called WP Biographia and you should be able to see the results of it at the foot of this post, if you're reading it from this URL.

I now know, or at least understand at a conceptual level with much web searching of the WordPress Codex, how to write and structure a WordPress plugin. I still need to know how to write and structure a WordPress widget but that will form part of the next version of WP Biographia. By then, I should be armed with enough WordPress API knowledge to start to write what I really wanted to write, which is my geo-related plugin, which may, or may not be called WP Mappa. I'm only a quarter of the way there, but it's a quarter more than when I started this.

In the meantime, WP Biographia is now part of the official WordPress plugin repository and is also up on github as well. It also now has a resident page here on my blog which I'll update as and when I make sufficient changes and improvements to warrant a new version.

Starting to code again is addictive and I seem to have managed to rack up a few github repositories of recent. WP Biographia is but one of what I've christened, in line with the theme of Gary's Bloggage, Gary's Codeage. For now, it's a holding pen for those code projects that live in github but for which I've yet to write a formal page on. These may appear sometime in the not too distant future as and when time permits.

Photo Credits: ficek1618 on Flickr.

Mapstraction, Maps and Me

Nokia has been taking up almost all of my time and what little time has been left has been spent with my family. But in between day job and family time there's evenings spent in a hotel room and hours spent on a plane, mainly between London's Heathrow and Berlin's Tegel airports. It's in these periods of time that a combination of my MacBook Pro, running a combo of Apache/MySQL/PHP with MAMP and TextMate has allowed me to rediscover the pleasure of what I used to do for my day job before Yahoo! and before Nokia ... and that's to write code.

It's been a while since my last blog post; my day job at Nokia has been taking up almost all of my time and what little time has been left has been spent with my family. But in between day job and family time there's evenings spent in a hotel room and hours spent on a plane, mainly between London's Heathrow and Berlin's Tegel airports. It's in these periods of time that a combination of my MacBook Pro, running a combo of Apache/MySQL/PHP with MAMP and TextMate has allowed me to rediscover the pleasure of what I used to do for my day job before Yahoo! and before Nokia ... and that's to write code.

As a fully unreconstructed maps nerd, I love the variety and richness of the mapping APIs available on today's internet. One of the best books on how to use these mapping APIs is the "does just what it says on the label" Map Scripting 101 by Adam DuVander. While the book touches on the power of the APIs from Google, from Yahoo, and from Bing (amongst others) its main focus in on Mapstraction, the JavaScript mapping abstraction library.

Brain Map

As the name suggest, Mapstraction abstracts, or wraps, the differences between the variety of approaches that each JavaScript mapping API uses into a single consistent interface. With Mapstraction, the API methods to create a map, to change the zoom level, to centre the map, to add a marker or push pin to the map are the same, regardless of which underlying mapping API you use.

Mapstraction allowed you to use the mapping APIs from Google, Yahoo, Bing, Cloudmade, GeoCommons, Cartocuidad, Yandex and MapQuest. But not Nokia's Ovi Maps API, which was released in February 2011. This is where my local Apache installation, TextMate and the aforementioned hotel room and flight time comes back into the story. Cue a frantic crash course to reacquaint myself with JavaScript, some trial and error, some swearing and some background reading to convert my slightly outdated knowledge of CVS into how to use git and Mapstraction now supports the Ovi Maps API. No, really. It's on github right now.

There's a demo of some of the major features of both Mapstraction and the Ovi Maps API over at maps.vicchi.org and, in the spirit of social coding, the source for that is on github as well.

I'm not suggesting for one moment that if the current geo day job falls through I can happily pick up a replacement role coding JavaScript, or coding anything for that matter, but it's oddly reassuring that I still have the vague ability to continue the profession of coding software that earnt me a living for almost 25 years.

Photo Credits: Infidelic on Flickr.