From Wikibooks, open books for an open world
< ZK‎ | How-Tos
Jump to navigation Jump to search

Installation and Configuration[edit | edit source]

Tomcat[edit | edit source]

Install ZK on Tomcat

1. Download Tomcat from http://tomcat.apache.org and install it, if you haven't installed it yet. (Tested by using link http://localhost or http://localhost:8080)

2 Stop Tomcat

3. Unzip zk-*.zip or zk-*.tar.gz

4. Copy dist/lib/*.jar,dist/lib/zkforge/*.jar and dist/lib/ext/*.jar to the $TOMCAT_HOME/shared/lib ($TOMCAT_HOME is where your tomcat installed). Don't use a subfolder structure within the $TOMCAT_HOME/shared/lib folder.

5. Start Tomcat

6. Browse to http://localhost/manager or http://localhost:8080/manager and deploy demo/bin/zkdemo.war to Tomcat or by copying it to $TOMCAT_HOME/webapps directly. If you prefer copying directly, you have to stop Tomcat first. If the file is missing, get zksandbox.war instead.

7. Browse to http://localhost/zkdemo/userguide, or http://localhost:8080/zkdemo/userguide, or http://localhost:8080/zksandbox/, depending on your configuration for Tomcat.

Tomcat 4.1[edit | edit source]

ZK works with Tomcat 4.1 seamlessly since version 3.0 because it no longer depends on the JSP 2.0 technology.

If you are using older version of ZK before 3.0, you have to copy jsp-api.jar to $TOMCAT_HOME/common/lib. The jsp-api.jar file can be found in Tomcat's download, or Subversion.

Tomcat 5.0.30[edit | edit source]

The ZK's logger not support Tomcat 5.0.30 version.

Tomcat 5.5 installed on Ubuntu 7.10 Security Policy Configuration[edit | edit source]

Thank to Ed Clement

To fix: java.security.AccessControlException: access denied (java.util.PropertyPermission org.zkoss.util.resource.checkPeriod read) [followed by stacktrace]

1) Open the Tomcat web applications permission file. In my case this was located at /etc/tomcat5.5/policy.d/04webapps.policy (Not sure how much this location or the file name will very) 2) I added the following lines to the bottom of the file:

//added for zkdemo webapp 
grant codeBase "file:${catalina.home}/webapps/zkdemo/-" { 
permission java.security.AllPermission; 

3) Save the file and restarted tomcat (not sure if this was needed but I did it anyway)

Obviously this solution should work for an zk webapp, you will just need to change the "zkdemo" to the name of the web application you are trying to deploy/run.

Apache + Tomcat[edit | edit source]


Tomcat Authentication[edit | edit source]

ISSUE: Executions.getCurrent().getRemoteUser() return null.

SOLUTION: Enable Tomcat Authentication Configuration


      <description>Authorized Users Group</description>


    <description>Test role</description>


  <user name="testuser" password="testpassword" roles="test"/>

Resin[edit | edit source]

1. Download Resin from http://caucho.com/download/index.xtp and install it, if you haven't installed it yet.

2. Stop Resin

3. Unzip zk-1.0.0.zip or zk-1.0.0.tar.gz

4. Copy dist/lib/*.jar to $RESIN_HOME/lib ($RESIN_HOME is where you installed Resin.)

5. Copy dist/lib/ext/*.jar to $RESIN_HOME/lib

6. [Optional] Copy dist/lib/zkforge/*.jar to $RESIN_HOME/lib (It depends whether you need component from ZK Forge)

7. Deploy demo/bin/zkdemo.war to Resin by copying it to $RESIN_HOME/webapps directly.

8. Start Resin.

9. Browse to http://localhost/zkdemo/userguide or http://localhost:8080/zkdemo/userguide, depending on your configuration.

by Peter Manchev

Jetty[edit | edit source]

1. Download Jetty from http://www.mortbay.org/jetty/index.html and install it, if you haven't installed it yet.

2. Stop Jetty.

3. Unzip zk-1.x.x.zip or zk-1.x.x.tar.gz

4. Copy dist/lib/*.jar to $JETTY_HOME/lib

  ($JETTY_HOME is where you installed Jetty.)

5. Copy dist/lib/ext/*.jar to $JETTY_HOME/lib

6. [Optional] Copy dist/lib/zkforge/*.jar to $JETTY_HOME/lib

  (It depends whether you need component from ZK Forge)

7. Deploy demo/bin/zkdemo.war to Jetty by copying it to $JETTY_HOME/webapps directly.

8. Start Jetty.

9. Browse to http://localhost/zkdemo/userguide or http://localhost:8080/zkdemo/userguide, depending on your configuration.

JBoss 4.0 and above[edit | edit source]

1. Download Jboss from http://www.jboss.com/downloads/index and install it,if you haven’t installed

2. Test the Jboss using link http://localhost:port, if it’s OK stop the server.

3. Unzip zk-2.2.0-RC.zip or zk-2.2.0-RC.tar.gz

4. Copy dist/lib/*.jar and dist/lib/*/*.jar to the $JBOSS_HOME/server/default/lib

5. Copy zkdemo.war to $JBOSS_HOME/server/default/deploy

6. Start the server.

7. Browse to http://localhost/zkdemo/userguide or http://localhost:8080/zkdemo/userguide depending on you configuration for Jboss.

by Juan Jose Buendia Mardones (Chile)

JBoss 3.2.2 + tomcat 4.1[edit | edit source]

1. follow the instruction to install ZK Ajax on tomcat 4.1.

2. Download the files:

  and copy them to the lib directory under default. 

3. Change the web.xml so that it will fit servlet 2.3 specifications.

4. We are still working on some problems and I will update this record when I'll have the full solution.

When I tried the solution given by Mars Chen some of the components built upon the Jboss platform didn't function anymore. When doing my solution however one of the ZK components (the upload file) didn't work. But for now I did a workaround to use tomcat 5.5 in the background.

by Yaniv Ran (USA)

2.1 There I got another simple solution: using ZK distribution's bsh.jar into JBoss lib directory to replace bsh-core-version.jar.

Please refer BeanShell official site. == http://www.beanshell.org/download.html == The bsh-version.jar contains all files in bsh-core-version.jar.

by Mars Chen (Taiwan)

Oracle OC4J and Oracle OPMN Release 3[edit | edit source]

Intro: OC4J 10.1.3 (release 3) is the first production version of Oracle Containers For Java to support J2EE 1.4 specification (Servlet 2.4). Prior versions, supports only J2EE 1.3 (with Servlet 2.3) and ZK will not work with this versions.

1. Download OC4J 10.1.3 or later from http://www.oracle.com and install it.

2. You must setup OC4J to run with the -userThreads parameter at the command line (oc4j.cmd, on OPMN this is done inside the opmn.xml <data id="oc4j-options" value="-userThreads" />)

3. Unzip zk-1.2.0-2006-04-07.zip or later version

4. Copy dist/lib/*.jar and dist/lib/ext/*.jar to the $OC4J_HOME/j2ee/home/applib

5. Start OC4J server and enter a new oc4jadmin's password if prompted or restart the server if it is already up

6. Open "Enterprise Manager" application - just browse to http://localhost:8888/em/

7. Login as oc4jadmin and go to Applications --> Deploy page

8. Deploy zkdemo.war (follow the on-screen instructions)

9. Browse to http://localhost:8888/zkdemo/userguide

  • Substitute "/zkdemo" with the context uri you entered in EM during deployment
  • Start OC4J Server:
  bin/oc4j -start

BEA WebLogic[edit | edit source]

Note: This install guide is for Windows.

1. Download Weblogic 9.1 from [1]

2. Start the Weblogic installer and accept all defaults.

3. Once the default installation is complete, create a weblogic domain by clicking Start->Programs->BEA products->Tools->Configuration Wizard.

4. Select "Create New Weblogic Domain" and click Next.

5. Accept the defaults on "Select Domain Source" and click Next.

6. Enter a password in "Configure Administrator Username and Password" and click Next.

7. Accept all defaults on "Configure Server Start Mode and JDK" and click Next.

8. Select No on Configure Environment Setting and Services" and click Next.

9. Accept all defaults on "Create Weblogic Domain and click Create.

10. Once the domain is created, check the check box labeled "Start Admin Server" and click Done.

11. The server will start up.

12. The HTTP port is default to 7001 unless you change it.

The easiest way to deploy your application is to copy your war/ear (it could be in an exploded format) to the autodeploy directory under the weblogic installaton directory. If you followed the instruction above that directory is located at C:\bea\user_projects\domains\base_domain\autodeploy. When you place your war/ear file in that directory, weblogic will detect it and do a hot deployment.

If you want to copy ZK libraries to the domain, put them under c:/bea/user_projects/domains/base_domain/lib

Libraries that have to be copied include bsh.jar commons-fileupload.jar commons-el.jar pxcommon.jar pxweb.jar zk.jar zul.jar zhtml.jar

IBM WebSphere quick start[edit | edit source]

1.IBM offers a websphere application server community edition, go to http://www-128.ibm.com/developerworks/downloads/ws/wasce/?S_TACT=105AGX10&S_CMP=WASCE to download it.
2.follow the instruction to download, you might need to register for an account if you don't already have one.
3. under downloads, choose Server and 32bit IBM SDK 1.4.2 SR4-1, procees to download.
4. start the installer and accepts all defaults.
5. once installation is completed, go to All Programs->IBM Websphere->Application Server->Profiles->Default->Start the Server, this will start the server.
6. Browse http://localhost:9060/ibm/console/secure/logon.do to deploy application
7. After deployed, applications can be access via http://localhost:9080/myapp for additional documentation and tutorials, go to http://publib.boulder.ibm.com/wasce/Front_en.html

Eclipse[edit | edit source]

How To Setup Eclipse Wtp For ZK

How To Setup Eclipse Wtp And XAMPP For ZK

see also: http://www.zkoss.org/smalltalks/eclipse/ek.html

How to setup the zul.xsd schema into Eclipse[edit | edit source]

  1. You should have setup Eclipse to work with ZK. The details is in the above smalltalk.
  2. Execute the Eclipse SDK.
  3. Select Window/Preferences... from the menu and the Preferences dialog popup.
  4. Select XML/XML Catalog from the left sidebar tree menu and the right side is the XML Catalog panel.
  5. Select User Specified Entries in the XML Catalog Entries field and press the Add... button.
  6. The Add XML Catalog Entry dialog now popup:
  7. Now you should see a new entry http://www.zkoss.org/2005/zul/zul.xsd under the User Specified Entires.
  8. Done.

How to generate ZUL files from the ZUL schema using Eclipse[edit | edit source]

  1. You should have setup the zul.xsd schema into Eclipse.
  2. Select File/New/Other... from the Eclipse SDK menu and the New dialog popup.
  3. In Select a wizard page, select XML/XML from the tree menu and press Next > button.
  4. In Create XML File page, select Create XML file from an XML schema file and then press Next > button.
  5. In XML File Name page, type or select a proper parent folder for your project. It is generally under the WebContext folder of your project. Then type in the ZUL file name you want to create(e.g. helloworld.zul) and press Next > button.
  6. In Select XML Schema File page, select Select XML catalog entry option. You should see the http://www.zkoss.org/2005/zul/zul.xsd in the XML Catalog list. Now select the entry and press Next > button.
  7. In Select Root Element page:
    • In Root Element field, pick a proper root element. In most ZK applications, it is generally a window or an zk element.
    • In Content options field, you can leave as is.
    • In Namespace Information field, you can select the entry and press edit... button to take out the prefix or change the prefix.
    • Press Finish button.
  8. The ZUL file is created and opened on an XML editor window.
  9. Now you can start editing your ZUL file. Press Alt-/ to open the Content Assist popup window to help you fill up proper ZUL elements and attributes.
  10. Done.

How to setup Eclipse to work with zhtml[edit | edit source]

  1. Select Window/Preferences... from the Eclipse SDK menu and the Preferences dialog will popup.
  2. Select General and Content Types Catalog from the left sidebar tree menu and the right side is the Content Types panel.
  3. Select Text and XML in the Content types and press the Add... button .
  4. Add *.zhtml or such as *.zul, *.jsp, *.html etc.
  5. Finally, you can press the RightClick on your file and choose the XML editor in the Open With menu.
  6. Done.

How to setup the Rational Application Developer RAD version of Eclipse to work with zhtml[edit | edit source]

  1. Select Window/Preferences... from the SDK menu and the Preferences dialog will popup.
  2. Select Workbench/File Associations then click on the top Add to add a file type *.zhtml
  3. Click on the lower Add and select HTML Source Page Editor and set it to be default
  4. Done

Installing Liferay (on tomcat) and a ZK Portlet[edit | edit source]

Liferay installation[edit | edit source]

There are several way in which you can do this, one is to goto Liferay and download the pre-bundled liferay tomcat bundled. This is the easiest method, but of course not ideal if you have a pre-existing tomcat server.

If you have a tomcat server already and don't particularly feel like deploying another one, you can download the liferay war. Liferay's installation typically removes the ROOT from the server, but I don't particularly like doing that so I'll explain with out having to loose your root

  • First, if you don't have tomcat, download and install the latest stable tomcat on the OS of your pleasure (you can try other app servers but experience has taught me other ones might be trickier to begin with as the configuration is usually more lengthy).
  • Next download the non-bundled liferay war (Liferay Portal Professional 4.2.1 WAR) from Liferay
  • Also download the additional file called Liferay Portal 4.2.1 Dependencies, and unzip it to shared/lib
  • In order to keep your ROOT you'll need to extract the contents of the war into a folder, call it 'myportal' fo instance.
  • Under the WEB-INF folder create a 'classes' folder, in this folder create a file called 'portal-ext.properties', in the file put the following (note you may of course change the portal.ctx and/or the lucene and jackrabbit directory depending on your later configurations):
  • Go back into the WEB-INF folder and edit the web.xml change the root_path to have a param value of '/myportal', so the top of the web.xml will look as follows:
<?xml version="1.0"?>

<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4">
		<filter-name>Auto Login Filter</filter-name>
  • Now go into the META-INF folder and add a file called 'context.xml' and add the following (configure this to your own specifics just make sure the context path attribute is '/myportal', if you don't use mysql database and just want liferay to use hSQLdb, just strip out the first Resource element):
<Context path="/myportal" reloadable="true" >
  • Now for the real trick, liferay 4.2 has a small bug when you change the context to something other than the ROOT. In the folder html/portal you will find a file called load_render_portlet.jsp, open the file up and go to line 55-56should look as follows:
			function <%= namespace %>loadPortlet() {
				var path = "/c/portal/render_portlet";

however it should look as follows:

			function <%= namespace %>loadPortlet() {
				var path = "/myportal/c/portal/render_portlet";

Ok I'm sure there is a better way of doing that, but I'd rather let the liferay boys do that themselves.

  • If you wish to use mySQL, you'll need to modify the context.xml to your own configurations, you'll also need to download the liferay-mysql script file and run it against your database.
  • Now on you root folder (i.e. C:\ for windows, / for UNIX/LINUX) you'll need to create a 'home' folder (if it doesn't exist) and in that a 'liferay' folder. Make sure tomcat has permission to modify the folder.
  • Now all you need do is re zip the folder and rename the zip file to myportal.war, drop it into tomcat's webapps deploy directory and (hopefully) you have a working liferay portal.

Deploying a ZK portlet[edit | edit source]

Here I'll assume you are familiar with and have created a ZK war.

  • First, you need to tell liferay about your portlet so create a class that looks like this:
 * Copyright (c) 2000-2006 Liferay, LLC. All rights reserved.
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.

package za.co.mypackage.portlet;

import java.io.IOException;

import javax.portlet.ActionRequest;
import javax.portlet.ActionResponse;
import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.PortletRequestDispatcher;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

 * @author  Brian Wing Shun Chan
 * @modified Glenn Keith
public class JSPPortlet extends GenericPortlet {

	public void init() throws PortletException {
		editJSP = getInitParameter("edit-jsp");
		helpJSP = getInitParameter("help-jsp");
		viewJSP = getInitParameter("view-jsp");

	public void doDispatch(RenderRequest req, RenderResponse res)
		throws IOException, PortletException {

		String jspPage = req.getParameter("jspPage");

		if (jspPage != null) {
			include(jspPage, req, res);
		else {
			super.doDispatch(req, res);

	public void doEdit(RenderRequest req, RenderResponse res)
		throws IOException, PortletException {

		if (req.getPreferences() == null) {
			super.doEdit(req, res);
		else {
			include(editJSP, req, res);

	public void doHelp(RenderRequest req, RenderResponse res)
		throws IOException, PortletException {

		include(helpJSP, req, res);

	public void doView(RenderRequest req, RenderResponse res)
		throws IOException, PortletException {

		include(viewJSP, req, res);

	protected void include(String path, RenderRequest req, RenderResponse res)
		throws IOException, PortletException {

		PortletRequestDispatcher prd =

		if (prd == null) {
			_log.error(path + " is not a valid include");
		else {
			prd.include(req, res);

	protected String editJSP;
	protected String helpJSP;
	protected String viewJSP;

	private static Log _log = LogFactory.getLog(JSPPortlet.class);

  • Next in your WEB-INF create a 'liferay-display.xml' file that looks as follows:
<?xml version="1.0"?>
<!DOCTYPE display PUBLIC "-//Liferay//DTD Display 4.0.0//EN" "http://www.liferay.com/dtd/liferay-display_4_0_0.dtd">

	<category name="category.test">
		<portlet id="portletone" />
  • Now also in the WEB-INF create a file called 'liferay-portlet.xml' that looks as follows:
<?xml version="1.0"?>
<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 4.1.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_4_1_0.dtd">

		<role-link>Power User</role-link>
  • Now again in WEB-INF create a 'portlet.xml' file that looks as follows:
<?xml version="1.0"?>

<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd" version="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd">
		<display-name>Sample JSP Portlet</display-name>
			<title>Sample JSP Portlet</title>
			<short-title>Sample JSP Portlet</short-title>
			<keywords>Sample JSP Portlet</keywords>
  • You'll note the /view.zul reference in this file is the 'index' file of the portlet, also note throughout all these file I have referenced 'portletone', you'll need to change this to the name of your war.
  • Finally at the top of your web.xml file after <web-app> add the following (followed by the typical ZK stuff):


You'll notice I left the company_id as liferay.com. I've left it like this because changing the value also means digging around the liferay database, it's not that hard to find all the place to modify the value, so if you do, your on your own.

  • Deploy the resulting war into /home/liferay/deploy directory,
  • Access and sign in to your portal, click on 'Add Content' link, under the category 'Test' add 'Sample JSP Portlet'.

Hey presto, one portal with ZK portlet

Pluto[edit | edit source]

Deploy a ZK Porlet[edit | edit source]


Define the definition of porlet in web.xml

<display-name>ZK Portlets</display-name> 
<description>ZK loader for ZUML pages</description> 
<load-on-startup>1</load-on-startup><!-- Must --> 

<description>The asynchronous update engine for ZK</description> 


2) portlet.xml

Define a ZK portlet in portlet.xml.

<description>ZKloader for ZUML pages</description> 
<display-name>ZK Portlet Loader</display-name> 

How to resolve Session Timeout[edit | edit source]

The cause of this problem is that ZK cannot find the desktop from its session. Why? ZK desktop was stored in the session of pluto instead of ZK webapp because pluto pass its session to ZK webapp while doing cross-context in Tomcat. This breaks the spec of servlet. So far, there is no good solution. But here is a workaround that ZK stores desktop in application scope instead of session scope to avoid the problem. Please add the following lines in your zk.xml