Actions and Effects"

From Documentation
 
(17 intermediate revisions by 5 users not shown)
Line 3: Line 3:
 
__TOC__
 
__TOC__
  
[since 5.0.6]
+
{{versionSince|5.0.6}}
  
The client-side action (CSA) is used to control how to perform an action at the client. Typical use is to control the effect of showing or hiding a widget. For example, with CSA, you could use the so-called ''slide-down'' effect to display a widget.
+
The client-side action is used to control how to perform an action at the client. Typical use is to control the effect of showing or hiding a widget. For example, with client-side action, you could use the so-called ''slide-down'' effect to display a widget.
  
It is a generic feature available to <javadoc>org.zkoss.zk.ui.HtmlBasedComponent</javadoc>, so you could apply to almost all widgets.
+
It is a generic feature available to <javadoc>org.zkoss.zk.ui.HtmlBasedComponent</javadoc>, so you could apply it to almost all widgets.
  
CSA allows the developer to control some actions without JavaScript. If you want to have the full control (and are OK to write some JavaScript code), please refer to [[ZK Client-side Reference/General Control|ZK Client-side Reference]] for the complete control of the client-side behavior.
+
The client-side action allows the developer to control some actions without JavaScript. If you want to have full control (and are OK to write some JavaScript code), please refer to [[ZK Client-side Reference/General Control|ZK Client-side Reference]] for complete control of the client-side behavior.
  
 
= How to Apply Client-side Actions =
 
= How to Apply Client-side Actions =
Line 21: Line 21:
 
For example, we could use the ''slide-down'' effect to display a window as follows<ref>If you are using the effects with a modal window, it is important to specify the width. Otherwise, the calculation of the position might be wrong.</ref>.
 
For example, we could use the ''slide-down'' effect to display a window as follows<ref>If you are using the effects with a modal window, it is important to specify the width. Otherwise, the calculation of the position might be wrong.</ref>.
  
<source lang="xml" high="4">
+
<source lang="xml" highlight="4">
 
<zk>
 
<zk>
 
<button label="Show a modal window" onClick="wnd.doModal()"/>
 
<button label="Show a modal window" onClick="wnd.doModal()"/>
<window id="wnd" title="Modal" border="normal" window="300px"
+
<window id="wnd" title="Modal" border="normal" width="300px"
 
action="show: slideDown" visible="false">
 
action="show: slideDown" visible="false">
 
This is a modal window.
 
This is a modal window.
Line 30: Line 30:
 
</zk></source>
 
</zk></source>
  
In additions, you could specify additions options by enclosing it with the parentheses as follows.
+
In addition, you could specify additional options by enclosing them with the parentheses as follows.
  
 
<source lang="xml">
 
<source lang="xml">
Line 38: Line 38:
 
</source>
 
</source>
  
which specifies the duration of sliding down is 100 milliseconds, and the duration of sliding-up is 300 milliseconds.
+
which specifies the duration of sliding down is 100 milliseconds, and the duration of sliding up is 300 milliseconds.
  
Security Note: the options is actually a JavaScript object (i.e., a map, <javadoc directory="jsdoc">_global_.Map</javadoc>), and ZK pass whatever being specified to the client for evaluation. Thus, if you allow the user to specify the effect, you shall encode it first to avoid [[ZK Developer's Reference/Security Tips/Cross-site scripting|cross-site scripting]].
+
Security Note: the options is actually a JavaScript object (i.e., a map, <javadoc directory="jsdoc">_global_.Map</javadoc>), and ZK passes whatever is being specified to the client for evaluation. Thus, if you allow the user to specify the effect, you shall encode it first to avoid [[ZK Developer's Reference/Security Tips/Cross-site scripting|cross-site scripting]].
  
 
<blockquote>
 
<blockquote>
Line 51: Line 51:
 
Here is a list of predefined actions.
 
Here is a list of predefined actions.
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Name!! Description
 
! Name!! Description
 
|-
 
|-
Line 68: Line 68:
  
 
== Predefined Effects ==
 
== Predefined Effects ==
Here is a list of predefined actions.
+
Here is a list of predefined effects.
  
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Name!! Description
 
! Name!! Description
 
|-
 
|-
 
| slideDown
 
| slideDown
| Slides down to display this widget (making a wdiget visible).
+
| Slides down to display this widget (making a widget visible).
Options:
 
* '''duration''' - the number of milliseconds to slide down the widget
 
 
|-
 
|-
 
| slideUp
 
| slideUp
| Slides up to hide this widget. (making a widget invisible)
+
| Slides up to hide this widget (making a widget invisible).
Options:
 
* '''duration''' - the number of milliseconds to slide up the widget
 
 
|-
 
|-
 
| slideIn
 
| slideIn
| Slides in to display this widget (making a wdiget visible).
+
| Slides in to display this widget (making a widget visible).
Options:
 
* '''duration''' - the number of milliseconds to slide in the widget
 
 
|-
 
|-
 
| slideOut
 
| slideOut
| Slides out to hide this widget. (making a widget invisible)
+
| Slides out to hide this widget (making a widget invisible).
Options:
+
|}
* '''duration''' - the number of milliseconds to slide out the widget
+
 
 +
== Predefined Options for Effects ==
 +
{| class='wikitable' | width="100%"
 +
! Option Name !! Acceptable Values !! Description
 +
|-
 +
| anchor
 +
| t, b, l, r
 +
| The 4 values represent '''the direction''' to slide: '''top to bottom''' , '''bottom to top''', '''left to right''', '''right to left''' respectively.
 +
|-
 +
| duration
 +
| a number of milliseconds
 +
| The time to slide up/down/in/out a widget. The larger the time, the slower the widget slides.
 
|}
 
|}
  
 +
== Custom Actions ==
 +
If you want to take some actions other than the predefined actions listed above, you have to override the corresponding method at the client. For example, suppose you'd like to change the color when a label's value (<javadoc method="setValue(java.lang.String)">org.zkoss.zul.Label</javadoc>) is changed. Then, you could do as follows:
 +
 +
<source lang="xml">
 +
<label id="inf2">
 +
<attribute w:name="setValue">
 +
function (value, fromServer) {
 +
this.$setValue(value, fromServer);
 +
if (this.desktop) {
 +
this._red = !this._red;
 +
this.setStyle('background:'+(this._red ? 'red':'green'));
 +
}
 +
}
 +
</attribute>
 +
</label>
 +
</source>
 +
 +
For more information, please refer to [[ZK Client-side Reference/General Control/Widget Customization|ZK Client-side Reference: Widget Customization]].
 
== Custom Effects ==
 
== Custom Effects ==
For adding your custom effects, please refer to [[ZK Client-side Reference/Customization/Actions and Effects|ZK Client-side Reference]] for details.
+
For adding your custom effects, please refer to [[ZK Client-side Reference/Customization/Actions and Effects|ZK Client-side Reference: Customization: Actions and Effects]] for details.
  
 
= Notes for Upgrading from ZK 3 =
 
= Notes for Upgrading from ZK 3 =
  
They are both called Client-side Actions, but they are different and you have to rewrite them to make it work under ZK 5:
+
They are both called Client-side Actions, but they are different and you have to rewrite them to make them work under ZK 5:
  
# The action names was changed and the support is limited to <code>show</code> and <code>hide</code> (while ZK 3 supports any <code>onxxx</code>).
+
# The action names were changed and the support is limited to <code>show</code> and <code>hide</code> (while ZK 3 supports any <code>onxxx</code>).
 
# The action operation must be the name of one of the methods defined in <javadoc directory="jsdoc">zk.eff.Actions</javadoc> (while ZK 3 is the JavaScript code).
 
# The action operation must be the name of one of the methods defined in <javadoc directory="jsdoc">zk.eff.Actions</javadoc> (while ZK 3 is the JavaScript code).
 
# It is part of <javadoc>org.zkoss.zk.ui.HtmlBasedComponent</javadoc> (while ZK 3 is <javadoc>org.zkoss.zul.impl.XulElement</javadoc>).
 
# It is part of <javadoc>org.zkoss.zk.ui.HtmlBasedComponent</javadoc> (while ZK 3 is <javadoc>org.zkoss.zul.impl.XulElement</javadoc>).
  
=Version History=
 
{{LastUpdated}}
 
{| border='1px' | width="100%"
 
! Version !! Date !! Content
 
|-
 
| 5.0.6
 
| December 2010
 
| Client-side actions were introduced since 5.0.6
 
|}
 
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 04:18, 22 March 2024


Actions and Effects


Since 5.0.6

The client-side action is used to control how to perform an action at the client. Typical use is to control the effect of showing or hiding a widget. For example, with client-side action, you could use the so-called slide-down effect to display a widget.

It is a generic feature available to HtmlBasedComponent, so you could apply it to almost all widgets.

The client-side action allows the developer to control some actions without JavaScript. If you want to have full control (and are OK to write some JavaScript code), please refer to ZK Client-side Reference for complete control of the client-side behavior.

How to Apply Client-side Actions

To apply the client-side action to a widget, you have to assign a value to the action property (HtmlBasedComponent.setAction(String)). The syntax is as follows.

action="action-name1: effect1; action-name2: effect2"

The action name (e.g., action1) has to be one of the predefined names, such as show and hide. The action effect (e.g., effect1) has to be one of the predefined effects, such as slideDown and slideUp.

For example, we could use the slide-down effect to display a window as follows[1].

<zk>
	<button label="Show a modal window" onClick="wnd.doModal()"/>
	<window id="wnd" title="Modal" border="normal" width="300px"
	 action="show: slideDown" visible="false">
		This is a modal window.
	</window>
</zk>

In addition, you could specify additional options by enclosing them with the parentheses as follows.

<div action="show: slideDown({duration: 1000}); hide: slideUp({duration: 300})">
....
</div>

which specifies the duration of sliding down is 100 milliseconds, and the duration of sliding up is 300 milliseconds.

Security Note: the options is actually a JavaScript object (i.e., a map, Map), and ZK passes whatever is being specified to the client for evaluation. Thus, if you allow the user to specify the effect, you shall encode it first to avoid cross-site scripting.


  1. If you are using the effects with a modal window, it is important to specify the width. Otherwise, the calculation of the position might be wrong.

Predefined Actions

Here is a list of predefined actions.

Name Description
show The show action is used to display a widget (making a widget visible).

When a visible widget is attached to a page, the show action will take place too.

hide The hide action is used to hide a widget (making a widget invisible).

When a visible widget is detached from a page, the hide action will take place too.

invalidate The invalidate action is invoked when a visible widget is invalidated, i.e., when Component.invalidate() is called.

Example, action="invalidate: slideDown".

Predefined Effects

Here is a list of predefined effects.

Name Description
slideDown Slides down to display this widget (making a widget visible).
slideUp Slides up to hide this widget (making a widget invisible).
slideIn Slides in to display this widget (making a widget visible).
slideOut Slides out to hide this widget (making a widget invisible).

Predefined Options for Effects

Option Name Acceptable Values Description
anchor t, b, l, r The 4 values represent the direction to slide: top to bottom , bottom to top, left to right, right to left respectively.
duration a number of milliseconds The time to slide up/down/in/out a widget. The larger the time, the slower the widget slides.

Custom Actions

If you want to take some actions other than the predefined actions listed above, you have to override the corresponding method at the client. For example, suppose you'd like to change the color when a label's value (Label.setValue(String)) is changed. Then, you could do as follows:

<label id="inf2">
	<attribute w:name="setValue">
	function (value, fromServer) {
		this.$setValue(value, fromServer);
		if (this.desktop) {
			this._red = !this._red;
			this.setStyle('background:'+(this._red ? 'red':'green'));
		}
	}
	</attribute>
</label>

For more information, please refer to ZK Client-side Reference: Widget Customization.

Custom Effects

For adding your custom effects, please refer to ZK Client-side Reference: Customization: Actions and Effects for details.

Notes for Upgrading from ZK 3

They are both called Client-side Actions, but they are different and you have to rewrite them to make them work under ZK 5:

  1. The action names were changed and the support is limited to show and hide (while ZK 3 supports any onxxx).
  2. The action operation must be the name of one of the methods defined in Actions (while ZK 3 is the JavaScript code).
  3. It is part of HtmlBasedComponent (while ZK 3 is XulElement).



Last Update : 2024/03/22

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