Developer reference Appendix B. WEB-INF/zk.xml Library Properties

From Documentation

Here is a list of properties that ZK depends on.

How to Define

To define a library property, you can configure it in WEB-INF/zk.xml. The library-property Element for more information. For example,

<library-property>
	<name>org.zkoss.zul.Button.mold</name>
	<value>trendy</value>
</library-property>

Alternatively, you can define it as a system property with the configuration file of your Web server, though the system property affects the whole system, not just one Web application.

class.extension

Default: none
[Since 5.0.0]

It specified the implementation class used to extend the specified component. The property name is a concatenation of the class name of the component and extension. For example, the property for the gid's extension is org.zkoss.zul.Grid.extension.

The implementation must implement the org.zkoss.zk.ui.util.Extension interface.

class.mold

Default: none
[Since 5.0.0]

It specified the default mold of the specified component. The property name is a concatenation of the class name of the component and mold. For example, the property for the button's default mold is org.zkoss.zul.Button.mold.

org.zkoss.net.URLEncoder

Default: java.net.URLEncoder
[Since 3.6.3]

It defines the class that implements the org.zkoss.net.URLEncoder interface. By default, it uses java.net.URLEncoder(s, "UTF-8") to encode the URL string. However, if you want to use a different encoder, you can implement one and specifiy with this property.

org.zkoss.util.label.classpath.charset

Default: UTF-8
[since 3.6.0]

It defines the charset used to encode i3-label.properties if the file is located in classpath.

org.zkoss.util.label.web.charset

Default: UTF-8
[since 3.6.2]

It defines the charset used to encode i3-label.properties if the file is located in a Web application.

Prior to 3.6.2, the property is called org.zkoss.util.label.WEB-INF.charset.

org.zkoss.util.label.web.location

Default: /WEB-INF/i3-label.properties
[Since 3.6.2]

It specifies where i3-label.properties are named and located.

org.zkoss.util.logging.realCauseBriefly

Default: 6
[Since 3.6.1]

It defines the number of lines to log an error message.

If nonpostive is specified, the full stack traces are logged. Notice that # of lines don't include packages starting with java, javax, sun, or bsh.

org.zkoss.util.logging.warningBriefly

Default: 3
[Since 3.6.1]

It defines the number of lines to log a warniing message.

If nonpostive is specified, the full stack traces are logged. Notice that # of lines don't include packages starting with java, javax, sun, or bsh.

org.zkoss.web.classWebResource.cache

Default: true
[Since 3.6.3]

It specifies whether to allow the browsers to cache the so-called class Web resources^[1].

By default, it is true. It means the static class Web resources are cached in browsers if possible, unless you upgrade ZK to a different version.

Notice the you can control the immutable period of the CSS files of class Web resources with
another property called org.zkoss.web.classWebResource.cache.CSS.hours.

If you are developing a component, it is better to turn it off (so you can force browser to load modified CSS and JS files by pressing F5).

<library-property>
	<name>org.zkoss.web.classWebResource.cache</name>
	<value>false</value>
</library-property>

---

1. ↑ Class Web resources are resources that can be loaded by use of "~./*".

org.zkoss.web.classWebResource.cache.CSS.hours

Default: 8760
[Since 3.6.3]

It specifies the number of hours in that period the CSS files of class Web resources won't be changed.

By default, it is 8760 (the same as other class Web resources). Notice that the resource is reloaded. If you want to turn off the cache of the CSS files of class Web resources, you can specify a non-positive value.

<library-property>
	<name>org.zkoss.web.classWebResource.cache.CSS.hours</name>
	<value>8760</value>
</library-property>

org.zkoss.web.util.resource.dir

Default: none
[Since 5.0.0]

It specifies a directory, where ZK will load the so-called Class-Web Resources (CWR), in addition to the class path. CWR includes JavaScript files, CSS files, and other resources that are specified in the form of ~./xxx.

By default, ZK only searches the class path for the required CWR. By specifying a directory here, ZK will search the directory first and then the class path. It implies a developer can override the default behavior by providing a file with the same name.

Notice: don't put security sensitive files in the directory specified here, since they can be accessed externally.

org.zkoss.web.servlet.http.URLEncoder

Default: javax.servlet.http.HttpServletResponse.encodeURL
[Since 5.0.0]

It specifies the class used to encode URL by including the session ID and the Servlet's context path, if necessary. The specified class must implement the org.zkoss.web.servlet.http.Encodes.URLEncoder interface.

In a sophisticated environment, e.g., Reverse Proxy, the encoded URL might have to be prefixed with some special prefix. To do that, you can implement the org.zkoss.web.servlet.http.Encodes.URLEncoder interface, and then specify the class with this library property.

org.zkoss.zkmax.ui.EventQueueProvider.class

Default: none
[Enterprise Edition]
[since 5.0.0]

It specifies the name of the class used to provide the event queue. The class must implement the org.zkoss.zkmax.ui.eq.impl.EventQueueProvider interface.

org.zkoss.zkmax.zul.FiledownloadListener.class

Default: none
[Enterprise Edition]
[Since 3.5.0]

It specifies the name of the class that will be notified when a file download is happening. The class must implement the org.zkoss.zkmax.zul.FiledownloadListener interface.

A developer usually uses it to reject a download if the user tried to resume it in an unacceptable situation. For example, a developer can limit the user from downloading within upcoming 24 hours.

org.zkoss.zul.client.rod

Default: true
[Enterprise Edition]
[since 5.0.0]

It specifies whether to apply Client Render on Demand.

Notice that you can enable or disable this feature a particular component and all its descendants by specifying a custom attribute called org.zkoss.zul.client.rod.

org.zkoss.zul.include.mode

Default: defer (3.x)
Default: auto (5.0)
[Since 3.6.2]

It specifies the default mode of the include component. In ZK 3, the default mode is defer, which is backward-compatible with the prior version. Since ZK 5, the default mode is auto for easier control.

org.zkoss.zul.progressbox.position

Default: left, top
[Since 5.0.1]

It specifies how to display the progress box at the client. The progress box is a message used to indicate the AU requests have being processed by the server. By default, it is displayed at the left, top corner.

Here is a list of allowed values. If you want to specify two of them, separate them with a comma, such as left,top.

org.zkoss.zul.theme.browserDefault

Default: false (override browser default)
[Since 3.6.0]

It specifies whether not to override the standard HTML tags, such as body's margin and padding.

org.zkoss.zul.theme.fontFamilyC

Default: Verdana, Tahoma, Arial, Helvetica, sans-serif
[Since 3.6.0]

It specifies the font used for the content in the ZUL CSS file.

org.zkoss.zul.theme.fontFamilyT

Default: Verdana, Tahoma, Arial, serif
[Since 3.6.0]

It specifies the font used for the title in the ZUL CSS file.

org.zkoss.zul.theme.fontSizeM

Default: 12px
[Since 3.6.0]

It specifies the size of the middle font used in the ZUL CSS file.

org.zkoss.zul.theme.fontSizeMS

Default: 11px
[Since 3.6.0]

It specifies the size of the middle-smaller font used in the ZUL CSS file.

org.zkoss.zul.theme.fontSizeS

Default: 11px
[Since 3.6.0]

It specifies the size of the smaller font used in the ZUL CSS file.

org.zkoss.zul.theme.fontSizeXS

Default: 10px
[Since 3.6.0]

It specifies the size of the extreme small font used in the ZUL CSS file.