Javascript Events, the DOM, and Firefox/Gecko

OK, here’s the deal, as quick as I can put it, but with enough words that Google will correctly index this post and make this information easier to find for the next person who needs it.

Let’s say you’re developing a Firefox extension, and you need to look at the HTML of the page. You know that Firefox is constantly throwing event notifications — there’s the MouseEvent “click” when something is clicked, the KeyboardEvent “keyup” when a key is release, and so on.

So, you figure “well, I need the HTML of the page, so I’ll wait until it loads, then grab the source/parse the DOM tree/unleash flying monkeys”. You know that the style of

window.onload = the_function_name;

is bad, because it only lets one function receive the load event. So, you write some code like

gBrowser.addEventListener(“load”, the_function_name, true);

because this is what you want. You wait for the “load” event to fire, and then run your function. Test this code out, and it will work well-enough, most of the time. Sometimes, it lags, sometimes it doesn’t even fire at all. WTF? Well, I’ve been there.

Here’s the thing: the “load” event fires when loading is done. If you’re looking at the whole window/document, it’s not done loading until the whole document is loaded, including bandwith-and-time-heavy images. And these things can be slow to load, or hang entirely. This can seriously mess with the concept of “loading”. You don’t care about any of these things, you just want the HTML.

Well, Firefox is a very deep project, and there’s a few secret events that aren’t widely used or documented. If you want to know when the HTML is loaded — or more accurately, when the DOM Tree’s content is loaded — there’s a special event you can monitor: “DOMContentLoaded”

gBrowser.addEventListener(“DOMContentLoaded”, the_function_name, true);

This is a very reliable way of knowing when the browser has loaded only the page. The catch is that it’s Firefox-internal only. Which means it only works from an extension — you can’t use this in a web page. There are techniques for duplicating this functionality in other browsers, but that’s getting beyond this post.

Detecting page loads in a Firefox Extension

Detecting page loads is a useful ability. It’s easy enough to throw in a

gBrowser.addEventListener(“load”, function_name, true);

But, it causes extra events to get generated. There’s load events occurring in the browser that aren’t page loads. The trick to detecting real page loads (but not Back/Forward navigation when the page is still in memory — only page loads that have a server hit) is to look at the event’s target. In this example, “event” has been passed into the function specified in the addEventListener call above.

if(event.originalTarget instanceof HTMLDocument) {

will make sure that the load event came from a web page being loaded. You can even go a step further and filter out different types of HTMLDocuments.

if(event.originalTarget.defaultView.frameElement) {

will catch events that were triggered as the result of a frame or iframe. It’s an important step, because lots of advertising networks embed their ads in iframes, and you probably are more interested in the actual web page than the ads on that page.