Rules for Bookmarklets
There are a few rules you should be aware of when you design your own bookmarklets.
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).
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
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:
Actually, you can also catch a return value using
You don't need to void a statement like
Personally I seldom bother with
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:
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.
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
In the cases where you need to work with double quotes you can often get around it
by escaping/unescaping your strings. For example,
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
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
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,
Furthermore, you can eliminate this problem by encapsulating your code in
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.