Templates"

From Documentation
m
m
 
(5 intermediate revisions by one other user not shown)
Line 3: Line 3:
 
As described in [[ZK Developer's Reference/MVC/View/Template|the MVC: Template section]], a template is a ZUML fragment that defines how to create components. A template is enclosed with [[ZUML Reference/ZUML/Elements/template|the template element]] as shown below.
 
As described in [[ZK Developer's Reference/MVC/View/Template|the MVC: Template section]], a template is a ZUML fragment that defines how to create components. A template is enclosed with [[ZUML Reference/ZUML/Elements/template|the template element]] as shown below.
  
<source lang="xml" high="2,6">
+
<source lang="xml" highlight="2,6">
 
<window>
 
<window>
 
     <template name="foo">
 
     <template name="foo">
Line 21: Line 21:
 
"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.
 
"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 it by invoking the <javadoc method="getTemplate(java.lang.String)">org.zkoss.zk.ui.Component</javadoc>. To create the components defined in the template, just invoke the <javadoc method="create(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component, org.zkoss.xel.VariableResolver, org.zkoss.zk.ui.util.Composer)">org.zkoss.zk.ui.util.Template</javadoc>. For example,
+
Each template is stored as part of a component and can be retrieved by invoking the <javadoc method="getTemplate(java.lang.String)">org.zkoss.zk.ui.Component</javadoc>. To create the components defined in the template, just invoke the <javadoc method="create(org.zkoss.zk.ui.Component, org.zkoss.zk.ui.Component, org.zkoss.xel.VariableResolver, org.zkoss.zk.ui.util.Composer)">org.zkoss.zk.ui.util.Template</javadoc>. For example,
  
 
<source lang="java">
 
<source lang="java">
Line 50: Line 50:
 
</source>
 
</source>
  
In addition, the template allow users to specify any number of parameters with any name, and these parameters can be retrieved back by the <tt>getParameters</tt> method of the <tt>Template</tt> interface:
+
In addition, the template allows users to specify any number of parameters with any name, and these parameters can be retrieved back by the <code>getParameters</code> method of the <code>Template</code> interface:
  
 
<source lang="xml">
 
<source lang="xml">
Line 58: Line 58:
 
</source>
 
</source>
  
If the content of a template is located elsewhere as a separated file, to reference it, specify it in the <tt>src</tt> attribute as follows.
+
If the content of a template is located elsewhere as a separate file, to reference it, specify it in the <code>src</code> attribute as follows.
  
 
<source lang="xml">
 
<source lang="xml">
Line 67: Line 67:
  
 
= Children Binding =
 
= Children Binding =
 +
{{versionSince |8.0}} We suggest using shadow component [http://books.zkoss.org/zk-mvvm-book/8.0/shadow_elements/iterate_collections.html <code><forEach></code>] as a replacement of children binding.
 +
 
[[ZK Developer's Reference/MVVM/Data Binding| ZK Data Binding]] provides a powerful way called [[ZK Developer's Reference/MVVM/Data Binding/Children Binding|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 [[ZK Developer's Reference/MVVM/Data Binding/Children Binding|the Children Binding section]].
 
[[ZK Developer's Reference/MVVM/Data Binding| ZK Data Binding]] provides a powerful way called [[ZK Developer's Reference/MVVM/Data Binding/Children Binding|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 [[ZK Developer's Reference/MVVM/Data Binding/Children Binding|the Children Binding section]].
  
 
=Version History=
 
=Version History=
{{LastUpdated}}
+
 
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-

Latest revision as of 08:29, 31 January 2024

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 Component.getTemplate(String). To create the components defined in the template, just invoke the Template.create(Component, Component, VariableResolver, Composer). For example,

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

The third argument of the create method is a variable resolver (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

Since 8.0 We suggest using shadow component <forEach> 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.



Last Update : 2024/01/31

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.