Today I posted my first open source project. A jQuery interface to the Lighthouse API. Sure it’s a super lightweight wrapper to an external api and the whole thing doesn’t exactly take up much hard-drive space, but it was an interesting endeavor none the less.
Most of the development time was spent designing the interface in my head (what’s that old saying about if i had more time, i’d have written less?). At first i wanted to implement just a standard interface of getters and setters. Something along the lines of:
var json = $.jBeacon.getProjects();
However, i quickly realized that this was not going to be so simple. First there’s the issue of cross-site ajax calls. Sadly, browsers will not allow a site to make an ajax call to an external site (for obvious security reasons). Luckily, the good folks over at entp (makers of Lighthouse) have implemented a json(p) interface to the api. Not to go into too much detail, but basically some resourceful javascript hackers realized long ago (before you were playing around with request objects) that you could communicate with a server by simply embedding a script tag. Fast forward to the world of web 2.0 and we now have a standard way of returning json data via a “callback”. Basically you request a page (like http://yourapp.lighthouseapp.com/projects/projects.json) and you append ?callback=[your callback function]. The server on the other end will prepare the data you’ve requested, throw together in json and then wrap it in javascript code that calls whatever function you pass into “callback” and give it the json as an argument.
Pretty slick, and it’s even slicker with jQuery because it’s all abstracted away into a simple .getJSON request. (jQuery’s core will analyze the request, see that it’s to an external domain, perform a json(p) request and even mediate the callback to an anonymous callback function you pass in as an argument).
Sadly this was not the last hurdle of my tiny project. Turns out jQueries hacks to make ajax run synchronously (locking the browser or some noise) don’t work with json(p) requests (and frankly aren’t really a good idea anyhow). This is when i figured my hardly-useful-anyways little wrapper project was finished.
Until i realized the proper design decision all along should have been the one that jQuery has made so prevalent. Event binding with anonymous callbacks (and in my case, event delegation to anonymous callback functions).
So instead of my getters returning json, my getters would receive an anonymous callback function and delegate their callbacks to them. So the interface ended up looking something like this:
$.jBeacon.getProjects(function(json) {
//Do something Here.
});
As you can see, this design pattern is used everywhere in jQuery, so it should be pretty comfortable if you’ve ever done any jQuery development. I also threw in a settings function to set up the account name (so you would only have to write that once) and you can also pass in an optional token.
$.jBeacon.settings({
account: “your_account_name”,
token: “your_token”
});
Just set that before any of your api calls and you should be good to go.
If you’d like to check out the project on github, you can find it here:
This should be the first piece of a Lighthouse miniapp i plan to build (similar to Warpspire’s Burndown). More details to follow.
