The loadOverlay Dilemma

Jonathan Fingland — Wed, 25 Mar 2009 04:51:41 +0000

When making Firefox extensions with modular components, it’s nice to be able to include overlays based on preferences or some other criteria at loadtime. One of the problems that quickly comes up is that sequential loadOverlay calls will fail. This bug is documented here. The solution described there, and elsewhere, is to use chained observers and a custom queue. Strangely, I never came across an implementation example of such an observer/queue combination. So… with that stunning introduction, I give you the system used in PirateQuesting 2.

The first part here is an overlay registry. Essentially, the queue portion of the solution.

piratequesting.overlayRegistry = function() {
	var overlays = [];
	var index = 0;

	function conflicts(tabid, tabpanelid, overlayFile) {
		for (var i = 0, len = overlays.length; i
Now, that is a somewhat specialized case. The tabid and tabpanelid are arguably unnecessary but have been included to prevent two modules having the same tab ids, and, more importantly, to be able to refer to the overlay by a known value, in this case the tabid.
A somewhat stripped down version might look like:
var overlayRegistry = function() {
	var overlays = [];
	var index = 0;

	function conflicts(overlayFile) {
		for (var i = 0, len = overlays.length; i
The overlay registry is simply an iterator-style queue. This makes walking through the items very easy for the observer (shown next) which doesn’t (and shouldn’t) really have any idea of the state of the queue. The queue, overlayRegistry, makes a number of methods available for getting basic info about the queue (size, progress, etc) for use in progress bars or the like. It also provides ways of resetting the queue. Obviously, since it’s designed to be an iterator, there are ways of getting the next item and advancing the queue. 
The second part of the solution is using a chained observer. Again, the piratequesting implementation is:
function overlayObserver()
{
  this.register();
}
overlayObserver.prototype = {
  observe: function(subject, topic, data) {

  	function cleanUp() {
		sidebar.contentDocument.getElementById("pqmain_deck").selectedIndex="1";

		var mod_boxes = sidebar.contentDocument.getElementsByTagName("tabbox");
		for (var i=0,len=mod_boxes.length;i
And a stripped down version would look something like this: 
function overlayObserver()
{
  this.register();
}
overlayObserver.prototype = {
  observe: function(subject, topic, data) {

  	if (topic == "xul-overlay-merged") {
		try {
			var nex = overlayRegistry.next();
			if (nex) {
  				try {
  					document.loadOverlay(nex.getOverlayFile(),this);
	  			} catch (error) {
  					dump("Failed to load: " + nex.getOverlayFile() + "\nReported Error " + getErrorString(error));
	  			}
  			} else {
  				cleanUp();
	  		}
  		} catch (error) { alert(getErrorString(error)); }
  	}
  },
  register: function() {
    var observerService = Components.classes["@mozilla.org/observer-service;1"]
                          .getService(Components.interfaces.nsIObserverService);
    observerService.addObserver(this, "xul-overlay-merged", false);
  },
  unregister: function() {
    var observerService = Components.classes["@mozilla.org/observer-service;1"]
                            .getService(Components.interfaces.nsIObserverService);
    observerService.removeObserver(this, "xul-overlay-merged");
  }
}

This observer chain is started with:
overlayObserver.observe(null,"xul-overlay-merged", null);

The observer code is also fairly simple but relies on some things that were not terribly well documented. The key thing to know about loadOverlay is that it raises an xul-overlay-merged observer notification. here, but you’ll notice what’s missing. This entry, however, has that piece of info. If you’ve never used observers before, this gives a good rundown.
Sooo…. What happens? how does it work? Basically, at some point during the initialization of the sidebar (not important in this discussion), the observer chain is started and will loop as follows:

receive notification of the last loadOverlay finishing
get the next item in the iterator
if the “next item” is null, stop
load the overlay file specified by said item

And you’re done. One Note I would make is that if there are multiple extensions making use of this at the same time, you’re very likely to have problems when both extensions receive the notifications and both start loading their next items. As firefox still lacks a built-in queue for overlay loading, we’re stuck hoping that nobody else will use this at the same time.
Note: You may notice that a lot of the piratequesting code makes use of a function getErrorString(). This is a very siple function that puts all of the error info I want into a string. dump() is a function available in firefox for dumping text to the console. I am also currently working on an error logging system and will cover all of these issues in more detail when that is finished. For the time being, ignore how I handle the errors but for obvious reasons, you will want to have some kind of error handling in place.
Edit 2009/04/04:

It has since occurred to me that by using additional information, that is, subject, from the observer notification, I can reduce the chances of conflict by ensuring it only fires on the completion of it’s own loadOverlay calls.

Passing parameters into a created dialog, and retrieving them on exit

Jonathan Fingland — Sun, 26 Oct 2008 07:50:05 +0000

This is going to be a pretty short tutorial today to help explain how to pass information to an window when opening it. The following is taken from PirateQuesting.

First, here is the function for entering the code when PirateQuest asks the user for verification.

function enterCode(url,imgsrc, func) {
	var params = {in:imgsrc, out:null};
	window.openDialog("chrome://piratequesting/content/codeDialog.xul", "",
		"chrome, dialog, modal, resizable=no, status=no,
		height=250, width=400", params).focus();
	if (params.out) {
		piratequesting.Code.submit(url,params.out,imgsrc,func);
	}
	else {
	    // User clicked cancel. stop here
	}
}

So, as we can see in the first line the params variable stores a hash. A has is useful here as it allows us to easily pass more than one variable in without goign to the work of creating an object. There are actually much more significant differences between a hash and an object but, for this tutorial, know that it stores values in name:value pairs separated by commas and all of it enclosed by curly braces. The last element must not be followed by a comma.

Next, when we use openDialog we pass params into the dialog.

After the user has clicked OK, the value of params.out is checked. The condition will be true unless the value is still null or by some strange miracle taken on a value like ‘false’.

Now, let’s look at the code behind the dialog itself

function codeDialogOnLoad() {

    // Use the arguments passed to us by the caller
    document.getElementById("codeImage").setAttribute('src',
            window.arguments[0].in);
}

// Called once if and only if the user clicks OK
function onOK() {
    window.arguments[0].out = document.getElementById("codeValue").value;
    return true;
}

Ok, so what do we have here? well, when the dialog first loads we call codeDialogOnLoad which then sets the image source on the dialog based on the value passed in params.in. Note that it is now referred to as window.arguments[0].in.

When the user presses OK, the value of an input box, codeValue, is assigned to params.out (a.k.a. window.arguments[0].out).

Last thing to look at is the codeDialog.xul

Ashita.org » XUL

The loadOverlay Dilemma

Passing parameters into a created dialog, and retrieving them on exit