On-demand Evaluation"
m (remove empty version history (via JWB)) |
|||
(12 intermediate revisions by 3 users not shown) | |||
Line 3: | Line 3: | ||
__TOC__ | __TOC__ | ||
− | By default, ZK creates components based on what | + | By default, ZK creates components based on what is 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 [[ZK Developer's Reference/UI Composing/ZUML/Load ZUML in Java|Load ZUML in Java]] section for how to load a ZUML document dynamically. | + | For example, you could split a ZUML document into multiple pages, and then load the required ones when necessary. Please refer to the [[ZK Developer's Reference/UI Composing/ZUML/Load ZUML in Java|Load ZUML in Java]] section for how to load a ZUML document dynamically. |
It improves the performance both at the server and client sides. It is suggested to apply this technique whenever appropriate. In addition, ZK Loader provides a standard on-demand evaluation called ''fulfill'' to simplify the implementation as described in the following section. | It improves the performance both at the server and client sides. It is suggested to apply this technique whenever appropriate. In addition, ZK Loader provides a standard on-demand evaluation called ''fulfill'' to simplify the implementation as described in the following section. | ||
Line 11: | Line 11: | ||
=Load-on-Demand with the fulfill Attribute= | =Load-on-Demand with the fulfill Attribute= | ||
− | The simplest way to defer the creation of the child components is to use [[ZUML Reference/ZUML/Attributes/fulfill|the fulfill attribute]]. For example, the [[ZK Component Reference/Input/Comboitem|comboitem]] in the following code snippet will not be created, until the [[ZK Component Reference/Input/Combobox|combobox]] receives the < | + | The simplest way to defer the creation of the child components is to use [[ZUML Reference/ZUML/Attributes/fulfill|the fulfill attribute]]. For example, the [[ZK Component Reference/Input/Comboitem|comboitem]] in the following code snippet will not be created, until the [[ZK Component Reference/Input/Combobox|combobox]] receives the <code>onOpen</code> event, indicating that comboitem is becoming visible. |
<source lang="xml"> | <source lang="xml"> | ||
Line 19: | Line 19: | ||
</source> | </source> | ||
− | In other words, if | + | In other words, if an XML element is specified with the fulfill attribute, all of its child elements will not be processed until the event specified as the value of the fulfill attribute is received. |
− | ==Specify Target with | + | ==Specify Target with ID or Implicit Variable== |
If the event to trigger the creation of children is targeted at another component, you can specify the target component's identifier in front of the event name as depicted below. | If the event to trigger the creation of children is targeted at another component, you can specify the target component's identifier in front of the event name as depicted below. | ||
Line 29: | Line 29: | ||
Any content created automatically when btn is clicked | Any content created automatically when btn is clicked | ||
</div> | </div> | ||
+ | </source> | ||
+ | |||
+ | |||
+ | === Create a Tabpanel's Children after It's Selected === | ||
+ | <source lang='xml' highlight='10'> | ||
+ | <tabbox> | ||
+ | <tabs> | ||
+ | <tab selected="true">tab 1</tab> | ||
+ | <tab>tab 2</tab> | ||
+ | </tabs> | ||
+ | <tabpanels> | ||
+ | <tabpanel> | ||
+ | .. | ||
+ | </tabpanel> | ||
+ | <tabpanel fulfill="self.linkedTab.onSelect"> | ||
+ | ... | ||
+ | </tabpanel> | ||
+ | </tabpanels> | ||
+ | </tabbox> | ||
</source> | </source> | ||
==Specify Target with its Path== | ==Specify Target with its Path== | ||
− | If the components belong to different ID space, you can specify a path before the event name as follows | + | If the components belong to a different ID space, you can specify a path before the event name as follows: |
<source lang="xml"> | <source lang="xml"> | ||
Line 45: | Line 64: | ||
<source lang="xml"> | <source lang="xml"> | ||
− | <div fulfill="${foo}.onClick"> | + | <button id="foo" label="click me to show"/> |
− | + | <div fulfill="${foo}.onClick"> | |
− | </div> | + | created on demand |
+ | </div> | ||
</source> | </source> | ||
Line 70: | Line 90: | ||
</source> | </source> | ||
− | Then, < | + | Then, <code>another.zul</code> will be loaded when the button is clicked. |
Notice that even though you could specify multiple conditions, you could specify at most one URI. The ZUML document of the URI will be loaded no matter which condition is satisfied. | Notice that even though you could specify multiple conditions, you could specify at most one URI. The ZUML document of the URI will be loaded no matter which condition is satisfied. | ||
Line 78: | Line 98: | ||
</source> | </source> | ||
− | If you specify an URI without any conditions, the ZUML document of the URI will be loaded from the very beginning. In other words, it has the same effect | + | If you specify an URI without any conditions, the ZUML document of the URI will be loaded from the very beginning. In other words, it has the same effect as using [[ZK Developer's Reference/UI Composing/ZUML/Include|include]]. |
<source lang="xml"> | <source lang="xml"> | ||
Line 85: | Line 105: | ||
= The onFulfill Event = | = The onFulfill Event = | ||
− | After ZK applies the fulfill condition, i.e., creates all descendant components, it fires the < | + | After ZK applies the fulfill condition, i.e., creates all descendant components, it fires the <code>onFulfill</code> event with an instance of <javadoc>org.zkoss.zk.ui.event.FulfillEvent</javadoc> to notify the component for further processing if any. |
− | For example, if you use the < | + | For example, if you use the <code>wireVariables</code> method of the <javadoc>org.zkoss.zk.ui.Components</javadoc> class, you might have to call <code>wireVariables</code> again to wire the new components in the <code>onFulfill</code> event. |
<source lang="xml" > | <source lang="xml" > | ||
Line 95: | Line 115: | ||
</source> | </source> | ||
− | + | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
{{ZKDevelopersReferencePageFooter}} | {{ZKDevelopersReferencePageFooter}} |
Latest revision as of 05:54, 6 February 2024
By default, ZK creates components based on what is 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 pages, 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 both at the server and client sides. It is suggested to apply this technique whenever appropriate. In addition, 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, the comboitem in the following code snippet will not be created, until the combobox receives the onOpen
event, indicating that comboitem is becoming visible.
<combobox fulfill="onOpen">
<comboitem label="First Option"/>
</combobox>
In other words, if an XML element is specified with the fulfill attribute, all of its child elements will not be processed until the event specified as the value of the fulfill attribute is received.
Specify Target with ID or Implicit Variable
If the event to trigger the creation of children is targeted at 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>
Create a Tabpanel's Children after It's Selected
<tabbox>
<tabs>
<tab selected="true">tab 1</tab>
<tab>tab 2</tab>
</tabs>
<tabpanels>
<tabpanel>
..
</tabpanel>
<tabpanel fulfill="self.linkedTab.onSelect">
...
</tabpanel>
</tabpanels>
</tabbox>
Specify Target with its Path
If the components belong to a 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.
<button id="foo" label="click me to show"/>
<div fulfill="${foo}.onClick">
created on demand
</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 when the fulfill condition is satisfied (i.e. if a 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 even though you could specify multiple conditions, you could specify at most one URI. The ZUML document of the URI will be loaded no matter which condition is satisfied.
<div fulfill="btn.onClick, foo.onOpen=another.zul"/>
If you specify an URI without any conditions, the ZUML document of the URI will be loaded from the very beginning. In other words, it has the same effect as 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>