Useful Java Utilities"

From Documentation
m (replace tt with code (via JWB))
(15 intermediate revisions by 4 users not shown)
Line 48: Line 48:
 
Clients.evalJavaScript("zk.log('Hi.');");
 
Clients.evalJavaScript("zk.log('Hi.');");
 
</source>
 
</source>
 +
 +
{{versionSince|9.6.0}}
 +
To handle javascript error while triggered evalJavascript, [https://www.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_Library_Properties/org.zkoss.zk.ui.ScriptErrorListener.class org.zkoss.zk.ui.ScriptErrorListener.class] is provided.
 +
 +
 +
==focus==
 +
{{versionSince|9.5.0}}
 +
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Clients.html#focus(org.zkoss.zk.ui.Component) Clients.focus(Component component)]
 +
 +
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Clients.html#focus(java.lang.String) Clients.focus(String selector)]
 +
 +
Focus the given component or the selector matched component.
  
 
==scrollIntoView==
 
==scrollIntoView==
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Clients.html#scrollIntoView(org.zkoss.zk.ui.Component) Clients.scrollIntoView(Component cmp)]
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Clients.html#scrollIntoView(org.zkoss.zk.ui.Component) Clients.scrollIntoView(Component cmp)]
  
Scrolls the parent of the given component, so the given one become visible in the view.
+
Scrolls the parent of the given component, so the given one becomes visible in the view.
 +
 
 +
{{versionSince| 9.5.0}}
 +
 
 +
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Clients.html#scrollIntoView(java.lang.String) Clients.scrollIntoView(String selector)]
 +
 
 +
Scrolls the parent of the selector matched component, so the given one becomes visible in the view.
  
 
==showBusy/clearBusy==
 
==showBusy/clearBusy==
Line 68: Line 86:
  
 
==showNotification==
 
==showNotification==
[since 6.0.1]
+
{{versionSince|6.0.1}}
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Clients.html#showNotification(java.lang.String) Clients.showNotification()]
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Clients.html#showNotification(java.lang.String) Clients.showNotification()]
[since 9.0.0]
+
{{versionSince|9.0.0}}
 
It is advised to use [http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Notification.html Notification class] which was introduced in ZK 9 instead.
 
It is advised to use [http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Notification.html Notification class] which was introduced in ZK 9 instead.
  
Line 97: Line 115:
  
 
=== Closable ===
 
=== Closable ===
[since 6.5.0]
+
{{versionSince|6.5.0}}
 
Notification now supports closable to let user close the notification box manually.
 
Notification now supports closable to let user close the notification box manually.
  
Line 109: Line 127:
  
 
=== Multiline ===
 
=== Multiline ===
To show a multiline message, just append <tt>&lt;br/&gt;</tt> in the message string.
+
To show a multiline message, just append <code>&lt;br/&gt;</code> in the message string.
 
<source lang='java'>
 
<source lang='java'>
 
Clients.showNotification("msg1 <br/> msg2 <br/>");
 
Clients.showNotification("msg1 <br/> msg2 <br/>");
Line 115: Line 133:
  
 
=Notification=
 
=Notification=
[since 9.0.0]
+
{{versionSince|9.0.0}}
  
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Notification.html org.zkoss.zk.ui.util.Notification]
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zk/ui/util/Notification.html org.zkoss.zk.ui.util.Notification]
Line 128: Line 146:
 
=Toast=
 
=Toast=
 
{{ZK EE}}
 
{{ZK EE}}
[since 9.0.0]
+
{{versionSince|9.0.0}}
  
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zkmax/ui/util/Toast.html org.zkoss.zkmax.ui.util.Toast]
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zkmax/ui/util/Toast.html org.zkoss.zkmax.ui.util.Toast]
  
This class offers a collection of methods showing a toast notification, which is dismissed upon left click (like Popup). Unlike Notification, Toast is stackable.
+
This class offers a collection of methods showing a toast notification, which is dismissed upon left click (like a Popup). Unlike Notification, Toast is stackable.
  
 
[[Image:ZKDevRef_UIPattern_UsefulJavaUtil_Toast01.png]]
 
[[Image:ZKDevRef_UIPattern_UsefulJavaUtil_Toast01.png]]
Line 148: Line 166:
  
 
Here are the available positions:
 
Here are the available positions:
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
!  !! left !! center !! right
 
!  !! left !! center !! right
 
|-
 
|-
Line 180: Line 198:
 
=Loadingbar=
 
=Loadingbar=
 
{{ZK EE}}
 
{{ZK EE}}
[since 9.0.0]
+
{{versionSince| 9.0.0}}
  
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zkmax/ui/util/Loadingbar.html org.zkoss.zkmax.ui.util.Loadingbar]
 
[http://www.zkoss.org/javadoc/latest/zk/org/zkoss/zkmax/ui/util/Loadingbar.html org.zkoss.zkmax.ui.util.Loadingbar]
  
Control a loadingbar with the LoadingbarControl.
+
A Loadingbar behaves like a Progressmeter that provides information on the progress of a task.
 +
 
 +
You can control a loadingbar with the LoadingbarControl.
  
 
[[File: Loadingbar.gif | center]]
 
[[File: Loadingbar.gif | center]]
  
 
<source lang="java">
 
<source lang="java">
LoadingbarControl loadingbarCtrl = Loadingbar.createLoadingbar("myId"); // create a LoadingbarControl for control the loadingbar
+
// create a LoadingbarControl for control the loadingbar
loadingbarCtrl.start() // display the loadingbar with initial value 0
+
LoadingbarControl loadingbarCtrl = Loadingbar.createLoadingbar("myId");  
loadingbarCtrl.update(20) // update the value to 20
+
loadingbarCtrl.start();
loadingbarCtrl.finish() // finish the loadingbar
+
loadingbarCtrl.update(20); // update the value to 20
 +
loadingbarCtrl.finish();
 
</source>
 
</source>
  
Line 198: Line 219:
  
 
<source lang="java">
 
<source lang="java">
loadingbarCtrl.start(20, "top", false) // display the loadingbar with initial value:20 position:top indeterminate:false
+
loadingbarCtrl.start(20, "top", false);
 
</source>
 
</source>
  
Line 211: Line 232:
 
==Animation Speed==
 
==Animation Speed==
  
To specify the value moving animation speed, [https://www.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_Library_Properties/org.zkoss.zkmax.ui.util.Loadingbar.animationSpeed org.zkoss.zkmax.ui.util.Loadingbar.animationSpeed] is provided.
+
To specify the Loadingbar animation speed, [https://www.zkoss.org/wiki/ZK_Configuration_Reference/zk.xml/The_Library_Properties/org.zkoss.zkmax.ui.util.Loadingbar.animationSpeed org.zkoss.zkmax.ui.util.Loadingbar.animationSpeed] is provided.
  
 
<source lang="xml">
 
<source lang="xml">
Line 222: Line 243:
 
=Version History=
 
=Version History=
 
{{LastUpdated}}
 
{{LastUpdated}}
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
Line 244: Line 265:
 
| Nov 2019
 
| Nov 2019
 
| [http://tracker.zkoss.org/browse/ZK-4379 ZK-4379]: Provide a Loadingbar utility
 
| [http://tracker.zkoss.org/browse/ZK-4379 ZK-4379]: Provide a Loadingbar utility
 +
|-
 +
| 9.5.0
 +
| Sep 2020
 +
| [http://tracker.zkoss.org/browse/ZK-4624 ZK-4624]: Clients API support scrollIntoView and focus by using selector string
 
|}
 
|}
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Revision as of 14:16, 12 January 2022


Useful Java Utilities


In this section we introduce some of the most commonly used Java utility classes.

Executions

org.zkoss.zk.ui.Executions

getCurrent

Executions.getCurrent()

Retrieves the current execution (request/response).

createComponents

Executions.createComponents()

With this method, you can create components defined in another zul file and attach them to the current page.

sendRedirect

Executions.sendRedirect()

Redirects to another URL. If the parameter is left null, it will redirect to the current page.


 

Sessions

org.zkoss.zk.ui.Sessions

getCurrent

Sessions.getCurrent()

Retrieves the current session.


 

Clients

org.zkoss.zk.ui.util.Clients

This class offers a collection of methods which manipulate client side via AU Response.

evalJavaScript

Clients.evalJavaScript()

This method sends an AU Response to execute the given JavaScript on client side, which is the standard way of calling JavaScript from server side in ZK. For example,

Clients.evalJavaScript("zk.log('Hi.');");

Since 9.6.0 To handle javascript error while triggered evalJavascript, org.zkoss.zk.ui.ScriptErrorListener.class is provided.


focus

Since 9.5.0 Clients.focus(Component component)

Clients.focus(String selector)

Focus the given component or the selector matched component.

scrollIntoView

Clients.scrollIntoView(Component cmp)

Scrolls the parent of the given component, so the given one becomes visible in the view.

Since 9.5.0

Clients.scrollIntoView(String selector)

Scrolls the parent of the selector matched component, so the given one becomes visible in the view.

showBusy/clearBusy

Clients.showBusy()

Clients.clearBusy()

Display/dismiss a busy icon, so user knows server is working or has finished working on something. For example,

Clients.showBusy(window, "Waiting for server...");

ZKDevRef UIPattern UsefulJavaUtil Clients showBusy.png

showNotification

Since 6.0.1 Clients.showNotification() Since 9.0.0 It is advised to use Notification class which was introduced in ZK 9 instead.

Shows a notification box, which is dismissed upon left click (like a Popup). You can either display a global notification (bigger) or a notification specific to another component (smaller with an arrow pointing to the target component).

Clients.showNotification(msg); // display a global notification box
Clients.showNotification(msg, component); // display a notification box pointing to a component

ZKDevRef UIPattern UsefulJavaUtil Clients showNotification01.png

You can also specify its position, style, and duration (for auto-dismiss):

Clients.showNotification(msg, type, component, position, duration);

Type determines the style of the notification box.

ZKDevRef UIPattern UsefulJavaUtil Clients showNotification02.png

Here are the available positions:

ZKDevRef UIPattern UsefulJavaUtil Clients showNotification03.png

Closable

Since 6.5.0 Notification now supports closable to let user close the notification box manually.

// add close icon on the top right corner of notification box
Clients.showNotification(msg, closable);

ZKDevRef UIPattern UsefulJavaUtil Clients showNotification04.png


Multiline

To show a multiline message, just append <br/> in the message string.

Clients.showNotification("msg1 <br/> msg2 <br/>");

Notification

Since 9.0.0

org.zkoss.zk.ui.util.Notification

This class offers a collection of methods showing a notification box, which is dismissed upon left click (like a Popup). You can either display a global notification (bigger) or a smaller notification specific to another component (smaller with an arrow pointing to the target component).

Notification.show(msg); // display a global notification box
Notification.show(msg, component); // display a notification box pointing to a component

Toast

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

Since 9.0.0

org.zkoss.zkmax.ui.util.Toast

This class offers a collection of methods showing a toast notification, which is dismissed upon left click (like a Popup). Unlike Notification, Toast is stackable.

ZKDevRef UIPattern UsefulJavaUtil Toast01.png

Toast.show(msg); // display a toast notification
Toast.show(msg, "warning", "top_right"); // display a toast notification on top-right of the browser viewport

You can also specify its position, style, duration (for auto-dismiss) and closable:

Toast.show(msg, type, position, duration, closable);

Here are the available positions:

left center right
top top_left top_center top_right
middle middle_left middle_center middle_right
bottom bottom_left bottom_center bottom_right

Animation Speed

To specify the duration of opening and closing animation, org.zkoss.zkmax.ui.util.Toast.animationSpeed is provided.

<library-property>
	<name>org.zkoss.zkmax.ui.util.Toast.animationSpeed</name>
	<value>500</value>
</library-property>

Loadingbar

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

Since 9.0.0

org.zkoss.zkmax.ui.util.Loadingbar

A Loadingbar behaves like a Progressmeter that provides information on the progress of a task.

You can control a loadingbar with the LoadingbarControl.

Loadingbar.gif
// create a LoadingbarControl for control the loadingbar
LoadingbarControl loadingbarCtrl = Loadingbar.createLoadingbar("myId"); 
loadingbarCtrl.start();
loadingbarCtrl.update(20); // update the value to 20
loadingbarCtrl.finish();

You can also specify its value(0~100), position(top/bottom) and indeterminate(true/false):

loadingbarCtrl.start(20, "top", false);

You can turn on/off the indeterminate animation by control the loadingbar:

Loadingbar2.gif
loadingbarCtrl.update(true); // set loadingbar indeterminate true

Animation Speed

To specify the Loadingbar animation speed, org.zkoss.zkmax.ui.util.Loadingbar.animationSpeed is provided.

<library-property>
	<name>org.zkoss.zkmax.ui.util.Loadingbar.animationSpeed</name>
	<value>500</value>
</library-property>

Version History

Last Update : 2022/01/12


Version Date Content
6.0.1 March 2012 Add Clients.showNotification()
6.5.0 July 2012 ZK-1145: Notification supports closable
9.0.0 Sep 2019 ZK-4371: Provide a Toast utility
9.0.0 Sep 2019 ZK-4372: Extract Notification functionalities from Clients
9.0.0 Nov 2019 ZK-4379: Provide a Loadingbar utility
9.5.0 Sep 2020 ZK-4624: Clients API support scrollIntoView and focus by using selector string



Last Update : 2022/01/12

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