ZK Rich Client - integration tutorial

This tutorial explains how to use a "rich client" web UI, inside OFBiz, via the ZK Rich framework (http://potix.com).  That is,

Prerequisites

1. Comfortable with installing and running OFBiz weekly build at the Windows Command Line
2. JDK 1.5, with JAVA_HOME environment variable set correctly
3. Comfortable with configuring a J2EE webapp via web.xml
4. A webapp (either your own or one of OFBiz's) already working, that you are happy to mess around with as a sandbox
5. Comfortable with creating your own OFBiz component and using ofbiz-component.xml

6. [Part 3 only] Familiarity with the Spring Framework, at least ApplicationContext and WebApplicationContext

Preparation

1. Download the latest stable binary (2.3.1 at the time of this writing) of ZK from here: http://potix.com/download/
2. Unzip this binary to a temporary directory, which we will call ZK_DIR
3. Make a shortcut to the PDFs in ZK_DIR/doc - zk-devguide.pdf is the most useful

Installing ZK framework in your OFBiz webapp

1. Copy all jars from ZK_DIR/dist/lib (but not the subdirs) onto your OFBiz classpath.  See step 2 for how to do this
2. Decide at what level you want ZK to be available....

• This webapp only: put them in webapp/WEB-INF/lib
• All webapps in this OFBiz component: put them somewhere relative to the root dir of this component (for instance lib/zk), then refer to them in your ofbiz-component.xml like so: <classpath type="jar" location="lib/zk/*"/>
• All of your webapps (sure?): put them somewhere on the framework classpath, for instance: OFBIZ_DIR/framework/base/lib3. Now we must register the various bits of the ZK engine in our webapp.   Edit your web.xml, and without removing anything you have registered, insert the following snippets...

  <!--- ZK: 1.1: servlet for ZK pages -->
   <servlet>
    <description>ZK loader for evaluating ZK 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>
  
   <!--- ZK: 1.2: map.zul and .zhtml requests to this 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>
  
   <!--- ZK: 2.1: servlet which handles client-server comms -->
   <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>auEngine</servlet-name>
    <url-pattern>/zkau/*</url-pattern>
   </servlet-mapping>
  
  
   <!--- ZK: 3: make sure the browser will treat relevant file types correctly -->
   <mime-mapping>
    <extension>js</extension>
    <mime-type>application/x-javascript</mime-type>
   </mime-mapping>
   <mime-mapping>
    <extension>zhtml</extension>
    <mime-type>text/html</mime-type>
   </mime-mapping>
   <mime-mapping>
    <extension>zul</extension>
    <mime-type>text/html</mime-type>
   </mime-mapping>
  

  4. Restart OFBiz and check that nothing nasty comes out in the logs! Part 1 - your first ZUL pageNow we're going to make a very simple page using ZUML (the ZK User Interface Markup Language).  In my firm we call these "ZULs", after the file extension, since it is much easier to say than ZUML.1. Create a file hello.zul in the root of your webapp (the directory referenced by the location attribute of the relevant <webapp/> tag in your ofbiz-component.xml).2. Paste the following code into it: