ZK Developer's Reference/UI Composing/ZUML/On-demand Evaluation

By default, ZK creates components based on what are defined in a ZUML document, when loading the document. However, we can defer the creation of some sections of components, until necessary, such as becoming visible. This technique is called load-on-demand or render-on-demand.

For example, you could split a ZUML document into multiple, and then load the required ones when necessary. Please refer to the Load ZUML in Java section for how to load a ZUML document dynamically.

It improves the performance in both the server and client sides. It is suggested to apply this technique when appropriate. In additions, ZK Loader provides a standard on-demand evaluation called fulfill to simplify the implementation as described in the following section.

Load-on-Demand with the fulfill Attribute

The simplest way to defer the creation of the child components is to use the fulfill attribute. For example, comboitem in the following code snippet will not be created, until combobox receives the onOpen event, indicating comboitem is becoming visible.

<combobox fulfill="onOpen">
    <comboitem label="First Option"/>    
</combobox>

In other words, if a XML element is specified with the fulfill attribute, all of its child elements won't be processed until the event specified as the value of the fulfill attribute is received.

Specify Target with its ID

If the event to trigger the creation of children is targeted to another component, you can specify the target component's identifier in front of the event name as depicted below.

<button id="btn" label="show" onClick="content.visible = true"/>
<div id="content" fulfill="btn.onClick">
    Any content created automatically when btn is clicked    
</div>

Specify Target with its Path

If the components belong to different ID space, you can specify a path before the event name as follows.

<button id="btn" label="show" onClick="content.visible = true"/>
<window id="content" fulfill="../btn.onClick">
    Any content created automatically when btn is clicked    
</window>

Specify Target with EL Expressions

EL expressions are allowed to specify the target, and it must return a component, an identifier or a path.

<div fulfill="${foo}.onClick">
...
</div>

Specify Multiple Fulfill Conditions

If there are multiple conditions to fulfill, you could specify all of them in the fulfill attribute by separating them with a comma, such as

<div fulfill="b1.onClick, ${another}.onOpen">
...
</div>

Load Another ZUML on Demand with the fulfill Attribute

You could specify an URI in the fulfill attribute, such that when, the fulfill condition is satisfied (i.e., the specified event has been received), the ZUML document of the URI will be loaded and rendered as the children of the associated component. To specify an URI, just append it to the condition and separate with an equal sign (=). For example,

<zk>
    <button id="btn" label="Click to Load"/>
    <div fulfill="btn.onClick=another.zul"/>
</zk>

Then, another.zul will be loaded when the button is clicked.

Notice that you could specify multiple conditions, but you could specify at most one URI, and the ZUML document of the URI is loaded no matter which condition is satisfied.

<div fulfill="btn.onClick, foo.onOpen=another.zul"/>

If you specify an URI without any condition, the ZUML document of the URI will be loaded at very beginning. In other words, it has the same effect of using include.

<div fulfill="=another.zul"/>

The onFulfill Event

After ZK applies the fulfill condition, i.e., creates all descendant components, it fires the onFulfill event with an instance of FulfillEvent to notify the component for further processing if any.

For example, if you use the wireVariables method of the Components class, you might have to call wireVariables again to wire the new components in the onFulfill event.

<div fulfill="b1.onClick, b2.onOpen" onFulfill="Components.wireVariables(self, controller)">
	...
</div>

Version History

Version	Date	Content