The client-config Element

From Documentation


The client-config Element


It is used to customize the behavior of the ZK Client Engine. You might have multiple client-config elements in one zk.xml.

 <client-config>
     <click-filter-delay>0</click-filter-delay>
     <debug-js>false</debug-js>
     <disable-behind-modal>false</disable-behind-modal>
     <error-reload>
         <device-type>ajax</device-type>
         <error-code>301</error-code>
         <reload-uri></reload-uri>
     </error-reload>
     <keep-across-visits>true</keep-across-visits>
     <processing-prompt-delay>900</processing-prompt-delay>
     <tooltip-delay>800</tooltip-delay>
     <resend-delay>9000</resend-delay>
 </client-config>


The click-filter-delay Element

[Default: 0]
Since 3.0.9 and 3.5.3

It specifies the time, in milliseconds, to filter out consecutive click events. If two click events (including onOK and onCancel) come too close (within the specified delay), the second one will be removed to avoid the denial-of-service attack. A non-positive value turns off this feature.

Prior to ZK 3.5.3, it is default to 390, which means it filters out the second click event if it happens within 390 milliseconds.

The debug-js Element

[Default: false]

It specifies whether to debug JavaScript files. By default, it is false and the compressed version of JavaScript files will be loaded. They are hard to read and debug, though the footprint is much smaller.

To debug JavaScript files, you can specify it to true. Then, the original uncompressed JavaScript files will be loaded instead.

The disable-behind-modal Element

[Default: false]

It specifies whether to disable all elements behind the modal window at the browser. If disabled, the performance is better.

Tip: This option can be considered as obsolete since 3.0.4. The user is almost impossible to change focus to an element behind the modal window, without disabling them.

Note: in ZK 3.0.3 and earlier, the option is default to true.

The error-reload Element

[Default: show an error message]

It specifies what URI to redirect the browser to. For example, if you prefer to redirect to the login page, say, login.zul, you can specify the following in zk.xml:


 <error-reload>
     <device-type>ajax</device-type>
     <error-code>301</error-code>
     <reload-uri>/login.zul</reload-uri>
 </error-reload>
 <error-reload>
     <device-type>ajax</device-type>
     <error-code>402</error-code>
     <reload-uri>/login.zul</reload-uri>
 </error-reload>
 <error-reload>
     <device-type>ajax</device-type>
     <error-code>410</error-code>
     <reload-uri>/timeout.zul</reload-uri>
     <connection-type>server-push</connection-type>
 </error-reload>

connection-type

Optional Default: au [Since 3.6.3]

Specifies the connection type. It can be either au or server-push. By default, it is au which are the Ajax reqests sent by the widgets running at the client.

If you want to specify the error page for the server push (comet-based), you have to specify server-push as shown in the example below

device-type

Optional Default: ajax [Since 3.6.3]

Specifies the device type. By default, it is ajax. If you want to configure for ZK Mobile, use mil.

error-code

Required

Specifies the error code, aka., the server status code; see RFC 2068.

For server-push (comet-based), there is an important error code called 410. It is received when the session is timeout (or the serve is restarted). If you want to notify user about this, you can specify something similar to the following.

<error-reload>
	<device-type>ajax</device-type>
	<error-code>410</error-code>
	<reload-uri>/timeout.zul</reload-uri>
	<connection-type>server-push</connection-type>
</error-reload>

reload-uri

Required

Specifies the URI to reload if the specified error occurs.

If the content of reload-uri is empty, the browser simply reloads the same page again.

 <reload-uri></reload-uri>

If you want to show an error message instead, specify false.

 <reload-uri>false</reload-uri>

The keep-across-visits Element

[Default: false]

It specifies whether to keep the desktop when a user reloads an URL or browses away to another URL. Since browsers won't cache HTML pages generated by ZK, ZK removes a desktop as soon as the user reloads the URL or browses to another URL.

However, you have to specify keep-across-visits with true, if you use the server-side cache for the HTML pages generated by ZK. An example of the server side cache is OpenSymphony CacheFilter.

 <client-config>
     <keep-across-visits>true</keep-across-visits>
 </client-config>

Note: When working with Opera, ZK always keeps the desktop (until the number of desktops exceed the allowed maximal number), since Opera is smart enough to preserve the most updated content and always reuses the cached page.

The package Element

[Default: none][since 5.0.0]

It defines a client package (JavaScript) and all of its sub packages that are provided by this server. Use this configuration if some client packages might be loaded from different servers, such as Ajax-as-a-Service.

For example, if this server provides the client packages for foo.fly.*, then the following shall be specified to enable Ajax-as-a-Service.

<client-config>
	<package>
		<package-name>foo.fly</package-name>
	</package>
</client-config>

The processing-prompt-delay Element

[Default: 900]

It specifies the time, in milliseconds, to wait before prompting the user with a dialog indicating that the request is in processing.

The resend-delay Element

[Default: 9000 if ZK EE[1], -1 otherwise]

It specifies the time, in milliseconds, to wait before resending the AU requests to the server. There are many reasons an AU request is not received by the server. For example, the server may drop the connection if it is overloaded. To ensure the reliability, ZK will abort the previous request and then resend the request, if the specified delay expires.

Since 3.0.3, you can specify a non-positive number to disable the resend mechanism.


Notes

  1. More precisely, 9000 if ZK EE is installed.

The tooltip-delay Element

[Default: 800]

It specifies the time, in milliseconds, to wait before popping up the tooltip when the user moves the mouse pointer over particular UI components.

Version History

Version Date Content
     



Last Update : 2010/07/14

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