Specify Stubonly for Client-only Components"

From Documentation
m
 
(9 intermediate revisions by 3 users not shown)
Line 4: Line 4:
  
 
= Overview =
 
= Overview =
[since 5.0.4][ZK EE]
+
{{versionSince| 5.0.4}}{{ZK EE}}
  
It is common that the states of some components are not required to maintain on the server. A typical example is that an application might use some components, such as <tt>hbox</tt>, for layout and won't access it again after rendered. To minimize the memory footprint, ZK supports a special property called <tt>stubonly</tt> (<javadoc method="setStubonly(java.lang.String)">org.zkoss.zk.ui.Component</javadoc>). Once specified with <tt>true</tt>, its states won't be maintained on the server (and all states are maintained at the client). For example,
 
  
<syntax lang="xml">
+
{{versionSince| 6.0.0}}{{ZK All}}
 +
 
 +
It is common that the states of some components are not required to be maintained on the server. A typical example is that an application might use some components, such as <code>hbox</code>, for layout and won't access it again after rendered. To minimize the memory footprint, ZK supports a special property called <code>stubonly</code> (<javadoc method="setStubonly(java.lang.String)">org.zkoss.zk.ui.Component</javadoc>). Once specified with <code>true</code>, its states won't be maintained on the server (and all states are maintained at the client). For example,
 +
 
 +
<syntaxhighlight line lang="xml">
 
<hbox stubonly="true">
 
<hbox stubonly="true">
 
</hbox>
 
</hbox>
</syntax>
+
</syntaxhighlight>
  
* Notice this feature is available since ZK 5.0.4 EE.
+
* Notice this feature is available since ZK 5.0.4 EE, and available in CE since ZK 6.0.0.
  
 
== Values of Stubonly: true, false and inherit ==
 
== Values of Stubonly: true, false and inherit ==
  
The default value of the <tt>stubonly</tt> property is <tt>inherit</tt>. It means the value is the same as its parent's, if any, or <tt>false</tt>, if no parent at all. Thus, if a component's <tt>stubonly</tt> is specified with <tt>true</tt>, all its descendants are stub-only too, unless <tt>false</tt> is specified explicitly. For example, in the following snippet, only <tt>textbox</tt> is <i>not</i> stub-only, while <tt>hbox</tt>, <tt>splitter</tt>, <tt>listbox</tt>,
+
The default value of the <code>stubonly</code> property is <code>inherit</code>. It means the value is the same as its parent's, if any, or <code>false</code>, if no parent at all. Thus, if a component's <code>stubonly</code> is specified with <code>true</code>, all its descendants are stub-only too, unless <code>false</code> is specified explicitly. For example, in the following snippet, only <code>textbox</code> is <i>not</i> stub-only, while <code>hbox</code>, <code>splitter</code>, <code>listbox</code>,
<tt>listitem</tt> and labels are all stub-only.
+
<code>listitem</code> and labels are all stub-only.
  
<syntax lang="xml">
+
<syntaxhighlight line lang="xml">
 
<hbox stubonly="true">
 
<hbox stubonly="true">
 
   a stub-only label
 
   a stub-only label
Line 29: Line 32:
 
   </listbox>
 
   </listbox>
 
</hbox>
 
</hbox>
</syntax>
+
</syntaxhighlight>
  
 
= Limitation of Stub Components =
 
= Limitation of Stub Components =
Line 37: Line 40:
 
== Invalidation ==
 
== Invalidation ==
  
While a stub component cannot be invalidated directly, it is safe to invalidate its parent. ZK will rerender all non-stub components and retain the states of stub components at the client. For example, in the following snippet, it is safe to click the <tt>invalidate</tt> button. From an end user's point of view, there is no difference whether <tt>stubonly</tt> is specified or not.
+
While a stub component cannot be invalidated directly, it is safe to invalidate its parent. ZK will rerender all non-stub components and retain the states of stub components at the client. For example, in the following snippet, it is safe to click the <code>invalidate</code> button. From an end user's point of view, there is no difference whether <code>stubonly</code> is specified or not.
  
<syntax lang="xml">
+
<syntaxhighlight line lang="xml">
 
  <window>
 
  <window>
 
   <button label="self.parent.invalidate()"/>
 
   <button label="self.parent.invalidate()"/>
Line 46: Line 49:
 
   </vbox>
 
   </vbox>
 
</window>
 
</window>
</syntax>
+
</syntaxhighlight>
 +
 
 +
It is a special case that [[ZK_Component_Reference/Supplementary/Paging|paging]] and <code>stubonly</code> cannot be applied at the same time. For example,
 +
<source lang="xml" >
 +
<listbox mold="paging" pageSize="1" >
 +
<listitem >
 +
<listcell stubonly="true"/>
 +
</listitem>
 +
<listitem>
 +
<listcell />
 +
</listitem>
 +
</listbox>
 +
</source>
 +
Although paging will [[ZK_Developer's_Reference/UI_Composing/Component-based_UI#Invalidate_a_Component|invalidate]] <code>listbox</code> and its children, <code>stubonly</code> needs the referred widget in client side which is detached during paging and throws mounting error.
  
 
== Detach and Reuse ==
 
== Detach and Reuse ==
 
The detailed information of a stub component is stored at the client. It is removed when the component is removed. Thus, you can't reuse a component if the component has some stub components and it is detached. For example, the following code won't work:
 
The detailed information of a stub component is stored at the client. It is removed when the component is removed. Thus, you can't reuse a component if the component has some stub components and it is detached. For example, the following code won't work:
  
<syntax lang="java">
+
<syntaxhighlight line lang="java">
 
public class MyListener implements EventListener {
 
public class MyListener implements EventListener {
 
   private static Window win;
 
   private static Window win;
Line 67: Line 83:
 
     }
 
     }
 
  }
 
  }
</syntax>
+
</syntaxhighlight>
  
In the above example<ref>Please refer to [http://tracker.zkoss.org/browse/ZK-1094 ZK-1094] for a real case.</ref>, <code>win</code> is reused but it also has a stub component (a label). When the window is closed, all the information at the client are removed (since Window's onClose() method detaches the window). Thus, if the event was executed again, the client can restore the detailed information back.
+
In the above example<ref>Please refer to [http://tracker.zkoss.org/browse/ZK-1094 ZK-1094] for a real case.</ref>, <code>win</code> is reused but it also has a stub component (a label). When the window is closed, all the information at the client is removed (since Window's onClose() method detaches the window). Thus, if the event is executed again, the client can restore the detailed information back.
  
 
<blockquote>
 
<blockquote>
Line 78: Line 94:
 
== Event Handling ==
 
== Event Handling ==
  
ZK will preserve all registered event listeners and handlers, when converting a stub-only component to a stub component. In other words, the listener will be called if the corresponding event is fired. However, since the original component no longer exists, the event is fired in the most generic format: an instance of <javadoc>org.zkoss.zk.ui.event.Event</javadoc>, rather than a derived class.
+
ZK will preserve all registered event listeners and handlers when converting a stub-only component to a stub component. In other words, the listener will be called if the corresponding event is fired. However, since the original component no longer exists, the event is fired in the most generic format: an instance of <javadoc>org.zkoss.zk.ui.event.Event</javadoc>, rather than a derived class.
  
For example, in the following snippet, "org.zkoss.zk.ui.event.StubEvent:onStub" will be generated to <tt>System.out</tt>.
+
For example, in the following snippet, [https://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/event/StubEvent.html org.zkoss.zk.ui.event.StubEvent:onStub] will be generated to <code>System.out</code>.
  
<syntax lang="xml">
+
<syntaxhighlight line lang="xml">
<textbox stubonly="true" onChange='System.out.println(event.getClass().getName()+":"+event.getName())'/>
+
<textbox stubonly="true"  
</syntax>
+
onChange='System.out.println(event.getClass().getName()+":"+event.getName())'/>
 +
</syntaxhighlight>
  
In addition, the target (<javadoc method="getTarget()">org.zkoss.zk.ui.event.Event</javadoc>) is the stub component rather than the original one (<tt>text</tt>).
+
In addition, the target (<javadoc method="getTarget()">org.zkoss.zk.ui.event.Event</javadoc>) is the stub component rather than the original one, <code>Textbox</code>.
  
 
== Client-side Programming ==
 
== Client-side Programming ==
Line 92: Line 109:
 
The client-side widget of a component is the same no matter if it is stub only. Thus, the application can have the full control by registering the client side event listener, such as
 
The client-side widget of a component is the same no matter if it is stub only. Thus, the application can have the full control by registering the client side event listener, such as
  
<syntax lang="xml">
+
<syntaxhighlight line lang="xml">
 
<textbox stubonly="true" w:onChange="doSomething(this.value)" xmlns:w="client"/>
 
<textbox stubonly="true" w:onChange="doSomething(this.value)" xmlns:w="client"/>
</syntax>
+
</syntaxhighlight>
  
 
In other words, the stub-only components behave the same at the client.
 
In other words, the stub-only components behave the same at the client.
Line 101: Line 118:
  
 
=Version History=
 
=Version History=
{{LastUpdated}}
+
 
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-

Latest revision as of 10:11, 1 February 2024


DocumentationZK Developer's ReferencePerformance TipsSpecify Stubonly for Client-only Components
Specify Stubonly for Client-only Components


Overview

Since 5.0.4

  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ee.png


Since 6.0.0

  • Available for ZK:
  • http://www.zkoss.org/product/zkhttp://www.zkoss.org/whyzk/zkeeVersion ce-pe-ee.png

It is common that the states of some components are not required to be maintained on the server. A typical example is that an application might use some components, such as hbox, for layout and won't access it again after rendered. To minimize the memory footprint, ZK supports a special property called stubonly (Component.setStubonly(String)). Once specified with true, its states won't be maintained on the server (and all states are maintained at the client). For example,

1 <hbox stubonly="true">
2 </hbox>
  • Notice this feature is available since ZK 5.0.4 EE, and available in CE since ZK 6.0.0.

Values of Stubonly: true, false and inherit

The default value of the stubonly property is inherit. It means the value is the same as its parent's, if any, or false, if no parent at all. Thus, if a component's stubonly is specified with true, all its descendants are stub-only too, unless false is specified explicitly. For example, in the following snippet, only textbox is not stub-only, while hbox, splitter, listbox, listitem and labels are all stub-only.

1 <hbox stubonly="true">
2   a stub-only label
3   <textbox stubonly="false"/>
4   <splitter/>
5   <listbox>
6     <listitem label="also stubonly"/>
7   </listbox>
8 </hbox>

Limitation of Stub Components

When a component is stub only, it will be replaced with a special component called a stub component (StubComponent) after rendered. In addition, the adjacent stub components might be merged to minimize the memory further. Thus, the application should not access the component again on the server, if it is specified as stub only.

Invalidation

While a stub component cannot be invalidated directly, it is safe to invalidate its parent. ZK will rerender all non-stub components and retain the states of stub components at the client. For example, in the following snippet, it is safe to click the invalidate button. From an end user's point of view, there is no difference whether stubonly is specified or not.

1  <window>
2   <button label="self.parent.invalidate()"/>
3   <vbox stubonly="true">
4   stubonly <textbox/>
5   </vbox>
6 </window>

It is a special case that paging and stubonly cannot be applied at the same time. For example,

<listbox mold="paging" pageSize="1" >
	<listitem >
		<listcell stubonly="true"/>
	</listitem>
	<listitem>
		<listcell />
	</listitem>
</listbox>

Although paging will invalidate listbox and its children, stubonly needs the referred widget in client side which is detached during paging and throws mounting error.

Detach and Reuse

The detailed information of a stub component is stored at the client. It is removed when the component is removed. Thus, you can't reuse a component if the component has some stub components and it is detached. For example, the following code won't work:

 1 public class MyListener implements EventListener {
 2    private static Window win;
 3    public void onEvent(Event evt) throws Exception{
 4       if (win ==null) {	   
 5          win = new Window();
 6          win.setTitle("Hello!");
 7          win.setClosable(true);
 8          Label testLabel = new Label("My Label");
 9          testLabel.setStubonly("true");
10          win.appendChild(testLabel);
11       }
12       win.setParent(evt.getTarget().getFellow("mainWindow"));
13       win.doModal();
14     }
15  }

In the above example[1], win is reused but it also has a stub component (a label). When the window is closed, all the information at the client is removed (since Window's onClose() method detaches the window). Thus, if the event is executed again, the client can restore the detailed information back.


  1. Please refer to ZK-1094 for a real case.

Event Handling

ZK will preserve all registered event listeners and handlers when converting a stub-only component to a stub component. In other words, the listener will be called if the corresponding event is fired. However, since the original component no longer exists, the event is fired in the most generic format: an instance of Event, rather than a derived class.

For example, in the following snippet, org.zkoss.zk.ui.event.StubEvent:onStub will be generated to System.out.

1 <textbox stubonly="true" 
2 onChange='System.out.println(event.getClass().getName()+":"+event.getName())'/>

In addition, the target (Event.getTarget()) is the stub component rather than the original one, Textbox.

Client-side Programming

The client-side widget of a component is the same no matter if it is stub only. Thus, the application can have the full control by registering the client side event listener, such as

1 <textbox stubonly="true" w:onChange="doSomething(this.value)" xmlns:w="client"/>

In other words, the stub-only components behave the same at the client.

Refer to Client Side Programming and ZK Client-side Reference: General Control for more information.

Version History

Version Date Content
6.0.2 June, 2012 Bug: stubonly doesn't work, and change the event handle from origin event to StubEvent.



Last Update : 2024/02/01

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