If you're new here, you may want to subscribe to my RSS feed. So that you can read the latest updates about Web2.0 tools, Making Money Online, Tips in SEO, Ajax and many more. Thanks for visiting ProgramimiCOM!

Overlays are an important aspect of XUL, but this is a subject that I’ve barely mentioned in previous articles. Overlays can be used for a variety of purposes when designing/writing XUL applications and come in either explicit or dynamic flavors. Explicit overlays are used within your own application and form the basis of code modularization.If you are creating a large application with several windows, local overlays can be used to share common elements between the various windows; if for example you have two windows in your application and both of them have a file menu, rather than having the file menu code in both of the windows, you can define an overlay and then share this one file between both windows. This centralizes the code for the file menu and makes updating/extending the menu much easier because code changes are only required in one place. The Mozilla suite of applications makes extensive use of overlays for this very purpose, with all of the main applications in the suite sharing many of their menus and functionality.

When creating XUL applications, remember that if you need a file menu in your application, you can easily make use of the Mozilla overlay for this feature and cut down massively on the amount of coding you need to do (I’ve avoided this in previous tutorials as it is counter-productive to the learning process when getting to know and understand XUL).

Dynamic overlays work in a subtly different way and can be used to add additional content to an existing application at runtime.  If you write an application designed to run as an add-on to the navigator part of the Mozilla suite, you are going to want to perhaps add a menu item to launch it or control it, and to do this without having to modify the Mozilla source files you use a dynamic overlay to add the additional content at run-time.

The main files of a XUL application are known as the base files; the master, or default, skin is called the base skin and shares the same name as the base XUL file.  In the application developed in earlier XUL tutorials the base XUL file is called interface.xul and the base skin file is called interface.css for example.  Overlay files should share the name of the application they are used with, with Overlay at the end: interfaceOverlay.xul for example, would be appropriate.

You can use any element within an overlay, and when the overlay is processed the children of the overlay element become the children of the element the overlay targets.  By default these children are placed below the children of the targeted element, so in a dynamic overlay an additional menu item would appear after the existing items in the targeted menu, although this can be changed with the use of attributes to specify where in the element tree the overlaid children appear.

Overlays in XUL - Creating an overlay

Creating overlays is easy; you still need the XML declaration and the XUL namespace is added as an attribute of an <overlay> element instead of a <window> element.  Elements within the overlay file should have an ID attribute which is used to match the overlaid content with the main application.  Create a XUL file that contains the following code:

<?xml version=”1.0″?>
<overlay xmlns=”http://www.mozilla.org/keymaster/gatekeeper/
there.is.only.xul”>
<menu id=”overlaidMenu”>
<menupopup id=”newPopup”>
<menuitem id=”menuitem1″ label=”New item 1″/>
<menuitem id=”menuitem1″ label=”New item 2″/>
<menuitem id=”menuitem1″ label=”New item 3″/>
<menuitem id=”menuitem1″ label=”New item 4″/>
</menupopup>
</menu>
</overlay>

Now save this file into the content folder of your application with a filename of newmenuOverlay.xul.  Next, we need to import the overlay content into the main XUL file of the application; in this case, I am using the XUL editor created in previous articles as an example.  Near the top of the file, add the following processing instruction:

<?xul-overlay
href=”chrome://interface/content/newmenuOverlay.xul”?>

Finally, in the location that you would like the new menu to appear, add this code:

<menu id=”overlaidMenu” label=”New Menu”/>

As you can see, the ID of the element in both the overlay file itself, and the final line of code in the main application file are the same.  Notice also that the overlay file is understood and processed by Mozilla using a chrome URL, even though we haven’t registered the overlay with the chrome in the same way that we have had to register some of the other key elements of the application such as the DTD and skin files.  The chrome is intelligent enough to pick these up without special instructions.

Overlays in XUL - Adjusting the overlay to your application
If you use a locale with your application and read in things like menuitem labels, you should do the same with any overlays, so in this example, I should change the menu code within the overlay file to something like:

<menuitem id=”menuitem1″ label=”&newlabel1;”/>
<menuitem id=”menuitem1″ label=”&newlabel2;”/>
<menuitem id=”menuitem1″ label=”&newlabel3;”/>
<menuitem id=”menuitem1″ label=”&newlabel4;”/>

Then create a new DTD file with the code:

<!ENTITY newlabel1 “New item 1″>
<!ENTITY newlabel2 “New item 2″>
<!ENTITY newlabel3 “New item 3″>
<!ENTITY newlabel4 “New item 4″>

This DTD file should be saved with the name newmenuOverlay.dtd to match the overlay file and should be saved in your existing locale directory.  This way, you won’t have to register the new DTD file with the chrome either; although before it can be used, you’ll need to add the following DOCTYPE declaration to your newmenuOverlay.xul file:

<!DOCTYPE overlay SYSTEM
“chrome://interface/locale/newmenuOverlay.dtd”>

So now, any window that needs to contain this menu can simply have the statement that imports the overlay, and an ID matched menu element (or whatever element is being overlaid), and it can make use of the overlay file.  This is also the same means by which files can be taken from Mozilla itself to cut down on the amount of coding that is required.  You know that Mozilla is going to be installed on the end users system in order for XUL to work, so when creating XUL applications for deployment, you can rely on being able to borrow elements like these from Mozilla.

Overlays can also overlay other overlay files as well as JavaScript or CSS files, so when using Mozilla content in your own applications not only can you overlay the elements used to build the desired menus, you can also use overlays to import the functionality which can cut down massively on the amount of coding you need to do, especially when it comes to some of the complicated XPCOM interfaces that are required in order to build things like the file open/save functionality that is often required in applications.

Overlays in XUL - Creating a dynamic overlay

Creating dynamic overlays is very similar to creating explicit overlays; although this time the overlays do need to be registered fully with the chrome in order to instruct Mozilla to apply the overlay files to the target application. With this method, the source file of the application that has the overlay applied to it doesn’t need to be modified.  This makes it an excellent method of creating updates or add-ons to an application that are fully packaged and made available for distribution or download.  It also means that you can create add-on components to Mozilla itself without modifying Mozilla’s source code.

You could add a menuitem to one of Mozilla’s menus in this way so that an application you’ve written can be accessed easily.  To do this, you first create the main overlay file, like you would any other overlay by starting with the XML declaration and the overlay container:

<?xml version=”1.0″?>
<overlay id=”xuleditOverlay” xmlns=”http://www.mozilla.org/keymaster/gatekeeper/
there.is.only.xul”>

As the menuitem is to be used to open your application, you’ll need a little bit of JavaScript to do this.  Normally this would go into its own JS file, but as it’s just the one little function, there’s no harm in adding it in here:

<script type=”application/x-javascript”>
function openXulEdit() {
window.openDialog(’chrome://interface/content/’, ‘_blank’,
‘chrome,dialog=no’);
}
</script>

This simple little script calls the openDialog method and takes, most importantly, the relevant chrome URL and two additional parameters.

All you need now is the new menuitem that you want added to Mozilla and the closing tag:

<menupopup id=”windowPopup”>
<menuitem label=”XUL Edit Lite 1.0″ oncommand=”openXulEdit
();” insertbefore=”sep-window-list”/>
</menupopup>
</overlay>

The menupopup ID must match that of the menupopup in Mozilla that you want to influence, in this case, the Window menu.  The oncommand attribute calls our little JavaScript snippet and the insertbefore attribute tells Mozilla to add the new menuitem right before the separator (take a look at the Window menu in Mozilla to see the separator I mean).  Save this file as xuleditOverlay.xul in your main content directory.  Next, you need to add a couple of lines of code to your existing main contents.rdf file:

<RDF:Seq about=”urn:mozilla:overlays”>
<RDF:li resource=”chrome://communicator/content/tasksOverlay.xul”/>
</RDF:Seq>
<RDF:Seq about=”chrome://communicator/content/tasksOverlay.xul”>
<RDF:li>chrome://interface/content/xuleditOverlay.xul</RDF:li>
</RDF:Seq>

The first code block lists the file that you are going to overlay, the second lists the file to be used as the overlay.  Add these just before the closing </RDF:RDF> tag.

Finally, you need to browse to the Mozilla Chrome directory and delete the folder called “overlayinfo.”  This directory will be recreated when Mozilla is next launched, so launch Mozilla and go into the overlayinfo directory.  There will be several folders in here depending on which Mozilla suite components are installed; if you go into the one called communicator, then into the content folder, you’ll find an overlays.rdf file.  Open this file in a text editor and if everything worked, there will be an Li statement that matches the one you just added to your applications contents.rdf file. One final check that it has worked of course is to open the Window menu in Mozilla to check that your overlaid menuitem appears and that it launches your application when selected.

In addition to adding content to Mozilla without altering the base files of the applications, this is the same mechanism that you can use to release additional or add-on content to your own XUL applications once they have been distributed.  You could simply create a new XUL module for your application and then package it in an installer that adds the required files and the new contents.rdf file to the existing directory structure.

So as you can see, overlays are an important aspect of XUL that can be used to add modularity to the bigger applications you create or add to the functionality of either Mozilla itself, or applications that you write.