Rules for Bookmarklets

Bookmarklets are, as you know by now, Javascript code. Most bookmarklets are designed for manipulating the contents of the currently loaded web page directly (like text highlighting) or somehow use it as input in a process (like a keyword search or a listing of links). A few bookmarklets don't use the content of the current page. Examples of these are a bookmarklet presenting an ASCII table or a color table. Most of the time, however, you want to use the current page in some way.

There are a few rules you should be aware of when you design your own bookmarklets.


Frames/No Frames

Bookmarklets execute in the current browser window. The window can contain a single document or several documents, in the form of a frameset. A bookmarklet that operates with the document's content (text selection, images, links, whatever) will generally not work in a frameset.

However, you can almost always design your bookmarklet so it can handle frames. For example, I've created a bookmarklet that lists frames. It works by traversing frames recursively (if it finds any).

See the tips page for some sample code you can use to create bookmarklets that handle frames (as well as pages without frames).


Return Values

If a function or an assignment returns a value, which you do not catch, the bookmarklet will redirect to a new page that shows the returned value. Silly, I know, but that's what it does. You can intercept the return value by encapsulating the relevant statements with void(...).

You need to void all statements that return a value unless the statement is inside a function. Note that assigning a value to any document element returns a value. In other words, there are three cases where you need to void your statements:

  • When you get a return value, eg.
    void(x=3);
  • When a variable reads from a document element, eg.
    void(lnks=document.links);
  • When a DOM element is changed, eg.
    void(document.links[0].href='http://www.ibm.com/');

Actually, you can also catch a return value using var (but void is generally more useful):

  • var x=3;

You don't need to void a statement like alert('Hello');

Personally I seldom bother with void and var. If you place your code inside a function none of this is necessary. See the tips page for instructions.


The Number of Characters

There is a limit to the number of characters your bookmarklet can contain. The problem is, this limit differs between browser versions. These are my findings on the number of characters supported by different browsers:

Browser Max chars
Netscape > 2000
Firefox > 2000
Opera > 2000
IE 4 2084
IE 5 2084
IE 6 508
IE 6 SP 2 488
IE 7 beta 2 2084

As you can see, Explorer 6.0 can only handle up to 508 characters, and Explorer 6.0 SP2 is even worse with max 488 characters! Explorer 7.0 appears to amend the situation with a maximum of 2084 characters.

In other words: If you want to be sure your bookmarklet runs in Explorer 6.0, it must be maximum 488 characters. For advanced bookmarklets you may find that this is just not possible.

Actually there is sometimes a way around this limit. Your bookmarklet can include script code from a separate Javascript document. This document would be located remotely on a web server. The bookmarklet can then call extensive methods which are implemented in the document in stead of in the bookmarklet. See the tips page.

The limitation is not a general scripting problem - a script in a page can be any length. The problem arises when you add the bookmarklet to your favorites (or make a link somewhere else) and run it from there. You'll find that the content of the favorite (the bookmarklet script code) is truncated, which means it won't work.


Use Single Quotes

Javascript allows you to use both single quotes ( 'xxx' ) and double quotes ( "xxx" ) in string expressions. Whenever possible use single quotes. This is the unofficial convention, and adhering to it will make it easier to distribute your bookmarklets to others via a web page.

In the cases where you need to work with double quotes you can often get around it by escaping/unescaping your strings. For example, unescape(%22) is a double quote. I have some tips on strings.


Watch your Variables

Since bookmarklets have complete access to the current web page, it means you also have access to any global variables the page's author has used in his own scripts. For example, the author may have used a variable called str. If you use the same variable name you are actually using the author's original variable. This is not a problem if the variable is not used further by the author, but if the page is supposed to reference the variable at a later time - say, when you press a button on the page - bad things may happen if you changed the variable in the mean time.

The way to handle this is to use "ugly variables", ie. variable names that are so exotic they are unlikely to be used by anyone else - like hd8ki2.

Admittedly this is a rather hypothetical point. I doubt I have ever experienced such a name clash in real life. In my bookmarklets I just use any common variable name I like, such as i or s. I suggest you do the same and just forget about this.

Furthermore, you can eliminate this problem by encapsulating your code in (function(){...})(). See the details at the tips page.


Cross-Platform Functionality

One of the things you learn as a web developer is that different browsers have different DOM's (Document Object Model - the interface you have to work through when accessing an HTML document's elements through scripting). The DOM of the two most common browsers, Internet Explorer and Netscape, differ substantially in some ways, which means you sometimes have to create different script code for the two versions - Although from Netscape ver. 6 and IE ver. 5 the same code can be used most of the time, as the browsers now adhere to the same DOM standard (most of the time anyway). Unfortunately this common code will not work in earlier browser versions.

If you don't plan for other people to ever use your bookmarklets there's not much need (or motivation) for you to design your bookmarklets for different browsers and browser versions.

However, if you want to make cross-platform bookmarklets you should take care to use code that can be understood by all browsers. Sometimes you may need to perform a browser check inside your bookmarklet, executing different code accordingly, other times it's easier to just create different versions of the bookmarklet. Sometimes there's just no way you can perform a particular action in another browser. For example, Internet Explorer has some sofisticated (non-standard) text selection methods that Netscape and Opera don't have.



Top of this page
Go to the main page
Send e-mail
Updated 13 Apr. 2006