From Documentation

Before You Start

New to Servlet Containers (aka., Java Web Server)?

Before developing Web applications in Java (and running ZK demo in your machine), you need to install a Servlet container. Apache Tomcat is one of the most popular Servlet containers due to the ease in which it can be installed and used.

New to the Java Language?

You don't need to know Java to use ZK, since all rich user interfaces can be implemented in a HTML-like markup language called ZUML. However, to complete a Web application, you or your teammates need some basic Java knowledge.

Here are some good Java tutorials.

Preparing an environment to run ZK

Prerequisites

If you haven't installed the following applications on your computer, please download and install them first.

• Java SE Development Kit (JDK)
• Application Server
• ZK Library

Obtaining the Java SE Development Kit (JDK)

1. Download JDK 6 Update 14.

2. Follow the Installation instructions to complete the installation.

Obtaining an application server - Apache Tomcat

1. Download Apache Tomcat 6.0
2. Follow the Apache Setup instructions to complete the installation.

Notice: We suggest you use the port number 8080.

Obtaining the ZK Library

1. From ZK Studio 0.9.4, it is bundled with latest stable ZK library, currently ZK3.6.1.
2. Download the latest version of the ZK library.
3. Unzip zk-bin-xxx.zip to your HDD, (e.g. C:\), please refer here for a list of files and directories included in the ZK distribution.

Preparing the Eclipse IDE (Recommended)

Installing Eclipse

1. Download, and install Eclipse IDE for Java EE Developers

Installing ZK Studio

Follow the step by step Installation Guide to install ZK Studio.

Defining a Server RunTime (Apache Tomcat)

1. From menu goto Windows > Preferences...
2. Select Server > Runtime Environments, then click Add
3. Select Apache > Apache Tomcat v6.0 and click Next
4. Browse to and select your Apache Tomcat root directory e.g. C:\Program Files\Apache Software Foundation\Tomcat 6.0
5. Click Finish

Configuring the ZK Library

Since ZK Studio is already bundled with the ZK library(for example, ZK 3.6.1) so you do not have to configure it. For further information, please refer to How to Import ZK library

Running a sample application

No installation required

Visit ZK Demo to experience the simplicity and richness of ZK right NOW!

Running a sample application

Notice: Make sure you have installed the following packages:

1. Java JDK
2. An Application Server (Tomcat)
3. Eclipse (OPTIONAL)

IF you have NOT installed these packages please refer to the previous chapter.

Downloading the ZK demo

1. Download zk-demo-3.6.1.zip.
2. Unzip zk-demo-3.6.1.zip, to say C:\

Running the sample application without an IDE

1. Copy zkdemo.war (eg. C:\zk-demo-3.6.1\zkdemo.war). to the $TOMCAT_HOME\webapps directory.
2. Start Apache Tomcat.
3. Open your browser and navigate to http://localhost:8080/zkdemo/userguide.

---

For server supporting only Servlet 2.3 (such as Tomcat 4), you have to replace WEB-INF/web.xml with WEB-INF/web.servlet-2.3.xml

Running the sample application with an IDE

1. Select File > Import .
2. In the Import dialog, select Web > WAR file and then click Next.
3. Using the Browse button to locate zkdemo.war (e.g. C:\zk-demo-3.6.1\zkdemo.war).
4. Click Finish to import the Web Project.
5. Right click on zkdemo project in the explorer and select Run As > Run on Server
6. Select Apache > Tomcat v6.0 Server in the server type dialog and click Finish
7. A browser will be activated, and click ZK Demo hyperlink to explore zkdemo.

Running the sample application on other application servers

IBM WebSphere

BEA WebLogic

JBoss

Oracle OC4J and Oracle OPMN Release 3

Liferay

Pluto

Jetty

Resin

Creating a "hello world" application from scratch (without IDE)

Creating a web project

Follow the project structure below and create the directory structure within $TOMCAT_HOME\webapps, for example MyApp (eg.C:\Program Files\Apache Software Foundation\Tomcat 6.0\webapps\MyApp\).

+MyApp 
    +WEB-INF 
       +lib
       web.xml
       zk.xml
  index.zul

Deploying the ZK library

Copy the following jar files to $TOMCAT_HOME\webapps\PROJECT NAME\WEB-INF\lib

zk-bin-3.6.0\dist\lib\*.jar
zk-bin-3.6.0\dist\lib\ext\*.jar
zk-bin-3.6.0\dist\lib\zkforge\*.jar

Creating the "web.xml" file

Copy the following lines into $TOMCAT_HOME\webapps\PROJECT NAME\WEB-INF\web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
  <display-name>MyApp</display-name>
  <listener>
  	<description>
  	Used to cleanup when a session is destroyed</description>
  	<display-name>
  	ZK Session Cleaner</display-name>
  	<listener-class>org.zkoss.zk.ui.http.HttpSessionListener</listener-class>
  </listener>
  <servlet>
  	<description>
  	The servlet loads the DSP pages.</description>
  	<servlet-name>dspLoader</servlet-name>
  	<servlet-class>
  	org.zkoss.web.servlet.dsp.InterpreterServlet</servlet-class>
  </servlet>
  <servlet>
  	<description>
  	ZK loader for 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>
  </servlet>
  <servlet>
  	<description>
  	The asynchronous update engine for ZK</description>
  	<servlet-name>auEngine</servlet-name>
  	<servlet-class>
  	org.zkoss.zk.au.http.DHtmlUpdateServlet</servlet-class>
  </servlet>
  <servlet-mapping>
  	<servlet-name>dspLoader</servlet-name>
  	<url-pattern>*.dsp</url-pattern>
  </servlet-mapping>
  <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>
  <servlet-mapping>
  	<servlet-name>auEngine</servlet-name>
  	<url-pattern>/zkau/*</url-pattern>
  </servlet-mapping>
  <welcome-file-list>
    <welcome-file>index.html</welcome-file>
    <welcome-file>index.htm</welcome-file>
    <welcome-file>index.jsp</welcome-file>
    <welcome-file>default.html</welcome-file>
    <welcome-file>default.htm</welcome-file>
    <welcome-file>default.jsp</welcome-file>
    <welcome-file>index.zul</welcome-file>
  </welcome-file-list>
</web-app>

Create the "zk.xml" file

Copy the following lines into $TOMCAT_HOME\webapps\PROJECT NAME\WEB-INF\zk.xml

<?xml version="1.0" encoding="UTF-8"?>
 
<!--
	Created by ZK Studio
-->
 
<zk>
 
</zk>

Creating your first web page

Create index.zul under $TOMCAT_HOME\webapps\PROJECT NAME\ and copy the following lines into it.

 <window title="My First window" border="normal" width="200px"> 
 Hello, World! 
 </window>

Running your application

1. Start Apache Tomcat.
2. Navigate to http://localhost:8080/MyApp/.

Creating a "hello world" application from scratch (with an IDE)

Notice: Make sure you have installed Java JDK, Application Server, and ZK Studio on your computer or you have to refer to the previous chapter.

Creating a new "ZK Project"

With the release of ZK Studio you no longer have to create a new Dynamic Web Project and configure the settings for ZK! You can create a new ZK Project, choose your ZK Package and sit back while ZK Studio does the rest for you.

The following swf demonstrates how to create a new ZK project using Eclipse 3.4 and ZK Studio:

For detailed steps, please refer to Create a New ZK Project

Creating a new ZUL file

1. Right click on the WebContent folder in the Project Explorer view or the Package Explorer view and select New > ZUL.

2. Type index.zul in the File name textbox and click Finish.

3. The newly created ZUL File will be opened in the ZUL Editor.

Running the ZUL file

1. Right click on the MyApp project in explorer and in the Menu dialog select Run As > Run on Server

2. Select Apache > Tomcat v6.0 Server in server type dialog and then click Finish

3. See the result in your browser.

Creating a real world application with a dataBase

Refer to this article.

Appendix A. The content of the binary distribution

This chapter describes the content of ZK library.

/doc

This directory holds documents including copyrights and release notes.

/dist/lib

This directory holds the binary libraries required to run ZK.

/dist/lib/zkforge

This directory holds the components from ZK Forge, such as FCKeditor. It is optional depending on whether you need them.

/dist/lib/ext

This directory holds the external libraries required to run ZK. Since these libraries are common, you might have installed them in your container.

Here are the optional jar files. You can choose whether to copy them over, depending on your requirements.

/dist/src

This directory holds the source code in JAR format. These JAR files are used for debugging in an IDE, such as Eclipse. You cannot build the binary libraries from these files, if you want to build the binary library from the source please download and uncompress zk-src-3.5.2.tar.gz.

/dist/xsd

This directory holds the XSD files that might be useful to develop ZK applications.

/dist/WEB-INF

This directory holds the TLD files. These TLD files are part of JAR files so they are loaded automatically. We put them here for your reference only.

Appendix B. The content of the demo distribution

This chapter describes the content of zk-demo-3.5.2.zip.

/

This directory holds the executable: zkdemo.war, zkdemo-min.war, zkdemos.ear and zkdemos-min.ear. Refer to the Installation chapter for details.

/zkdemo

This directory holds the source code of the live demo.

/MyApp

This directory holds an empty Web application which you can start your new Web application from.