ZK Configuration Reference/web.xml/ZK Loader

Location: WEB-INF/web.xml

[Required] Class: DHtmlLayoutServlet

DHtmlLayoutServlet is a servlet used to load ZUML pages when the Web server receives URL requests sent by users.

Notice that you must specify load-on-startup since many other servlets depend on the ZK loader.

<load-on-startup>1</load-on-startup>

It is suggested to map this servlet to the zul and zhtml extensions as shown below. It is OK if you want to map xul and html, too.

	<servlet>
		<description>ZK loader for evaluating ZUML pages</description>
		<servlet-name>zkLoader</servlet-name>
		<servlet-class>org.zkoss.zk.ui.http.DHtmlLayoutServlet</servlet-class>
		<init-param>
			<param-name>update-uri</param-name>
			<param-value>/zkau</param-value>
		</init-param>
		<load-on-startup>1</load-on-startup><!-- MUST -->
	</servlet>
	<servlet-mapping>
		<servlet-name>zkLoader</servlet-name>
		<url-pattern>*.zul</url-pattern>
	</servlet-mapping>
	<servlet-mapping>
		<servlet-name>zkLoader</servlet-name>
		<url-pattern>*.zhtml</url-pattern>
	</servlet-mapping>

The Initial Parameters

init-param	Descriptions
update-uri	[Required] It specifies the URI which the ZK AU engine is mapped to. For example, if the ZK AU engine is mapped to /zkau/*, by use of servlet-mapping, then specify /zkau for this parameter. Note: if the servlet container is used with other Web server, like Apache, you have to map this update URI to the servlet container (in additions to zul and zhtml files).
compress	[Optional][Default:true] It specifies whether to compress the output if the browser supports the compression (Accept-Encoding) and this Servlet is not included by other Servlets.
log-level	[Optional] It specifies the default log level for org.zkoss. If not specified, the system default (usually INFO) is used. Possible values: OFF, ERROR, WARNING, INFO, DEBUG and FINER. Refer to the Beyond ZK chapter in the Developer's Guide.

Map URL to Richlets

Assume you have a [[ZK Developer's Reference/UI Composing/Richlet|richlet] named foo.FooRichlet. Then, you could configure it as follows.

First, declare the richlet:

<richlet>
    <richlet-name>Foo</richlet-name>
    <richlet-class>foo.FooRichlet</richlet-class>
</richlet>

Second, map the richlet to any number of URL you want:

<richlet-mapping>
    <richlet-name>Foo</richlet-name>
    <url-pattern>/foo</url-pattern>
</richlet-mapping>
<richlet-mapping>
    <richlet-name>Fest</richlet-name>
    <url-pattern>/some/more/*</url-pattern>
</richlet-mapping>

Notice that, by default, richlets are disabled. To enable them, add the following declaration to web.xml. Once enabled, you can add as many as richlets as you want without modifying web.xml any more. Of course, url-pattern could be any pattern you prefer.

<servlet-mapping>
    <servlet-name>zkLoader</servlet-name>
    <url-pattern>/zk/*</url-pattern><!-- any pattern you prefer -->
</servlet-mapping>

Then, you can visit http://localhost:8080/PROJECT_NAME/zk/foo to request the richlet.

The URL specified in the url-pattern element must start with /. If the URI ends with /*, then it is matched to all request with the same prefix. To retrieve the request's actual URL, you can check the value returned by the Page.getRequestPath.

Version History

Version	Date	Content