The Library Properties

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.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 called org.zkoss.zul.Button.mold.

<library-property>
	<name>org.zkoss.zul.Button.mold</name>
	<value>trendy</value>
</library-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 nonpositive 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 warning message.

If nonpositive 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>

↑ 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.classWebResource.cache.etag

Default: false
[Since 5.0.1]

It specifies whether to use ETag to detect and return 304 for matched resource.

If turned on, the cached resource won't be reloaded if the user presses F5 to reload.

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.

For example, assume we have a JavaScript package called foo.great and we want to put it to WEB-INF/cwr. Then, we have to specify the following in WEB-INF/zk.xml:

	<library-property>
		<name>org.zkoss.web.util.resource.dir</name>
		<value>/WEB-INF/cwr</value>
	</library-property>

Then, you can place zk.wpd and required JavaScript files under the WEB-INF/cwr/js/foo/great directory.

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 Encodes.URLEncoder interface.

If the clients are far away from the server, you might override this class by encoding the URL of JavaScript and CSS files with a server nearby. Thus, it could shorten the time to load a page. For more information, please refer to Performance Tips.

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 Encodes.URLEncoder interface, and then specify the class with this library property.

org.zkoss.zk.ui.EmulateIE7

Default: false
[since 5.0.2]

It specifies whether to make Internet Explorer 8 running in IE7 compatible mode. It is used if some of your JavaScript code doesn't work well in IE8.

Refer to Introducing IE=EmulateIE7

org.zkoss.zk.ui.event.EventQueueProvider.class

Default: none (it implies EventQueueProviderImpl)
[since 5.0.0]

It specifies the name of the class used to provide the event queue. The class must implement the EventQueueProvider interface.

org.zkoss.zk.ui.input.grouping.allowed

Default: true
[since 5.0.5]

Turn on/off whether the user is allowed to key in the grouping character when entering a number. The grouping character depends on the Locale. For example, it is a comma in English, and a dot in Germany. By default, ZK will allow the user to key in the grouping characters and the grouping characters are simply ignored when the input is parsed to a number.

Some people still get confused whether the application considers a comma as a decimal point or not, when he is new to the application. By disabling the entering of the grouping character will help in this case.

<library-property>
	<name>org.zkoss.zk.ui.input.grouping.allowed</name>
	<value>false</value>
</library-property>

If you want to disable it only for a particular page, you could specify it in the page's attribute (note: the page must be the root page). For example,

<zk>
<custom-attributes org.zkoss.zk.ui.input.grouping.allowed="false" scope="page"/>
<doublebox/>
</zk>

org.zkoss.zk.ui.macro.autoforward.disabled

Default: false
[since 5.0.4]

Turn on/off auto forward mechanism for macro component

<library-property>
	<name>org.zkoss.zk.ui.macro.autoforward.disabled</name>
	<value>true</value>
</library-property>

org.zkoss.zk.ui.macro.autowire.disabled

Default: false
[since 5.0.4]

Turn on/off auto wire mechanism for macro component

<library-property>
	<name>org.zkoss.zk.ui.macro.autowire.disabled</name>
    	<value>true</value>
</library-property>

org.zkoss.zk.ui.metainfo.page.Loader.class

Default: none
[since 5.0.4]

It specifies the name of the class used to load the page definitions. The class must implement the Loader interface and it must have a constructor as follows.

public FooLoader(org.zkoss.zk.ui.WebApp wapp) { //assume FooLoader is the implementation class
     ...

The default iimplementation is straightforward:

private static class MyLoader extends org.zkoss.web.util.resource.ResourceLoader {
	private final WebApp _wapp;
	private MyLoader(WebApp wapp) {
		_wapp = wapp;
	}

	//-- super --//
	protected Object parse(String path, File file, Object extra)
	throws Exception {
		final Locator locator =
			extra != null ? (Locator)extra: getLocator(_wapp, path);
		return new Parser(_wapp, locator).parse(file, path);
	}
	protected Object parse(String path, URL url, Object extra)
	throws Exception {
		final Locator locator =
			extra != null ? (Locator)extra: getLocator(_wapp, path);
		return new Parser(_wapp, locator).parse(url, path);
	}
}

org.zkoss.zk.ui.uuidRecycle.disabled

Default: false (i.e., UUID recycle is enabled)
[since 5.0.3]

It specifies whether to disable the recycle of UUID. By recycling UUID will reduce the memory use of the browser. It is enabled by default.

org.zkoss.zk.ui.sys.XMLResourcesLocator.class

Default: none (it implies ClassLocator)
[since 5.5.0]

It specifies the name of the class used to load metainfo/config.xml, metainfo/lang.xml and metainfo/lang-addon.xml. By default, they are loaded from the class path. If you prefer to load them from other location, implement the XMLResourcesLocator interface.

Notice that you can specify the property in WEB-INF/zk.xml, since it is too late. Rather, you have to specify in the server's configuration (as a system property).

org.zkoss.zkplus.embed.updateURI

Default: /zkau
[Since 5.0.5]

It specifies the URI of the update engine. It is used when using a so-called embedded component. An embedded component is a native, say, JSF component that is implemented by embedding ZK components.

For more information, please refer to Embed ZK Component in Foreign Framework.

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 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.listbox.checkmarkDeselectOthers

Default: false
[Since 5.0.5]

If a listbox's checkmark (Listbox.isCheckmark()) is enabled, the selection will be toggled when an user clicks an item. In other words, all other items will remain the same.

If you prefer to deselect all other items and select the item being clicked (which the behavior of ZK 5.0.4 and earlier), you could specify true to this library property.

org.zkoss.zul.listbox.rightSelect

Default: true
[Since 5.0.5]

If a listbox's checkmark (Listbox.isCheckmark()) is enabled, the selection will be toggled when user right click on item.

If you prefer not to select/deselect item on right click, you could specify false to this library property.

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.

Allowed Values
Value	Description
bottom	Align the progress box at the bottom edge of the browser window.
center	Align the progress box at the center of the browser window. If it is used with left and top, it means the center in the vertical orientation.
left	Align the progress box at the left edge of the browser window.
mouse	Align the progress box near by the mouse pointer. If specified, it ignores all other values.
right	Align the progress box at the right edge of the browser window.
top	Align the progress box at the top edge of the browser window.

org.zkoss.zul.theme.browserDefault

Default: false (override browser default with ours)
[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: arial, 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: arial, sans-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.

org.zkoss.zul.tree.checkmarkDeselectOthers

Default: false
[Since 5.0.5]

If a tree's checkmark (Tree.isCheckmark()) is enabled, the selection will be toggled when an user clicks an item. In other words, all other items will remain the same.