Templates

As described in the MVC: Template section, a template is a ZUML fragment that defines how to create components. A template is enclosed with the template element as shown below.

<window>
    <template name="foo">
      <textbox/>
      <grid model=${data}>
         <columns/>
         <template name="model"> <!-- nested template -->
            <row>Name: <textbox value=${each.name}"/></row>
         </template>
      </grid>
   </template>
...

Using Template in Application

“Template” is a generic feature and its use is not limited to custom model rendering. Users are able to use “template” in ZK applications too.

Each template is stored as part of a component and can be retrieved by invoking the org.zkoss.zk.ui.Component#getTemplate(java.lang.String). To create the components defined in the template, just invoke the org.zkoss.zk.ui.util.Template#create(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component, org.zkoss.xel.VariableResolver, org.zkoss.zk.ui.util.Composer). For example,

comp.getTemplate("foo").create(comp, null, null, null);

The third argument of the create method is a variable resolver (org.zkoss.xel.VariableResolver). Depending on the requirement, you could pass any implementation you like. For example, the implementation of a listbox actually utilizes it to return the data being rendered; the code is similar to the following (for easy understanding, the code has been simplified).

For more detailed information about the variable resolver, please refer to ZUML Reference.

public class TemplateBasedRenderer implements ListitemRenderer {
    public void render(Listitem item, final Object data, int index) {
        final Listbox listbox = (Listbox)item.getParent();
        final Component[] items = listbox.getTemplate("model").create(listbox, item,
            new VariableResolver() {
                public Object resolveVariable(String name) {
                    return "each".equals(name) ? data: null;
                }
            }, null);

        final Listitem nli = (Listitem)items[0];
        if (nli.getValue() == null) //template might set it
            nli.setValue(data);
        item.detach();
    }
}

In addition, the template allows users to specify any number of parameters with any name, and these parameters can be retrieved back by the getParameters method of the Template interface:

<template name="foo" var1="value1" var2="${el2}">
...
</template>

If the content of a template is located elsewhere as a separate file, to reference it, specify it in the src attribute as follows.

<template name="foo" src="foo.zul">
...
</template>

Children Binding

We suggest using shadow component [](http://books.zkoss.org/zk-mvvm-book/8.0/shadow_elements/iterate_collections.html) as a replacement of children binding.

ZK Data Binding provides a powerful way called Children Binding to render a template based on the data (such as a list of elements). Moreover, the UI will be updated automatically if the data has been changed. For more information, please refer to the Children Binding section.

Version History

Version	Date	Content
6.0.0	July 2011	The template feature was introduced.