?Includes and Overlays
Includes are a Pentaho extension to the XUL specification that allow a more traditional way of breaking up a XUL document. Using Pentaho includes, the included context is completely unaware of the context it's being included into. This is perfect for shared components such as a common publishing dialog that are used across multiple applications. The simplest form of an include requires only the classpath to the include file:
Note the "<pen:.." prefix on the include tag. This tells the parser that include is a Pentaho only element.
The code above will include the contents of myInclude.xul just below the window element. There are times when you may want to separate out content into an include, but doing so will result in invalid XML. For instance, if you remove the content from the tabpanel below and put it in an include file, it will lack a root element:
To solve this problem you have to wrap the button and label in a dummy root within the include file, then in the include declaration add the attribute ignoreroot="true". In the example below, this will skip the window element in the include and place the button and label in the tabpanel:
== Event handling with include files ==
You may end up including entire separate applications as dialogs in your XUL application. These are bound to have event handlers and onload declarations in their root elements, but you never have to worry about it because the XUL parser will bring in all event handler declarations and combine onload attributes.
== Internationalization ==
By default, the parser will look for a resource bundle with the base name of your include document. In the example above, org/class/path/to/myInclude.properties is the default property file of org/class/path/to/myInclude. If it fails to find that message bundle, it will then try the main application bundle.
You can alternately supply a different resource bundle base name to the parser by adding a resource attribute to the include declaration:
== Overlays ==
Up to this point, the include examples have encompassed all of the context of the include file, perhaps skipping over the root element. While this will suit the majority of your needs, you may want to tailor the include to fit your particular application by removing or adding elements. You can accomplish this by combining includes with overlays, which are dependent on knowing the structure of your main XUL file in order to "match-up" or "overlay" themselves into the XUL document. The syntax is simple:
<overlay src="includeOverlay.xul" />
For more information, consult the Mozilla documentation