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

It is used to customize how ZK handles desktops. You might have multiple desktop-config elements in one zk.xml.

 <desktop-config>
     <desktop-timeout>3600</desktop-timeout>
     <disable-theme-uri>~./zul/css/norm*.css.dsp*</disable-theme-uri>
     <file-check-period>5</file-check-period>
     <extendlet-check-period>10</extendlet-check-period>
     <theme-uri>/my/blue**.css</theme-uri>
     <theme-provider-class>my.MyThemeProvider</theme-provider-class>
 </desktop-config>

The desktop-timeout Element

[Default: 3600]

It specifies the time, in seconds, between client requests before a desktop is invalidated. A negative time indicates the desktop should never timeout.

The disable-theme-uri Element

[Default: none]

It specifies what theme URI to be disabled. The theme URI shall be one of the default theme URI. For example, the following statement disables the generation of the default theme URI for the ZK XUL component set.

 <desktop-config>
     <disable-theme-uri>~./zul/css/zk.wcs</disable-theme-uri>
 </desktop-config>

It is usually used with the theme-uri element to replace the default theme. Please refer to ZK Developer's Reference for more details about theming and styling.

Also notice that implementing a theme provider is a more controllable alternative.

The extendlet-check-period Element

[Default: -1 (never expired)]

It specifies the time, in seconds, to wait before checking whether a resource loaded by an extendlet is modified. An extendlet is a processor to load the resources usually located in classpath, such as ~./zul/desktop.dsp.

Resources located in classpath are usually packed as a JAR file, so they are immutable and not need to check if modified. However, in a development environment, you might want to check if they are deployed without reloading the JAR files.

The file-check-period Element

[Default: 5]

It specifies the time, in seconds, to wait before checking whether a file is modified.

For better performance, ZK has employed a cache to store parsed ZUML file. The time specified here controls how often ZK checks whether a file is modified. The larger the number the better the performance.

The id-to-uuid-prefix Element

[Default: none]
[Since 3.6.1]
[deprecated 5.0.3]

It specifies whether to generate UUID based on ID. It is useful for testing purpose, such that the generated UUID is predictable. For example, the following causes the UUID to be generated by prefixing ID with _zid_.

<desktop-config>
	<id-to-uuid-prefix>_zid_</id-to-uuid-prefix>
</desktop-config>

Then, the following component's UUID will be _zid_foo.

<textbox id="foo"/>

Notice that UUID has to be unique in the whole desktop, so the above setting might cause the application unable to run (due to replicated UUID). You can minimize the possibility of ID conflicts by prefixing with page's UUID as follows.

<desktop-config>
	<id-to-uuid-prefix>_zid_${page}_</id-to-uuid-prefix>
</desktop-config>

Then, ${page} will be replaced with the page's UUID (if the page is available). However, since a page might still have several ID space, the UUID conflict is still possible.

The repeat-uuid Element

[Default: false]
[Since 3.6.0]

It specifies whether to use the same UUID sequence for desktops for each reboot. By default, it is turned off so the desktop's UUID is completely different after reboot. It helps to avoid the consistency between the browser and the server. However, it is useful to turn this option on if you want to debug and test the application.

The theme-uri Element

[Default: none]

It specifies the URI of an addition theme (aka., a style sheet file).

Like other URI, it accepts "*" for loading browser and Locale dependent style sheet. Refer to the Browser and Locale Dependent URI section in the Internationalization chapter for details.

You can specify any number of them-uri as follows.

 <desktop-config>
     <theme-uri>/my/blue**.css</theme-uri>
     <theme-uri>/my/second.css</theme-uri>
 </desktop-config>

If you want to replace a default theme, you have to use theme-uri with disable-theme-uri. Please refer to ZK Developer's Reference for more information.

Notice:

1. All style sheets defined in lang.xml and lang-addon.xml are loaded, no matter this parameter is defined or not. It is convenient for developers to override certain styles.
2. Each JAR could specify a lang-addon.xml file (under the metainfo/zk directory), so you could specify style sheets there if you have more than one style sheets.
3. You could specify extra CSS files for individual ZUML pages by use of the style component. Refer to the ZUML with the XUL Component Set chapter.

The theme-provider-class Element

[Default: none]

It specifies the class to provide the theme (aka., a style sheet file) URI dynamically. If you want to determine the theme based on the current user, cookie or locale. You can implement a class with the ThemeProvider interface, and specify it with the theme-provider-class element. Then, an instance of the class will be created, and it is called each time a desktop is rendered to the client to determine the theme URI.

Notice that the theme provider is called with all theme URIs that shall be generated (including what are specified in theme-uri and excluding what are specified in disable-theme-uri). And, only the return collection of URIs are actually generated. In other words, the theme provider has the highest priority.

Version History

Version	Date	Content