Specify Stubonly for Client-only Components"

From Documentation
Line 70: Line 70:
 
In other words, stub-only components behave the same at the client.
 
In other words, stub-only components behave the same at the client.
  
Refer to [[Small_Talks/2010/April/Client_Side_Programming |Client Side Programming]] and [http://docs.zkoss.org/wiki/ZK5:_Client_Computing_with_ZUML Client Computing with ZUML] for more information.
+
Refer to [[Small_Talks/2010/April/Client_Side_Programming |Client Side Programming]] and [http://books.zkoss.org/wiki/ZK_Client-side_Reference/General_Control Client Computing with ZUML] for more information.
  
 
=Version History=
 
=Version History=

Revision as of 01:39, 21 December 2010


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


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,

<syntax lang="xml"> <hbox stubonly="true"> </hbox> </syntax>

  • Notice this feature is available since ZK 5.0.4 EE.

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.

<syntax lang="xml"> <hbox stubonly="true">

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

</hbox> </syntax>

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 additions, adjacent stub components might be merged to minimize the memory further. Thus, the application shall not access the component again at 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. For end user's point of view, there is no difference whether stubonly is specified or not.

<syntax lang="xml">

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

</window> </syntax>

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.Event:onChange" will be generated to System.out.

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

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

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

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

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

Refer to Client Side Programming and Client Computing with ZUML for more information.

Version History

Version Date Content
     



Last Update : 2010/12/21

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