Listbox Template"

From Documentation
m ((via JWB))
(9 intermediate revisions by 4 users not shown)
Line 5: Line 5:
 
The template used to control the rendering of each item must be named <code>model</code> and declared right inside the <code>listbox</code> element. For example,
 
The template used to control the rendering of each item must be named <code>model</code> and declared right inside the <code>listbox</code> element. For example,
  
<source lang="xml" high="6,7,8,9,10,11">
+
<source lang="xml" highlight="7,8,9,10,11,12">
<listbox model="${$composer.fruits}" apply="foo.FruitProvider">
+
<div apply="foo.FruitProvider">
 +
    <listbox model="${$composer.fruits}">
 
<listhead>
 
<listhead>
 
<listheader label="Name" sort="auto"/>
 
<listheader label="Name" sort="auto"/>
Line 17: Line 18:
 
</listitem>
 
</listitem>
 
</template>
 
</template>
</listbox>
+
    </listbox>
 +
</div>
 
</source>
 
</source>
  
Line 28: Line 30:
 
<source lang="java">
 
<source lang="java">
 
public class FruitProvider extends org.zkoss.zk.ui.select.SelectorComposer {
 
public class FruitProvider extends org.zkoss.zk.ui.select.SelectorComposer {
     public String[][] fruits = new ListModelArray(
+
     public ListModelArray fruits = new ListModelArray(
 
             new String[][] {
 
             new String[][] {
 
                 {"Apple", "10kg"},
 
                 {"Apple", "10kg"},
Line 35: Line 37:
 
             });
 
             });
  
     public String[][] getFruits() {
+
     public ListModelArray getFruits() {
 
         return fruits;
 
         return fruits;
 
     }
 
     }
Line 60: Line 62:
 
When using the template, it is important to remember that the template is rendered on demand. It means the template can be rendered very late, after the page is rendered, after the user scrolls down to make an item visible, and so on. Thus, in the template, you ''cannot'' reference anything that is available only in the page rendering phase. For example, you can't reference [[ZUML Reference/EL Expressions/Implicit Objects/arg|the arg variable]] in a template:
 
When using the template, it is important to remember that the template is rendered on demand. It means the template can be rendered very late, after the page is rendered, after the user scrolls down to make an item visible, and so on. Thus, in the template, you ''cannot'' reference anything that is available only in the page rendering phase. For example, you can't reference [[ZUML Reference/EL Expressions/Implicit Objects/arg|the arg variable]] in a template:
  
<source lang="xml" high="4">
+
<source lang="xml" highlight="4">
 
<listbox model="${$composer.fruits}" apply="foo.FruitProvider">
 
<listbox model="${$composer.fruits}" apply="foo.FruitProvider">
 
     <template name="model">
 
     <template name="model">
Line 73: Line 75:
 
To work around, you have to store the value in, say, component's custom attributes (<javadoc method="getAttributes()" type="interface">org.zkoss.zul.Component</javadoc>. For example,
 
To work around, you have to store the value in, say, component's custom attributes (<javadoc method="getAttributes()" type="interface">org.zkoss.zul.Component</javadoc>. For example,
  
<source lang="xml" high="2,5">
+
<source lang="xml" highlight="2,5">
 
<listbox model="${$composer.fruits}" apply="foo.FruitProvider">
 
<listbox model="${$composer.fruits}" apply="foo.FruitProvider">
 
     <custom-attributes foo="${arg.foo}"/><!-- store it for later use -->
 
     <custom-attributes foo="${arg.foo}"/><!-- store it for later use -->
Line 88: Line 90:
 
The template can be applied recursively. Here is an example of a listbox-in-listbox:
 
The template can be applied recursively. Here is an example of a listbox-in-listbox:
  
<source lang="xml" high="12, 17">
+
<source lang="xml" highlight="12, 17">
 
<zk>
 
<zk>
 
<zscript><![CDATA[
 
<zscript><![CDATA[
Line 126: Line 128:
 
Here is an example of traversing the component tree to retrieve the data in the outer template, as shown at line 9 below. Notice that, each data is, as described before, stored in the component's value property.
 
Here is an example of traversing the component tree to retrieve the data in the outer template, as shown at line 9 below. Notice that, each data is, as described before, stored in the component's value property.
  
<source lang="xml" high="9">
+
<source lang="xml" highlight="9">
 
<listbox model="${quarters}">
 
<listbox model="${quarters}">
 
<template name="model">
 
<template name="model">
Line 148: Line 150:
 
If the component tree is deep, It is tedious and somehow error prone. Alternatively, you can store the information into [[ZUML Reference/ZUML/Elements/custom-attributes|a custom attribute]] and then retrieve it later, as shown at line 4 and 10 below.
 
If the component tree is deep, It is tedious and somehow error prone. Alternatively, you can store the information into [[ZUML Reference/ZUML/Elements/custom-attributes|a custom attribute]] and then retrieve it later, as shown at line 4 and 10 below.
  
<source lang="xml" high="4,10">
+
<source lang="xml" highlight="4,10">
 
<listbox model="${quarters}">
 
<listbox model="${quarters}">
 
<template name="model">
 
<template name="model">
Line 176: Line 178:
 
=Template for GroupsModel=
 
=Template for GroupsModel=
  
When used with <javadoc type="interface">org.zkoss.zul.GroupsModel</javadoc>, listboxes will use the template called <tt>model:group</tt> for rendering the grouping object. If it is not defined, it will look for the template called <tt>model</tt> instead (i.e., the same template is used for rendering the grouping and non-grouping objects).
+
When used with <javadoc type="interface">org.zkoss.zul.GroupsModel</javadoc>, listboxes will use the template called <code>model:group</code> for rendering the grouping object. If it is not defined, it will look for the template called <code>model</code> instead (i.e., the same template is used for rendering the grouping and non-grouping objects).
  
 
<source lang="xml">
 
<source lang="xml">
<listbox mode="${fooGroupsModel}">
+
<listbox model="${fooGroupsModel}">
 
   <template name="model:group">
 
   <template name="model:group">
 
       <listgroup open="${groupingInfo.open}" label="${each}"/>
 
       <listgroup open="${groupingInfo.open}" label="${each}"/>
Line 195: Line 197:
  
 
=Version History=
 
=Version History=
{{LastUpdated}}
+
 
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-

Revision as of 07:34, 8 July 2022

The template used to control the rendering of each item must be named model and declared right inside the listbox element. For example,

<div apply="foo.FruitProvider">
    <listbox model="${$composer.fruits}">
	<listhead>
		<listheader label="Name" sort="auto"/>
		<listheader label="Weight" sort="auto"/>
	</listhead>
	<template name="model">
		<listitem>
			<listcell label="${each[0]}"/>
			<listcell label="${each[1]}"/>
		</listitem>
	</template>
    </listbox>
</div>

The template's name is important because users are allowed to associate multiple templates to one component, and listbox's default renderer looks only for the template called model.

When the template is rendered, a variable called each is assigned with the data being rendered. Thus, you could retrieve the information to render with EL expressions, such as ${each[0]}, if it is an array, or ${each.name}, if it is a bean with a getter called name.

In this example, we assume the $composer.fruits expression returns a two-dimensional array[1], and is provided by the foo.FruitProvider composer such as follows[2].

public class FruitProvider extends org.zkoss.zk.ui.select.SelectorComposer {
    public ListModelArray fruits = new ListModelArray(
            new String[][] {
                {"Apple", "10kg"},
                {"Orange", "20kg"},
                {"Mango", "12kg"}
            });

    public ListModelArray getFruits() {
         return fruits;
    }
}

St201107-listbox.png


  1. Of course, it can be anything you like. Just make sure it matches the EL expressions specified in the template.
  2. Here we use SelectorComposer for simplicity. There are several ways to implement a composer, such as wiring a Spring-managed bean. For more information, please refer to the Composer section

Component's Value

By default, the data used to render a component will be stored to the component's value property automatically. For listitem, it is Listitem.setValue(T). Thus, you retrieve it back easily by invoking Listitem.getValue().

Of course, if you prefer to store other values, you can simply specify value="${whatever}" to the listitem element in the template.

The forEachStatus Variable

There is a variable called forEachStatus providing the information of the iteration. It is an instance of ForEachStatus. For example, you could retrieve the iteration's index by use of ${forEachStatus.index}.

Lifecycle and the arg Variable

When using the template, it is important to remember that the template is rendered on demand. It means the template can be rendered very late, after the page is rendered, after the user scrolls down to make an item visible, and so on. Thus, in the template, you cannot reference anything that is available only in the page rendering phase. For example, you can't reference the arg variable in a template:

<listbox model="${$composer.fruits}" apply="foo.FruitProvider">
    <template name="model">
        <listitem>
            <listcell label="${arg.foo}"/> <!-- Wrong! it is always empty -->
            <listcell label="${each}"/>
        </listitem>
    </template>
</listbox>

To work around, you have to store the value in, say, component's custom attributes (Component.getAttributes(). For example,

<listbox model="${$composer.fruits}" apply="foo.FruitProvider">
    <custom-attributes foo="${arg.foo}"/><!-- store it for later use -->
    <template name="model">
        <listitem>
            <listcell label="${foo}"/> <!-- Correct! Use the stored copy. -->
            <listcell label="${each}"/>
        </listitem>
    </template>
</listbox>

Nested Listboxes

The template can be applied recursively. Here is an example of a listbox-in-listbox:

<zk>
	<zscript><![CDATA[
	ListModel quarters = new ListModelArray(new String[] {"Q1", "Q2", "Q3", "Q4"});
	Map months = new HashMap();
	months.put("Q1", new ListModelArray(new String[] {"Jan", "Feb", "Mar"}));
	months.put("Q2", new ListModelArray(new String[] {"Apr", "May", "Jun"}));
	months.put("Q3", new ListModelArray(new String[] {"Jul", "Aug", "Sep"})); 
	months.put("Q4", new ListModelArray(new String[] {"Oct", "Nov", "Dec"}));
	ListModel qs = (quarters);
	]]></zscript>
	<listbox model="${quarters}">
		<template name="model">
			<listitem>
				<listcell>${each}</listcell>
				<listcell>
					<listbox model="${months[each]}">
						<template name="model">
							<listitem label="${each}"/>
						</template>
					</listbox>
				</listcell>
			</listitem>
		</template>
	</listbox>
</zk>

St201107-listbox-in-listbox.png

How to retrieve the outer template's data in the inner template

Although forEachStatus has an API called ForEachStatus.getPrevious(), it always returns null[1]. It is because the template is rendered on demand. When ZK is rendering the inner template, the previous iteration has already gone. There is no way to retrieve the iteration information of the outer template.

Rather, you have to traverse the component tree or use the custom-attributes element.

Here is an example of traversing the component tree to retrieve the data in the outer template, as shown at line 9 below. Notice that, each data is, as described before, stored in the component's value property.

<listbox model="${quarters}">
	<template name="model">
		<listitem>
			<listcell>
				<listbox model="${months[each]}">
					<template name="model">
						<listitem>
							<listcell label="${forEachStatus.index}" />
							<listcell>${self.parent.parent.parent.parent.parent.value}</listcell>
							<listcell>${each}</listcell>
						</listitem>
					</template>
				</listbox>
			</listcell>
		</listitem>
	</template>
</listbox>

If the component tree is deep, It is tedious and somehow error prone. Alternatively, you can store the information into a custom attribute and then retrieve it later, as shown at line 4 and 10 below.

<listbox model="${quarters}">
	<template name="model">
		<listitem>
			<custom-attributes master="${each}"/>
			<listcell>
				<listbox model="${months[each]}">
					<template name="model">
						<listitem>
							<listcell label="${forEachStatus.index}" />
							<listcell>${master}</listcell>
							<listcell>${each}</listcell>
						</listitem>
					</template>
				</listbox>
			</listcell>
		</listitem>
	</template>
</listbox>

  1. On the other hand, it returns the previous iteration information when using with the forEach attribute

Template for GroupsModel

When used with GroupsModel, listboxes will use the template called model:group for rendering the grouping object. If it is not defined, it will look for the template called model instead (i.e., the same template is used for rendering the grouping and non-grouping objects).

<listbox model="${fooGroupsModel}">
   <template name="model:group">
      <listgroup open="${groupingInfo.open}" label="${each}"/>
   </template>
   <template name="model">
      <listitem>....</listitem>
   </template>
   <template name="model:groupfoot">
      <listgroupfoot>....</listgroupfoot>
   </template>
<listbox>
  • Note the groupingInfo is used to get the information of the grouping data. Please refer to GroupingInfo

Version History

Version Date Content
6.0.0 July 2011 The template feature was introduced.
6.0.0 January 2012 The GroupingInfo statement was introduced.



Last Update : 2022/07/08

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