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:

<pen:include src="org/class/path/to/myInclude.xul" />

Note the <pen:... prefix on the include tag. This tells the parser that include is a Pentaho only element.

<window xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul" xmlns:pen="http://www.pentaho.org/2008/xul">
    <pen:include src="org/class/path/to/myInclude.xul"/>
    ...
</window>

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:

<tabbox>
    <tabs><tab label="test tab"/></tabs>
    <tabpanels>
        <tabpanel>
            <!-- content to remove to include -->
            <button label="test button"/>
            <label value="test label"/>
            <!-- end content to include -->
        </tabpanel>
    </tabpanels>
</tabbox>

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:

...
<tabbox>
    <tabs><tab label="test tab"/></tabs>
    <tabpanels>
        <tabpanel>
            <pen:include src="org/class/path/to/myInclude.xul" ignoreroot="true" />
        </tabpanel>
    </tabpanels>
</tabbox>
...

<window id="dummyRootElement" xmlns="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul">
    <button label="test button"/>
    <label value="test label"/>
</window>

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:

<pen:include src="org/class/path/to/myInclude.xul" resource="com/path/to/resourcebunlde" />

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:

<pen:include src="org/pathto/include.xul">
    <overlay src="includeOverlay.xul" />
</pen:include>

More information on overlays

Though this is not official documentation on XUL overlays, it's among the best on the Web: http://mb.eschew.org/12.

Mozilla's official documentation is less detailed: http://developer.mozilla.org/en/docs/XUL_Tutorial:Overlays.

With regard to overlays, the only syntactical difference between the Pentaho XUL implementation and the Mozilla XUL 1.0 specification is in the declaration of the usage of an overlay. The standard is to use an XML processing directive at the top of the XUL document:

<?xul-overlay href="chrome://findfile/content/helpoverlay.xul"?>

Unfortunately, Pentaho's implementation can't support this right now. To apply an overlay to your XUL document, employ the same syntax used for includes:

<pen:include src="overlay.xul"/>

You can also apply an overlay to a include which is useful in tailoring a reused component for your particular application:

<pen:include src="include.xul">
   <overlay src="overlay.xul" />
</pen:include>

All overlay attributes are now supported from the Mozilla specification: removeelement, insertbefore, insertafter, position. These allow you to tailor how you want your overlayed elements to appear in the application.

Finally, you can also add and remove overlays at runtime via the "document" object in your event handlers:

document.addOverlay("classpath/to/overlay.xul");

document.removeOverlay("classpath/to/overlay.xul");

Removing of overlays is only supported for "addition" overlays. In other words, if your overlay removes content via the removeelement="true" attribute, it cannot be reversed at this time.