Last week I showed you a bookmarklet that lets you edit your CSS live in any browser. Today, I want to dive into the details of how to create a bookmarklet. But first, the basics:

What is a bookmarklet?

A bookmarklet is a small snippet of JavaScript crammed into a URL. Nothing else. That's not very helpful, though, is it? All it means is this: instead of using the http: or ftp: protocol for a URL, we use the javascript: protocol. And when this URL is invoked (perhaps by clicking a bookmark in your browser's bookmark toolbar) the remainder of the URL is executed as JavaScript. What this means is that we can execute any arbitrary JavaScript within the context of any site we please. And we can package it so that it can be shared and reused easily. But...

What is the point?

In general a bookmarklet will either alter the current page in some way, or make use of the context of the current page in concert with some other service. Some examples of the former are edit CSS, jQuerify, Firebug Lite, and 960gs grid overlay. These are usually only useful to developers. Some examples of the latter are URL shorteners, post to delicious, Amazon wishlist, and Instapaper. These are much more useful to consumers. Both kinds of bookmarks use the same technology, though, so the approach to developing them is basically the same.

The "Hello World" bookmarklet

Create a bookmark, and give it the following URL:

javascript:alert('hello%20world');

Now click the bookmark. Yep, that's all there is to it. Notice that we replaced the space with %20. That's important, and there are a few more rules that we need to keep in mind when creating bookmarklets.

Gotchas & Tips

URL length limit

I'm not sure what the definitive answer is on this. IE is (unsurprisingly) the limiting factor here, but I've heard conflicting information on what the actual limit is. I haven't bothered to test it since that would mean firing up Windows and opening IE, which I avoid at all costs. So, just keep it really really short, m'kay?

Cheat the URL limit

Most bookmarklets try to do way more than is possible within the URL limit I just described, so of course there is a way to cheat the rule. Just host an external JS file that gets dynamically required by your bookmarklet. Here is an example. The bookmarklet just appends a SCRIPT tag into the HEAD of the document, which requests and executes the external JS file.

Don't return a value

If your bookmarklet code returns a value, that value will find it's way to the browser's address bar. This is most likely not what you want, so you have two weapons to use against this. You can append a void() call at the end of your JS code:

someCode();void(0);

Or you can wrap your JS in an anonymous function. The added benefit here is that any variables you define are not polluting the global scope:

function(){someCode()}();

Don't depend on a JS library

Probably an obvious one, but you can't assume that jQuery, Prototype, or any other library is included in the page where your bookmarklet will eventually be run. I got around this in my Edit CSS bookmarklet by dynamically including jQuery and running it in noConflict mode. See the code for that here.

Next steps

If you want to write a bookmarklet that integrates with a Rails application, definitely check out John Nunemaker's screencast. Also dig into the bookmarklets that I linked to earlier in the article. If you have a favorite bookmarklet or want to know more about bookmarklets, please join the discussion below.