Session Timeout Management"

From Documentation
m
 
(26 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
  
−
After a session is timeout, all desktops and UI objects it belongs are removed. If a user keeps accessing the desktop that no longer exists, ZK will prompt the user for the session-timeout situation. ZK supports several ways to prompt the user for session timeout:
+
After a session times out, all desktops and UI objects it belongs are removed. If a user keeps accessing the desktop that no longer exists, ZK will prompt the user for the session-timeout situation. ZK supports several ways to prompt the user for session timeout:
  
−
* Show an error message
+
* Show a message
 
* Redirect to another page
 
* Redirect to another page
−
* Totally Control by running JavaScript code
+
* Totally control by running JavaScript code
  
−
You could pick one depending on your application requirement. In additions, you could configure your application to enforce the user prompting to take place, without waiting the user's activity. It is called automatic timeout.
+
You could pick one depending on your application requirement. In addition, you could configure your application to enforce the user prompting to take place, without waiting for the user's activity. It is called automatic timeout.
 +
 
 +
=Show a Message=
 +
 
 +
By default, a message is shown to prompt the user and prevent from further accessing as depicted below.
 +
 
 +
[[File:DrSessTimeout.png]]
 +
 
 +
==Custom Message==
 +
 
 +
You could show a custom message by specifying [[ZK_Configuration_Reference/zk.xml/The_session-config_Element#The_timeout-message_Element|<code>timeout-message</code>]] in <code>WEB-INF/zk.xml</code>. For example,
 +
 
 +
<source lang="xml">
 +
<session-config>
 +
<device-type>ajax</device-type>
 +
<timeout-message>Session timeout. Please reload.</timeout-message>
 +
</session-config>
 +
</source>
 +
 
 +
=== Internationalization ===
 +
 
 +
If you want to specify a Locale-dependent message, you could specify the key and prefix it with <code>label:</code> as follows.
 +
 
 +
<source lang="xml">
 +
<session-config>
 +
<device-type>ajax</device-type>
 +
<timeout-message>label:timeout</timeout-message>
 +
</session-config>
 +
</source>
 +
 
 +
Then, you have to prepare the zk-label properties files as described in the [[ZK_Developer%27s_Reference/Internationalization/Labels|Labels]] section.
 +
 
 +
<source lang="text">
 +
#zk-label.properties
 +
timeout={
 +
Session timeout.
 +
(multi-line is allowed)
 +
}
 +
</source>
  
−
=Show an Error Message=
 
 
=Redirect to Another Page=
 
=Redirect to Another Page=
−
Sometimes it is better to redirect to another page that gives users more complete description and guides they to the other resources, or asks them to login again. You can specify the target URI, that you want to redirect users to when timeout, in zk.xml under WEB-INF directory. For example, the target URI is /timeout.zul and then you can add the following lines to zk.xml.
+
Sometimes it is better to redirect to another page that gives users a more complete description and guides them to the other resources, or asks them to login again. You can specify the target URI, that you want to redirect users to when timeout, with [[ZK_Configuration_Reference/zk.xml/The_session-config_Element#The_timeout-uri_Element|the timeout-uri element]] in <code>WEB-INF/zk.xml</code>. For example, the target URI is /timeout.zul and then you can add the following lines to zk.xml.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 20: Line 57:
 
</source>
 
</source>
  
−
'''Tip''': Each device has exactly one timeout URI. For more information about zk.xml, refer to Appendix B in the Developer's Reference
+
In addition to <code>WEB-INF/zk.xml</code>, you could change the redirected URI manually as follows.
−
 
 
−
In addition to zk.xml, you can change the redirect URI manually as follows.
 
  
 
<source lang="java" >
 
<source lang="java" >
Line 28: Line 63:
 
</source>
 
</source>
  
−
About Device: A device represents the client device. Each desktop is associated with one device, and vice versa.
+
<blockquote>
 +
----
 +
About Device: A device represents the client device, such as Ajax browsers and Android devices. Each desktop is associated with one device, and vice versa.
 +
</blockquote>
  
 
If you prefer to reload the page instead of redirecting to other URI, you can specify an empty URI as follows.
 
If you prefer to reload the page instead of redirecting to other URI, you can specify an empty URI as follows.
Line 38: Line 76:
 
</session-config>
 
</session-config>
 
</source>
 
</source>
 +
 +
=Total Control in JavaScript=
 +
 +
If you want more amazing effect, you could provide some JavaScript code and configure ZK to run it if timeout. For example, [http://www.zkoss.org/zkdemo our demo] shows up a message on the top of window with some animation, and then automatically reloads if it detects any mouse move (it means the user is back).
 +
 +
For example, if you have a function called <code>foo.timeout</code> to handle the timeout effect, then you could configure <code>WEB-INF/zk.xml</code> as follows.
 +
 +
<source lang="xml">
 +
<session-config>
 +
    <device-type>ajax</device-type>
 +
    <automatic-timeout>true</automatic-timeout>
 +
    <timeout-message>script:<![CDATA[foo.timeout('Session Timeout');]]></timeout-message>
 +
</session-config>
 +
</source>
 +
 +
The code depends on the client. For Ajax devices, it has to be JavaScript.
  
 
=Automatic Timeout=
 
=Automatic Timeout=
 +
 +
By default, the session-timeout mechanism is triggered only if the client sends back a request (such as clicking on a button). If you prefer to prompt the user even if it doesn't do anything, you could specify the [[ZK_Configuration_Reference/zk.xml/The_session-config_Element#The_automatic-timeout_Element|automatic-timeout element]] in <code>WEB-INF/zk.xml</code> as follows.
 +
 +
<source lang="xml">
 +
<session-config>
 +
<device-type>ajax</device-type>
 +
<automatic-timeout/>
 +
</session-config>
 +
</source>
 +
 +
Then, ZK Client will trigger the session-time mechanism (showing a message, redirecting to another page, or running some JavaScript code).
 +
 +
== Page-level Automatic Timeout ==
 +
 +
If you want to specify whether to automatically timeout for particular pages, you can use [[ZUML Reference/ZUML/Processing Instructions/page#automaticTimeout | the page directive]].
 +
 +
Moreover, it is better to turn off the automatic timeout for the timeout page you want to redirect to (if the page is a ZUML page). For example,
 +
 +
<source lang="xml">
 +
<!-- my timeout page -->
 +
<?page automaticTimeout="false"?>
 +
...
 +
</source>
 +
 
=Never Timeout=
 
=Never Timeout=
−
You can also prevent the session timeout by making a "keep-alive" timer. Set in zk.xml:
+
Though not recommended, you could prevent the session from timeout by making a "keep-alive" timer, such that the desktop keeps alive until the user surfs away.
 +
 
 +
To do that, you first configure WEB/zk.xml as follows.
  
 
<source lang="xml" >
 
<source lang="xml" >
Line 49: Line 129:
 
</source>
 
</source>
  
−
and make a timer in your ZUL page:
+
and create a timer in your ZUL page:
  
 
<source lang="xml" >
 
<source lang="xml" >
−
<timer id="timerKeepAliveSession" repeats="true" delay="10000"/>
+
<timer id="timerKeepAliveSession" repeats="true" delay="600000" onTimer=""/>
 
</source>
 
</source>
  
−
This will prevent the session to time out when the ZUL page is opened in the borwser. The session still timeouts when the user has navigated the browser away (or when the connection between browser and the server is broken). Instead of 10sec delay, you may set the <code>timerKeepAliveSession</code> more flexible, like <code>session.getMaxInactiveInterval() * 100</code>.
+
This will prevent the session to time out when the ZUL page is opened in the browser. The session still timeouts when the user has navigated the browser away. The delay (600000 is 10 minutes) shall be as long as possible but smaller than your session timeout.
 +
 
 +
The [[ZK_Configuration_Reference/zk.xml/The_session-config_Element#The_timer-keep-alive_Element|timer-keep-alive]] element is used to specify whether the session shall consider timer as a normal request. If it is considered as a normal request, the session timeout mechanism will be restarted when it is received. Otherwise, the timer, by default, won't restart the timeout mechanism.
  
 
=Version History=
 
=Version History=
−
{{LastUpdated}}
+
 
−
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
−
| &nbsp;
+
| 5.0.5
−
| &nbsp;
+
| October 2010
−
| &nbsp;
+
| The support of Custom Message and JavaScript was introduced.
 
|}
 
|}
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 04:06, 31 January 2024


DocumentationZK Developer's ReferenceUI PatternsSession Timeout Management
Session Timeout Management


After a session times out, all desktops and UI objects it belongs are removed. If a user keeps accessing the desktop that no longer exists, ZK will prompt the user for the session-timeout situation. ZK supports several ways to prompt the user for session timeout:

  • Show a message
  • Redirect to another page
  • Totally control by running JavaScript code

You could pick one depending on your application requirement. In addition, you could configure your application to enforce the user prompting to take place, without waiting for the user's activity. It is called automatic timeout.

Show a Message

By default, a message is shown to prompt the user and prevent from further accessing as depicted below.

DrSessTimeout.png

Custom Message

You could show a custom message by specifying timeout-message in WEB-INF/zk.xml. For example, 

<session-config>
	<device-type>ajax</device-type>
	<timeout-message>Session timeout. Please reload.</timeout-message>
</session-config>

Internationalization

If you want to specify a Locale-dependent message, you could specify the key and prefix it with label: as follows. 

<session-config>
	<device-type>ajax</device-type>
	<timeout-message>label:timeout</timeout-message>
</session-config>

Then, you have to prepare the zk-label properties files as described in the Labels section. 

#zk-label.properties
timeout={
Session timeout.
(multi-line is allowed)
}

Redirect to Another Page

Sometimes it is better to redirect to another page that gives users a more complete description and guides them to the other resources, or asks them to login again. You can specify the target URI, that you want to redirect users to when timeout, with the timeout-uri element in WEB-INF/zk.xml. For example, the target URI is /timeout.zul and then you can add the following lines to zk.xml. 

<session-config>
    <device-type>ajax</device-type>    
    <timeout-uri>/timeout.zul</timeout-uri>    
</session-config>

In addition to WEB-INF/zk.xml, you could change the redirected URI manually as follows. 

Devices.setTimeoutURI("ajax", "/timeout.zul");

About Device: A device represents the client device, such as Ajax browsers and Android devices. Each desktop is associated with one device, and vice versa.

If you prefer to reload the page instead of redirecting to other URI, you can specify an empty URI as follows. 

<session-config>
    <device-type>ajax</device-type>    
    <timeout-uri></timeout-uri>    
</session-config>

Total Control in JavaScript

If you want more amazing effect, you could provide some JavaScript code and configure ZK to run it if timeout. For example, our demo shows up a message on the top of window with some animation, and then automatically reloads if it detects any mouse move (it means the user is back).

For example, if you have a function called foo.timeout to handle the timeout effect, then you could configure WEB-INF/zk.xml as follows. 

<session-config>
    <device-type>ajax</device-type>
    <automatic-timeout>true</automatic-timeout>
    <timeout-message>script:<![CDATA[foo.timeout('Session Timeout');]]></timeout-message>
</session-config>

The code depends on the client. For Ajax devices, it has to be JavaScript.

Automatic Timeout

By default, the session-timeout mechanism is triggered only if the client sends back a request (such as clicking on a button). If you prefer to prompt the user even if it doesn't do anything, you could specify the automatic-timeout element in WEB-INF/zk.xml as follows. 

<session-config>
	<device-type>ajax</device-type>
	<automatic-timeout/>
</session-config>

Then, ZK Client will trigger the session-time mechanism (showing a message, redirecting to another page, or running some JavaScript code).

Page-level Automatic Timeout

If you want to specify whether to automatically timeout for particular pages, you can use the page directive.

Moreover, it is better to turn off the automatic timeout for the timeout page you want to redirect to (if the page is a ZUML page). For example, 

<!-- my timeout page -->
<?page automaticTimeout="false"?>
...

Never Timeout

Though not recommended, you could prevent the session from timeout by making a "keep-alive" timer, such that the desktop keeps alive until the user surfs away.

To do that, you first configure WEB/zk.xml as follows. 

<session-config>
  <timer-keep-alive>true</timer-keep-alive>
</session-config>

and create a timer in your ZUL page: 

<timer id="timerKeepAliveSession" repeats="true" delay="600000" onTimer=""/>

This will prevent the session to time out when the ZUL page is opened in the browser. The session still timeouts when the user has navigated the browser away. The delay (600000 is 10 minutes) shall be as long as possible but smaller than your session timeout.

The timer-keep-alive element is used to specify whether the session shall consider timer as a normal request. If it is considered as a normal request, the session timeout mechanism will be restarted when it is received. Otherwise, the timer, by default, won't restart the timeout mechanism.

Version History

Version Date Content
5.0.5 October 2010 The support of Custom Message and JavaScript was introduced.



Last Update : 2024/01/31

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


Retrieved from "https://www.zkoss.org/_w/index.php?title=ZK_Developer%27s_Reference/UI_Patterns/Session_Timeout_Management&oldid=56659"