ZK Developer's Reference/UI Patterns/Templating/Composition

Composition is one of the built-in templating implementations. The concept is simple:

1. Define a template (a ZUML document representing a complete UI)
2. Define a ZUML document that contains a collections of fragments that a template might references

Notice that the user shall visit the ZUML document with a collection of fragments rather than the template document.

The advantage of Composition is that you don't need additional configuration file.

Defines a Template

A template document is a ZUML document that defines how to assemble the fragments. For example,

<!-- /WEB-INF/layout/template.zul -->
<vbox>
  <hbox self="@{insert(content)}"/>
  <hbox self="@{insert(detail)}"/>
</vbox>

As shown, the anchor (i.e., the component that a fragment will insert as children) is defined by specify an annotation as @{insert(name)}. Then, when Composition is applied to a ZUML document with a collections of fragments, the matched fragment will become the child of the annotated component (such as hbox in the above example).

Define Fragments

To apply a template to a ZUML document that an user visits, you have to defined a collection of fragments that a template might use, and then specify Composition as one of the initiators of the document:

<!-- foo/index.zul -->
<?init class="org.zkoss.zk.ui.util.Composition"
arg0="/WEB-INF/layout/template.zul"?>
<zk>
  <window self="@{define(content)}" title="window1" width="100px"/>
  <window self="@{define(content)}" title="window2" width="200px"/>
  <grid self="@{define(detail)}" width="300px"/>
</zk>

As shown, a fragment is defined by specify an annotation as self="@{define(name)}. Furthermore, the template is specified in the init directive.

Then, when the user visits this page (foo/index.zul in the above example), Composition will do:

1. Load the template, and render it as the root components of this page(foo/index.zul)
2. Move the fragments specified in this page to become the children of the anchor component with the same annotation name

Thus, here is the result

<vbox>
  <hbox>
    <window title="window1" width="100px"/>
    <window title="window2" width="200px"/>
  </hbox>
  <hbox>
    <grid/>
  </hbox>
</vbox>

Multiple Templates

You could apply multiple templates to a single page too:

<?init class="org.zkoss.zk.ui.util.Composition"
arg0="/WEB-INF/layout/template0.zul" arg1="/WEB-INF/layout/template1.zul"?>

The templates specified in arg0 and arg1 (etc.) will be loaded and rendered one-by-one.

Version History

Version	Date	Content