XUL Solutions

If you used XUL Planet's version of the XUL Tutorial, you must have come to realize that the extension installation part is significantly outdated. The installation process was significantly changed on Firefox, and the infamous install.js script has been put to sleep. It still lives in the old Mozilla Suite and Seamonkey, I think.
Here's the deal: extensions used to use a script (install.js) to perform certain installation operations. Most of them were really repetitive and predictable chrome registrations, while on some cases extension developers would add some specific post-install operations that were required for their extension to work properly.
All of that got the axe. Firefox extensions no longer include that script, and including it will have no effect on installation. It won't be executed, period. Chrome registration has been moved elsewhere (the chrome.manifest file) and post-installation scripts can no longer be bundled this way. It was a good move in my opinion. Most extensions don't require post-install scripts, so this makes life easier for the majority.
But what happens when you do need a post-install script? Well, don't worry. Creating one is not very complicated, and I'll explain how to do it.
Most (all?) extensions overlay the main browser window (chrome://browser/content/browser.xul). If yours doesn't, add one, it's not going to kill you. The same applies to extensions on other applications, as long as there's a main xul file you can overlay. The least you'll need to add is a script:

<overlay id="homepage-overlay"
      xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
<script type="application/x-javascript"
       src="chrome://myextension/content/overlay.js" />
</overlay>

Next thing you'll need is your overlay script (on overlay.js, or whatever name you prefer):

const MY_EXTENSION_VERSION = "0.1";

function initializeOverlay() {
var pref =
  Components.classes["@mozilla.org/preferences-service;1"].
    getService(Components.interfaces.nsIPrefBranch);
 var finished = "";

try {
  finished = pref.getCharPref("myextension.install.finished");
} catch(e) {}

if (finished != MY_EXTENSION_VERSION) {
  /* add post-install stuff here. */
  pref.setCharPref("myextension.install.finished", MY_EXTENSION_VERSION);
}
}

window.addEventListener("load", initializeOverlay, false);

A little explaining is in order. First of all, the initializeOverlay function is added as a load event handler. This will make the browser execute this function when it's main interface is about to be drawn and shown to the user. This means this function is executed shortly before the user can actually see the window. You can access DOM elements though, because the DOM for the window is already loaded.
Secondly, we need to make sure our script is only executed once, right after installation. That's why I'm using a preference (myextension.install.finished) to serve as a flag that indicates whether the post-install script has been executed or not.
Note that I didn't use a boolean preference, but a string preference that holds the current version of the extension. The purpose of this is to make this script a little more robust. You never know how this script is going to change in future versions, so you may need to do different things when doing a fresh install or upgrading from version X to version Y. Things are just nicer this way. On the not-so-nice side, you'll have to remember to change that constant every time you change version numbers. You'll also want to clear this preference when the extension is being uninstalled. But that's the topic of the next blog: Creating an uninstall script for an extension.

Labels: extension, installation, preference, xul