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.