XUL Programmer's Reference Manual

<overlay>

Attributes Common Children
id menubar
xmlns menu
  toolbar
  toolbox
  box
   

<overlay> is the root element of a separate file that contains XUL subtrees which can be interpolated into a XUL interface. The id attribute of the subtree in the overlay and of the target element in the base XUL file is the means of identifying where in the XUL the overlayed elements are to be placed. In all cases, the id attribute of the skeletal element in the base file and of the subtree meant to replace it from the overlay are identical, as in the following example, where the subtree on the right in loaded into the XUL menubar on the left and runtime.

Base XUL File Menu Overlay
...
<menubar id="main-menu">
  <menu value="File">
        <menupopup>
          <menuitem value="New" />
          <menuitem value="Open" />
          ...           
        </menupopup>
  </menu>
  <menu value="Edit">
        <menupopup>
          ....          
        </menupopup>
  </menu>
 <menu id="extra-menu" />
</menubar>
...

<overlay  
  xmlns:html="http://www.w3.org/1999/xhtml"
  xmlns="http://www.mozilla.org/keymaster/
    gatekeeper/there.is.only.xul" >
<menu id="extra-menu" value="Extras"> 
 <menupopup> 
   <menuitem value="Whiz" /> 
   <menuitem value="Bang" /> 
   <menuseparator/> 
   <menuitem value="Super" /> 
   <menuitem value="Duper"/> 
  </menupopup> 
</menu>
</overlay>

The overlay example on the right is an entire file; the XUL on the right is a portion of the "base" file onto which the "extra-menu" subtree is overlayed. Any number of subtrees can be defined within a single overlay file. By convention, XUL overlays are named so that their role as overlays rather than base files is obvious.

Note that it is the id of the subtree and not the overlay that determines where in the base XUL the overlay will be. The id of the overlay itself is optional. When the XUL file on the left in the example above is loaded, it in turn loads the overlay on the right. The resulting menu looks as follows:

For more information on overlays, see the XPToolkit Overlays Document.
 

Last updated: 3/2/00 Ian Oeschger