Hitachi Vantara Pentaho Community Wiki
Child pages
  • 07. Includes and Overlays
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

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="" xmlns:pen="">
<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="[]"><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/ 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" />


For more information, consult the Mozilla documentation

  • No labels