ZK Configuration Reference/zk.xml/The device-config Element

It specifies a device. A device represents a client. Different clients have different implementation. Currently there are two types: ajax and mil. They represents the Web browsers with Ajax, and the mobile device with Mobile Interactive Language. It is used to create an instance returned by the getDevice method of the Desktop intereface.

The allowed child element is device-type , device-class, timeout-uri, and unavailable-message. You might have multiple device-config elements in one zk.xml.

 <device-config>
     <device-type>ajax</device-type>
     <device-class>my.MyAjaxDevice</device-class>
     <timeout-uri>/my-timeout.zul</timeout-uri>
     <server-push-class>my.ServerPush</server-push-class>
     <unavailable-message><![CDATA[
 <p style="color:red">Sorry, JavaScript must be enabled in order for you to use KillApp.</p>
     ]]></unavailable-message>
     <embed><![CDATA[
 <script type="text/javascript">
     AU_progressbar = function (id, msg) {
         Boot_progressbox(id, msg, 0, 0, true, true);
     };
 </script>
     ]]></embed>
 </device-config>

Note: Unlike most other configurations defined in WEB-INF/zk.xml, the definitions defined in device-config are applied to all Web applications sharing the same zk.jar. Refer to the zscript-config element for more information.

Notes

The device-class Element

[Optional]

It specifies the implementation class. The class must implement the Device interface. Instead of implementing it from scratch, you can derive from the proper implementation, such as AjaxDevice and MilDevice.

The device-type Element

[Required]

It specifies the device type. The previous implementation with the same device type will be replaced if any.

The embed Element

[Optional][Multiple]

It specifies the content that shall be added to the output generated and sent to the client when rendering a desktop. The syntax of the content depends on the client. For Ajax clients, it can be any tags that can be placed inside HTML HEAD tag, such as SCRIPT, META and others.

For example, if you want to show the progress bar in the center of the browser window, you can specify the following in zk.xml.

<device-config>
	<device-type>ajax</device-type>
	<embed><![CDATA[
 <script type="text/javascript">
     AU_progressbar = function (id, msg) {
         Boot_progressbox(id, msg, 0, 0, true, true);
     };
 </script>
     ]]></embed>
</device-config>

You can specify multiple embed elements and their content be concatenated together.

The server-push-class Element

[Optional][Default: depends on device and what edition you use]

It specifies which class used to implement the server-push feature. The class must have a default constructor (without any argument), and implement the ServerPush interface.

 <device-config>
     <device-type>ajax</device-type>
     <server-push-class>my.ServerPush</server-push-class>
 </device-config>

In addition to configuring the application's default implementation, you can choose an implement for a particular class by use of DesktopCtrl.enableServerPush(ServerPush). For example,

((DesktopCtrl)desktop).enableServerPush(new org.zkoss.zk.ui.impl.PollingServerPush());

The timeout-uri Element

[Optional]
[Default: null]
[Deprecated since 3.6.3, use  session-config instead]

It specifies the target URI that will be used to redirect users to, when the desktop no longer exists – it is usually caused by session timeout. If this element is omitted, an error message will be shown up at the browser to alert users for what happens.

To reload the same URI again, you can specify an empty content as follows.

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

The unavailable-message Element

[Optional][Default: depends on device]

It specifies the message that will be displayed if the client doesn't support this device.