Event Listening"

From Documentation
m (Created page with '{{ZKDevelopersReferencePageHeader}} =Version History= {{LastUpdated}} {| border='1px' | width="100%" ! Version !! Date !! Content |- |   |   |   |} {{ZKDeveloper…')
 
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
 +
= Overview =
 +
 +
ZK allows applications to handle events at both server and client side. Handling events at the server side, as described in the previous sections, are more common, since the listeners can access the backend services directly. However, handling event at the client side improves the responsiveness. For example, it is better to be done with a client-side listener if you want to open the drop-down list when a comobox gains the focus.
 +
 +
The rule of thumb is to use server-side listeners first since it is easier, and then improve the responsiveness of the critical part, if any, with the client-side listener.
 +
 +
Here we describe how to handle events at the client. For client-side UI manipulation, please refer to the [[ZK Developer's Reference/Client-side Control/UI Composing|UI Composing]] and [[ZK Developer's Reference/Client-side Control/Widget Customization|Widget Customization]] sections.
 +
 +
= Declare a Client-side Listener in ZUML =
 +
 +
Declaring a client-side listener in a ZUML document is similar to declaring a server-side listener, except
 +
 +
# Use the client namespace, http://www.zkoss.org/2005/zk/client (aka., client)
 +
# It is JavaScript
 +
# Use <tt>this</tt> to reference to the target widget (while the event is referenced with <tt>event</tt>)
 +
 +
For example,
 +
 +
<source lang="xml">
 +
<combobox xmlns:w="client" w:onFocus="this.open()"/>
 +
</source>
 +
 +
Notice that EL expressions are allowed in the JavaScript code (for the client-side listener). Thus, it is straightforward to embed the server-side data to the client-side listener. For example,
 +
 +
<source lang="xml">
 +
<window id="wnd" title="main">
 +
<combobox xmlns:w="client" w:onFocus="zk.log('${wnd.title}')"/>
 +
</window>
 +
</source>
 +
 +
If you want to escape it, place a backslash between $ and {, such as <code>w:onFocus="zk.log('$\{wnd.title}')"</code>.
 +
 +
For more information about manipulate widgets at the client, please refer to the  [[ZK Developer's Reference/UI Composing/Client-side UI Composing]] section.
 +
 +
== The Relationship between Client and Server-side Event Listener ==
 +
 +
It is allowed to register both the client and server-side event listeners. They will be both invoked. Of course, the client-side listener is called first, and then the server-side listener. For example,
 +
 +
<source lang="xml">
 +
<div>
 +
  <combobox xmlns:w="client" w:onFocus="this.open()"
 +
  onFocus='self.parent.appendChild(new Label("focus"))'/>
 +
</div>
 +
</source>
 +
 +
If you want to stop the event propagation such that the server won't receive the event, you could invoke <javadoc method="stop(_global_.Map)" directory="jsdoc">zk.Event</javadoc>. For example, the server-side listener won't be invoked in the following example:
 +
 +
<source lang="xml">
 +
<div>
 +
  <combobox xmlns:w="client" w:onFocus="this.open(); event.stop();"
 +
  onFocus='self.parent.appendChild(new Label("focus"))'/>
 +
</div>
 +
</source>
 +
 +
= Declare a Client-side Listener in Java =
 +
 +
The other way to declare a client-side listener at the server is <javadoc method="setWidgetListener(java.lang.String, java.lang.String)">org.zkoss.zk.ui.Component</javadoc>. For example,
 +
 +
<source lang="java">
 +
combobox.setWidgetListener("onFocus", "this.open()");
 +
</source>
 +
 +
Notice that it is Java and running at the server.
 +
 +
Also notice that EL expressions are not allowed (i.e., not interpreted) if you assign it directly. It is because EL expressions are interpreted by ZK Loader when loading a ZUL page. However, it is easy to construct a string to any content you want with Java.
 +
 +
= Register a Client-side Listener in Client-Side JavaScript =
 +
 +
Listening an event at the client could be done by calling <javadoc directory="jsdoc" method="listen(_global_.Map, int)">zk.Widget</javadoc>. For example,
 +
 +
<source lang="xml">
 +
<window>
 +
<bandbox id="bb"/>
 +
<script defer="true">
 +
this.$f().bb.listen({onFocus: function () {this.open();}});
 +
</script>
 +
</window>
 +
</source>
 +
 +
where
 +
 +
# <code>defer="true"</code> is required such that the JavaScript code will be evaluated after all widgets are created successfully. Otherwise, it is not able to retreive the bandbox (<code>bb</code>).
 +
# <code>script</code> is a widget (unlike <code>zscript</code>), so <code>this</code> references to the <code>script</code> widget, rather than the parent.
 +
# <javadoc directory="jsdoc" method="$f(_global_.String)">zk.Widget</javadoc> is equivalent to <javadoc method="getFellow(java.lang.String)">org.zkoss.zk.ui.Component</javadoc>, except it is a JavaScript method (accessible at the client).
 +
 +
== Register DOM-level Event Listener ==
 +
 +
Notice that the event listener handling discussed in the previous sections is for handling so-called ZK widget event (<javadoc directory="jsdoc">zk.Event</javadoc>). Though rare, you could register a DOM-level event too by use of jQuery (API: <javadoc directory="jsdoc">_global_.jq</javadoc>).
  
 
=Version History=
 
=Version History=
{{LastUpdated}}
+
 
 
{| border='1px' | width="100%"
 
{| border='1px' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content

Revision as of 03:18, 1 December 2010

Overview

ZK allows applications to handle events at both server and client side. Handling events at the server side, as described in the previous sections, are more common, since the listeners can access the backend services directly. However, handling event at the client side improves the responsiveness. For example, it is better to be done with a client-side listener if you want to open the drop-down list when a comobox gains the focus.

The rule of thumb is to use server-side listeners first since it is easier, and then improve the responsiveness of the critical part, if any, with the client-side listener.

Here we describe how to handle events at the client. For client-side UI manipulation, please refer to the UI Composing and Widget Customization sections.

Declare a Client-side Listener in ZUML

Declaring a client-side listener in a ZUML document is similar to declaring a server-side listener, except

  1. Use the client namespace, http://www.zkoss.org/2005/zk/client (aka., client)
  2. It is JavaScript
  3. Use this to reference to the target widget (while the event is referenced with event)

For example,

<combobox xmlns:w="client" w:onFocus="this.open()"/>

Notice that EL expressions are allowed in the JavaScript code (for the client-side listener). Thus, it is straightforward to embed the server-side data to the client-side listener. For example,

<window id="wnd" title="main">
<combobox xmlns:w="client" w:onFocus="zk.log('${wnd.title}')"/>
</window>

If you want to escape it, place a backslash between $ and {, such as w:onFocus="zk.log('$\{wnd.title}')".

For more information about manipulate widgets at the client, please refer to the ZK Developer's Reference/UI Composing/Client-side UI Composing section.

The Relationship between Client and Server-side Event Listener

It is allowed to register both the client and server-side event listeners. They will be both invoked. Of course, the client-side listener is called first, and then the server-side listener. For example,

<div>
  <combobox xmlns:w="client" w:onFocus="this.open()"
   onFocus='self.parent.appendChild(new Label("focus"))'/>
</div>

If you want to stop the event propagation such that the server won't receive the event, you could invoke Event.stop(Map). For example, the server-side listener won't be invoked in the following example:

<div>
  <combobox xmlns:w="client" w:onFocus="this.open(); event.stop();"
   onFocus='self.parent.appendChild(new Label("focus"))'/>
</div>

Declare a Client-side Listener in Java

The other way to declare a client-side listener at the server is Component.setWidgetListener(String, String). For example,

combobox.setWidgetListener("onFocus", "this.open()");

Notice that it is Java and running at the server.

Also notice that EL expressions are not allowed (i.e., not interpreted) if you assign it directly. It is because EL expressions are interpreted by ZK Loader when loading a ZUL page. However, it is easy to construct a string to any content you want with Java.

Register a Client-side Listener in Client-Side JavaScript

Listening an event at the client could be done by calling Widget.listen(Map, int). For example,

<window>
	<bandbox id="bb"/>
	<script defer="true">
	this.$f().bb.listen({onFocus: function () {this.open();}});
	</script>
</window>

where

  1. defer="true" is required such that the JavaScript code will be evaluated after all widgets are created successfully. Otherwise, it is not able to retreive the bandbox (bb).
  2. script is a widget (unlike zscript), so this references to the script widget, rather than the parent.
  3. Widget.$f(String) is equivalent to Component.getFellow(String), except it is a JavaScript method (accessible at the client).

Register DOM-level Event Listener

Notice that the event listener handling discussed in the previous sections is for handling so-called ZK widget event (Event). Though rare, you could register a DOM-level event too by use of jQuery (API: jq).

Version History

Version Date Content
     



Last Update : 2010/12/01

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