2006/07/02

Creating a post-install script for an extension

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: , , ,


Comments:
Hi I want to know whether this script will execute only whe the extension is installed for the first time or everytime the browser opens up.

Thanks
 
Hi Tina,
The script will run every time the browser opens up, but, as explained in the post, there is a preference that makes sure that the first part of the script runs only once.
Also, if you're creating extensions for Firefox 3 and above, there's a new alternative with the FUEL library: http://developer.mozilla.org/en/FUEL/Extension
 
Hi Villa

Can you please explain me how can i write script on installation of add-on, i want to open an xul page at installation time.
is it possible?
please help me.
 
Nehal,

There isn't much more to what I already posted. You can just add the window.open("chrome url") code to the post install script, and it should work fine.

You might want to add a timeout to the function call because the session restore feature can cause weird things to happen. Let me know if there's more you need to know.
 
Hi Villa,

Thanks for your reply. Now I am able to open an xul page at installation. but it is come only first time i am installing add-ons, I put my code inside this "(finished != MY_EXTENSION_VERSION)" condition, if i uninstall add-on and then reinstall it then it will not open that code.

For i want to create registry which create at installtion and delete at uninstallation, but till now i am not able to identify "Uninstallation event" i.e. how can i identify that uninstallation is processing.


Villa, please reply me as soon as possible.

Thanks
Nehal Pandya.
 
Hi
I implemented this code and it's working great, Thanks for the tip, that great one.

Now my question is, I want to add directing the user to thankyou page after the addon is installed, the first time. The problem is that all the code executes fine beside the redirect line
window._content.document.location = url;

any help is welcome
Thanks

Elad
 
You probably want to do something like window.openUILink(url). See if that works for you. Also, you probably need to use setTimeout so that this code runs *after* the window and tabs have fully loaded.
 
the setTimeout did it :)
Thanks very much!!
 
Post a Comment



<< Home

This page is powered by Blogger. Isn't yours?