Specify Stubonly for Client-only Components"

From Documentation
Line 29: Line 29:
 
</source>
 
</source>
  
= Limitation =
+
= Limitation of Stub Components =
== Invalidation and Smart Updates ==
+
 
 +
When a component is stub only, it will be replaced with a special component called a stub component (<javadoc>org.zkoss.zk.ui.StubComponent</javadoc>). Furthermore, stub components might be merged to minimize the memory further. The application shall not access the component again 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 example it is safe to click the <tt>invalidate</tt> button. For end user's point of view, there is no difference if <tt>stubonly</tt> is specified or not.
 +
 
 +
<source lang="xml">
 +
<window>
 +
  <button label="self.parent.invalidate()"/>
 +
  <vbox stubonly="true">
 +
  stubonly <textbox/>
 +
  </vbox>
 +
</window>
 +
</source>
  
 
== Event Handling ==
 
== Event Handling ==
Line 37: Line 51:
  
 
{{ ZKDevelopersGuidePageFooter}}
 
{{ ZKDevelopersGuidePageFooter}}
 +
[http://www.example.com link title]

Revision as of 10:50, 9 August 2010

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


Stop.png This documentation is for an older version of ZK. For the latest one, please click here.


Overview

[since 5.0.4][ZK EE]

It is common that the states of some components are not required to maintain at 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 at the server (and all states are maintained at the client). For example,

<hbox stubonly="true">
</hbox>

Values of Stubonly: true, false and inherit

The default value of the stubonly property is inherit that is the same as its parent, 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 example, only textbox is not stub-only, while hbox, splitter, listbox, listitem and labels are all stub-only.

<hbox stubonly="true">
  a stub-only label
  <textbox stubonly="false"/>
  <splitter/>
  <listbox>
    <listitem label="also stubonly"/>
  </listbox>
</hbox>

Limitation of Stub Components

When a component is stub only, it will be replaced with a special component called a stub component (StubComponent). Furthermore, stub components might be merged to minimize the memory further. The application shall not access the component again 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 example it is safe to click the invalidate button. For end user's point of view, there is no difference if stubonly is specified or not.

 <window>
  <button label="self.parent.invalidate()"/>
  <vbox stubonly="true">
  stubonly <textbox/>
  </vbox>
</window>

Event Handling

Client-side Programming


Last Update : 2010/08/09

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


link title