ZK Developer's Reference/UI Composing/ZUML/Iterative Evaluation

forEach

By default, ZK instantiates a component for each XML element. If you would like to generate a collection of components, you could specify the forEach attribute. For example,

<listbox>
    <listitem label="${each}" forEach="Apple, Orange, Strawberry"/>
</listbox>

is equivalent to

<listbox>
    <listitem label="Apple"/>
    <listitem label="Orange"/>
    <listitem label="Strawberry"/>
</listbox>

When ZK Loader iterates through items of the give collection, it will update two implicit objects: each and forEachStatus. The each variable represents the item being iterated, while forEachStatus is an instance of ForEachStatus, from which you could retrieve the index and the previous forEach, if any (nested iterations).

If you have a variable holding a collection of objects, then you can specify it directly in the forEach attribute. For example, assume you have a variable called grades as follows.

grades = new String[] {"Best", "Better", "Good"};

Then, you can iterate them by use of the forEach attribute as follows. Notice that you have to use EL expression to specify the collection.

<listbox>
    <listitem label="${each}" forEach="${grades}"/>    
</listitem>

The iteration depends on the type of the value of the forEach attribute:

• If java.util.Collection, it iterates each element of the collection.
• If java.util.Map, it iterates each Map.Entry of the map.
• If java.util.Iterator, it iterates each element from the iterator.
• If java.util.Enumeration, it iterates each element from the enumeration.
• If Object[], int[], short[], byte[], char[], float[] or double[] is specified, it iterates each element from the array.
• If null, nothing is generated (it is ignored).
• If neither of above types is specified, the associated element will be evaluated once as if a collection with a single item is specified.

The each Variable

During the evaluation, a variable called each is created and assigned with the item from the specified collection. In the above example, each is assigned with "Best" in the first iteration, then "Better" and finally "Good".

Notice that the each variable is accessible both in EL expression and in zscript. ZK will preserve the value of the each variable if it is defined before, and restore it after the evaluation of the associated element.

The forEachStatus Variable

The forEachStatus variable is an instance of org.zkoss.ui.util.ForEachStatus. It holds the information about the current iteration. It is mainly used to get the item of the enclosing element that is also assigned with the forEach attribute.

In the following example, we use nested iterative elements to generate two listboxes.

<hlayout>
    <zscript>
    classes = new String[] {"College", "Graduate"};
    grades = new Object[] {
        new String[] {"Best", "Better"}, new String[] {"A++", "A+", "A"}
    };
    </zscript>
    <listbox width="200px" forEach="${classes}">
        <listhead>
            <listheader label="${each}"/>
        </listhead>
        <listitem label="${forEachStatus.previous.each}: ${each}"
         forEach="${grades[forEachStatus.previous.index]}"/>
    </listbox>
</hlayout>

Notice that the each and forEachStatus variables are accessible both in EL expression and in zscript.

Apply forEach to Muliple Elements

If you have to iterate a collection of items for multiple XML elements, you could group them with the zk element as shown below.

<zk forEach="${cond}">
    ${each.name}
    <textbox value="${each.value}"/>
    <button label="Submit"/>
</zk>

The zk element is a special element used to group a set of XML element nested. ZK Loader won't create a component for it. Rather, ZK Loader interprets the forEach, if and unless attribute it might have.

Version History

Version	Date	Content