2005-11-11

On-demand cross-site javascript

While I am neither firm believer nor much versed in the design patterns camp, they make good, neat vocabular units. It won't become a true lingua franca until enough people in the extended circle (by which I mean the wide public of not very acacemically versed J. Random Hackers) are familiar with them, but I would still encourage reading up on them, at least a little. This post, once I get on with it, will cover some ground on on-demand loading of javascript, which is also the largest common denominator with the ajaxpatterns article I read as inspiration for and background to writing this.

While I believe design patterns by now at least almost are safely out of hype, they were a religious plague a few years ago when present day plagues like AJAX had not yet caught on. I remember reading an article by a frustrated or at least blissfully cynical Jamie Zawinski, probably at gruntle (though I can't seem to find it now), where he patiently explained that design patterns do not make good programmers out of mediocre programmers. The pattern is a concept explained in simple terms, a basic idea, if you will, on how a problem or part of a problem is formulated as a solution, but you won't design high quality software just by having read up on a library of off the shelf patterns. (In case someone would happen to dig up Jamie's article, by the way, you will most likely find that this is my take on the rant, though by all means read Jamies' too -- it was a good read.)

Anyway, the one thing I had expected to find in an article about on-demand javascript but did not find, was a run-down on how to perform cross-domain on-demand loading of javascript code that you have not written yourself. And consequentially, which will not magically plug in with the rest of your pages and find its place somewhere, hooking up with the rest of your code, announcing "I'm live and loaded now!", which is otherwise a very comfy way of writing external modules. In summary: how do we fire an onload callback, once a <script> tag we just added to the document flow has been fetched and parsed?

Nope, you didn't miss it; it wasn't there. I suppose there might have been in the linked Do you want to know more? tutorial article by Thomas Brattli at the end of the page, but that place had unfortunately been defaced by some schmuck who adolescently replaced all content text with 65,000 by 65,000 pixel wide goatse.cx images from web.archive.org and a note deriding Windows IIS security. (I mailed Thomas about it; hopefully he will find the time to restore his site.) Many browsers are known to crash at huge images like that, by the way -- I strongly advise against going there to look for yourself, if you have anything important going in the your browser session (hence my not linking there directly from here).

If we had wanted to load the script from our own domain, we could of course have used XMLHttpRequest, but without that, we are pretty much left to our own devices. As it happens, I stumbled upon one of those devices just that yesterday, in looking for inspiration on how to integrate Del.icio.us JSON feeds for purposes such as making a categories (or tags) side bar, along the lines I touched briefly in yesterday's post. Ma.la (who probably has a better name, but I'm afraid my Japanese isn't what it should be) has made a striking little piece of inginuous code that does just this -- watch this del.icio.us JSON feed dynamic loading demo (usage: type a del.icio.us user name in the input field and click load to add the most recent fifteen bookmarks to the page).

The bold face bits together perform the magic of running the feed_onload callback, once the code has been fetched from Del.icio.us, and the Delicious.posts variable is defined (since that is what you get when you pull in a Del.icio.us JSON feed).

How this magic works? Well, the setup code before the first bold statement (horrible pun, I admit) sets up some scaffolding for a poll loop trying to evaluate a statement 100 times a second until it eventually yields something non-false without throwing an error. A bit smelly, and a bit elegant, both at the same time. (I would have settled for something much less frequent; running every ten milliseconds feels somewhat excessive, but to each their own, I suppose.)

The second bold face statement makes sure the onload callback won't unintentionally get fired again, by deleting the variable the loader is looking for, or else we would get a page growing fifteen new links every ten milliseconds. This code is of course asking for trouble in the event of multithreaded javascript ever happening in browsers, but until then, there is no race condition to fear.

The less dynamic approach I am planning on taking at the moment, only loads the feed once at page load, then writes some code into the page and considers itself done. It does not really qualify as on-demand javascript, but rather multi-source javascript compositioning, which is useful too. I'm talking about loading a Del.icio.us JSON feed on pageload, adding some navigation based on it (such as the categories you see at Greg's Speccy blog, which is implemented just this way), or Yamy 改め Chalice's Del.icio.us sidebar, which lends itself better for an example. (Again, I wish my Japanese was better; it really looks like a good site.)

Chalice simply solves the problem the Web 1.0 way: first include the external script, then your own (in-line or externally, whichever you prefer) which uses the data loaded from the first script. Basic, robust, foolproof. The HTML standard guarantees that both scripts are loaded before they get executed, in document order, and all is fine and dandy.

This will do for a static navigation panel. It works for Greg and it works for Chalice. Personally, though, I'm still curious about the mechanics of dynamic loading, for my later ideas on a dynamic navigation variant, functionally very similar to Greg's, but with unfoldable categories that expand and show links from other categories without reloading the entire page. It's this kind of small AJAXish applications I'm most mirthful playing with, and I'm really looking forward to eventually cracking that nut. What guarantees do browsers offer about the loading and execution order when you inject new script tags into a loaded document? Indeed, what happens when an external script does not load?

It's very hard to track down answers for questions like these by asking Google, and it's not particularly easy by reading standards either -- the W3C HTML standard, for one, is mostly about the "solid state" HTML document approach, and does not address the DOM "one-page HTML application" approach many of us are moving on towards today. Useful pointers to articles on subjects like these are warmly welcome, by the way.

2005-11-10

Blogger Del.icio.us categorizer script

Update


I have now abandoned this version of the script in favour of its much upgraded, extended and bug fixed successor script, which does the same thing and more. If you are having trouble with this script, or miss features, I would recommend upgrading first.

I've spent the better part of the night and morning working on a Greasemonkey script that helps me organize my blog posts into categories, using Del.icio.us as a remote metadata storage for my posts, with or without category tags alike. (Since I am planning to eventually roll out some additional navigational aid code which will rely on having access to post titles, dates and timestamps, besides tags, to all posts in the blog. Blogger doesn't do half of that now and I won't hold my breath waiting for any of that to appear anytime soon.)

Anyway, what I have made is a script that extends an already rather nice tag adder script by Jasper de Vries. Jasper's version adds Technorati tags to posts, mine adds Del.icio.us tags. Just type in your tags in the Tags field added to the posts page (space or comma separated), and any post with tags will get a <div class="tags"> widh an unordered list of all tags, linked to your appropriate Del.icio.us tags.

Blogger editor with Tags field

Here is the nifty bit. When your then publish your post, the "published successfully" page has been blessed with two additional buttons; a "Link at Del.icio.us" link, and a "View Post" I threw in for good measure (since I have often missed a link there to visit the exact post I just (re)published, rather than going to the blog index page).

Del.icio.us link on published page

It's the Del.icio.us link that is the primary component, though, and when you click it, you are brought to the standard Del.icio.us "add bookmark" page, all fields filled in. (Post title, post permalink URL and timestamp, plus the tags you already typed in. This way you can keep both the tags on your posts and at Del.icio.us in sync easily, which is a good start for making even nicer category browsing hacks such those Greg has deployed in his Speccy and Vent blogs.

The first time you use the script in a blog, it will ask some questions -- how you want to list the links in the blog (I use "Categories:" in mine), what the link to your Del.icio.us tags is, and whether you want to add additional tags to all posts (I add "ecmanaut" to them, so I can easily get a feed which only lists my own posts here without messing them up with any other social bookmarks of mine). You may reconfigure these options anytime by clicking the Tags: label, but remember that you must also republish old posts, if you want to change the header (since it's a part of the post text, rather than of the template itself).

Come to think of it, that might not be a very pretty arrangement; I might make another version which lets you give an id for a div where the <ul> with categories gets put, but for now this will do. (It's also easier to deploy for you, this way; no need to alter any templates, except perhaps to add some CSS for the div.tags selector and optionally its ul, li and a descendants.)

One more note, before I leave you to your own devices. When you update a post's entry and change tags on it, the link to Del.icio.us won't pick up the new categories, even though they are properly fed in the URL, so you might have to copy them manually. I'm not sure if that would count as a bug or a feature, but now that you know, you won't have to get bitten by it, either way.

Del.icio.us pre-filled-in bookmark form

Enjoy! And if it bothers you that I have more or less considered the words Tag and Category interchangably above, you may move on to Sambot, and learn why tagging is such a great thing. Because it really is.

Not satisfied with how the formatting of your tags list came out? You might find a hint or two about styling them with CSS in this follow-up article about how to make your tags line up on the same line.

2005-11-09

Google Reader: adding access keys

I like Google Reader, but find its support for keyboard navigation a bit lacking. A few days ago, I thought I would file a feature request with the developers (assuming they read their mail) for adding hotkeys for page up and page down links, but then I got impatient and sketched up a Greasemonkey solution of my own instead. It's as future proof as the google developers allow it to be, and it is fairly easy to change to your own preferences.

Bottom reader paneWhen you install my Google Reader access keys script, you will be rewarded with a few additional on-screen hints (some characters who did not use to be have become underlined), and pressing those keys will activate that link or toggle between the choice's available options.

I thought I would dive into how I accomplished this. At the top of the script, you find what looks like (and indeed is) a mapping from keyboard shortcuts to some maybe slightly scary-looking CSS selectors. Edit the key, and your version of the script will have a different set of keyboard shortcuts. To make it a bit more readable, I annotated each key with what function it defines:

var keys = { 'U':'a#queue-page-up',     // page Up
'D':'a#queue-page-down', // page Down
'B':'div#order-by', // order By
'S':'div#read-items', // Sort by
'E':'div.read-state label' // kEep unread
};

The selectors point out which element contains the control, and the text it carries. Further down in the script, I use these to find what link to "click" and which piece of text to add the underline hint to. Here is the code that adds the underlines:

var key, selector, node, label;
for( key in keys )
{
selector = keys[key];
node = getElementsBySelector( selector );
if( !node.length ) continue;
node = node[0];
if( node.nodeName.match( /a/i ) )
underline( node, key );
else if( node.nodeName.match( /div/i ) )
{
label = node.getElementsByTagName( 'label' ).item( 0 );
underline( label, key );
}
}

Then we set up the keyboard snooping, listening for our access keys:

document.addEventListener( 'keydown', keypress, false );

This will call keypress() whenever a key is pressed in the reader interface. (The details of that method will follow shortly.)

Keep unreadgetElementsBySelector is Simon Willison's document.getElementsBySelector(), and would have been massive overkill if the kind Google Reader Developers would have added id attributes for all functional components, which they unfortunately do not (...yet? -- the "Keep unread" checkbox only has a class name). If they would have, we would have just put node id:s there rather than selectors and used document.getElementById() instead, halved the script size, shaving off 4K of it in one go and been somewhat less resource intensive runtime.

My underline() method takes a node and a key (a character) parameter, and tries to find that character in the user visible text contained by the node, and add an underline to the first occurrence of it. (In case the text already had an underline, as is the case with the links, it will add another underline by using the CSS border attribute instead.) It's a very useful function; feel free to pick it up separately:

function underline( node, key )
{
if( !node ) return;
var character = new RegExp( '(<[^>]*>[^<'+ key +']*)*('+ key +')', 'i' );
var hasOne = getStyle( node, 'textDecoration' ).match( 'underline' );
var style = hasOne ? 'border-bottom:1px solid' : 'text-decoration:underline';
var underlined = '$1<span style="'+ style +';">$2</span>';
node.innerHTML = node.innerHTML.replace( character, underlined );
}

function getStyle( node, style )
{
if( node.currentStyle )
return node.currentStyle[ style ];
if( window.getComputedStyle )
return getComputedStyle( node, null )[ style ];
return '';
}

Time for the key input crunching code. First, we make sure we got a key we handled and which node it is bound to by our magic keys mapping above. If it isn't there, or the node isn't (it might become deprecated in a future version of Google Reader), just exit right away:

function keypress( event )
{
event = event || window.event;
var key = String.fromCharCode( event.which || event.keyCode );
var node = getElementsBySelector( keys[key] ), label;
if( !node.length ) return;
node = node[0];

Now we look at what node we have picked up -- if it's a plain link, or a label element (as is the "Keep unread" link -- a label with an encapsulated <input type="checkbox"> tag, to be precise), we just send it a mouse click:

  switch( node.nodeName )
{
case 'A':
case 'LABEL':
simulateClick( node );
break;

And if it was a <div> tag, we look for all its descendant <a> tags, assuming they are options to toggle between when our access key has been pressed:

    case 'DIV':
var choices = node.getElementsByTagName( 'a' ), i, current = 0;
for( i=1; i<choices.length; i++ )
if( choices[i].className.match( 'selected' ) )
current = i;
node = choices.item( ++current % choices.length );
simulateClick( node );
break;
}

Then we look through these links to see which one carries the "selected" class name, pick the next node (wrapping at the number of choices available, so it will find the first choice when the last choice was active) and send it a click.

All of this knowledge of document structure has been picked up by inspection of the page structure in the Firefox Document Inspector beforehand, by the way, so my knowledge of this page isn't anything overly magic. "inspect this" arrow Just press Ctrl+Shift+I on any page (having made sure you checked the "Developer tools" checkbox on first installing Firefox) and it will pop up. To find out the looks of the tag neighbourhood around "Show read items:", for instance, I first clicked the "inspect this" arrow, then clicked the "Show read items:" text in the main window, and was rewarded with this insight into the structural neighbourhood:

inspector DOM tree overview

If you recall the keys mapping, the Sort by key was bound to the div#read-items div, in the screen shot above listed as the parent of the label and the two <a> tags, read-items-hidden and read-items-visible. In case we wanted a key to not just toggle between these modes, we could bind either or both directly too, by tucking in another 'H':'a#read-items-hidden', line back there, for instance, following this same recipe. Neat way of adding functionality without really adding any code, right?

Finally, we make sure that the keys we heard are swallowed up, so they don't have any other effect, besides toggling visibility or clicking somewhere or whatever else we did:

  event.preventDefault && event.preventDefault();
event.cancelBubble && event.cancelBubble();
}

This odd code configuration is a safeguard in case the browser would not support these methods, in which case nothing happens and no errors are left hanging in the javascript error console. It's polite to ask before accessing methods you are not sure about how portable across browsers they are, and user scripts are known to work both in Mozilla, Opera and Internet Explorer (with funky third-part extensions) today so while I don't often try my hacks in all three nor across different platforms, I throw in a few checks like these where I'm uncertain.

The only bit of code left unspoken for now is the simulateClick function, which I picked up from the Google Reader blog eariler today.

Using this approach, you can add keyboard bindings fairly painlessly to mostly any web page or web application, not only Google Reader. It's easier when you have some kind of guarantee of the developers over there not haphazardly changing document structure and node id:s, classes and semantics of things as often as they change underwear, but even when they do you are usually only some inspection in the document inspector and a few tweaks to the CSS selectors in the keys mapping away from a new version of your own keyboard access features. The best thing, of course, is mailing your improvements to the people behind the site you inject your preferences into, but in the cases where those people are hard to reach (or persuade) the Greasemonkey approach is your ever trusty friend.

Happy accessibility hacking!