Author
Dennis Chen, Engineer, Potix Corporation

Date
Aug. 24, 2007

Version
Applicable to zk-2.5.0-FL-2007-08-22 and later.

Applicable to JSF 1.1

Applicable to JSP 2.0

Introduction

JSF (JavaServer Faces), a technology simplifies building user interfaces for JavaServer applications. Compare to JSF with ZK, both are UI component framework on JavaServer application, JSF is page base solution and ZK has different way on ajax base. It seems you can’t choose both JSF and ZK in one page and cooperated together. But now, ZK provides a set of JSF components which wrap ZK components, and implement the features of JSF like ValueBinding, Converter, Validator, etc. In this article we will demonstrate you how to use ZK JSF Component. Use ZK JSF Components to enrich your JSF Application – a conference room reservation demo

In this demonstration, we show you a mixed usage on ZK JSF Components with ajax and page submitting. First JSF page provides a form to reserve a conference room. When you change the conference room you can see the content changed directly by ajax, and you can popup a quick query window to know what time of the conference room is free.

When you submit the first page, it checks/processes the data in the JSF way. If failed, return to the first page and show you the failing reason. If passed, the submitted data is updated to a backing bean and forwarded to second page which show you the information in backing bean. You can run this demo on the Conference Room Reservation Example in the zkjsf-demo. The runtime result will be like below.

Demo

Simple Example of using ZK JSF Components

To use ZK JSF Components is as easy as to use ZK Components. We will show you in this section.

The Fileupload Demo on ZKDemo

In ZK demo site,http://www.zkoss.org/zkdemo/userguide/, a file-uploading demo whose code is as below:

<window title="fileupload demo" border="normal">
	<button label="Upload">
		<attribute name="onClick">{
			Object media = Fileupload.get();
			if (media instanceof org.zkoss.image.Image) {
				Image image = new Image();
				image.setContent(media);
				image.setParent(pics);
			} else if (media != null)
				Messagebox.show("Not an image: "+media, "Error", Messagebox.OK, Messagebox.ERROR);
		}</attribute>
	</button>
	<vbox id="pics"/>
</window>

You can upload an image and show it on the browser with ajax.

3 steps to use ZK JSF Component

To use ZK JSF Components, just 3 steps need to be done in your JSF page.

Declare a tag library(or namespace) http://www.zkoss.org/jsf/zul

Ex:<%@ taglib uri="http://www.zkoss.org/jsf/zul" prefix="z"%>

Write component tag with a tag library (or namespace) prefix.

Ex:<z:button label="Upload">

Use a Page component to contain any other ZK JSF Components

A JSF page doing the upload demo with ZK JSF Components will be like follow:

<HTML>
<HEAD>
<title>Simple Example</title>
</HEAD>
<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<%@ taglib uri="http://www.zkoss.org/jsf/zul" prefix="z"%>
<f:view>
	<z:page>
		<z:window title="fileupload demo" border="normal">
			<z:button label="Upload">
			<z:attribute name="onClick">{
				Object media = Fileupload.get();
				if (media instanceof org.zkoss.image.Image) {
				Image image = new Image();
				image.setContent(media);
				image.setParent(pics);
				} else if (media != null)
				Messagebox.show("Not an image: "+media, "Error",
					Messagebox.OK, Messagebox.ERROR);
				}
			</z:attribute>
			</z:button>
			<z:vbox id="pics"/>
		</z:window>		
	</z:page>
</f:view>
</body>
</HTML>

You can run this demo on the Simple Example in the zkjsf-demo. The runtime result will be like below.

Binding to a Backing Bean

Since you can use ZK component in JSF now, we provide more JSF features on It. One of JSF’s features we have impelemnted is javax.faces.component.EditableValueHolder. When a component implement this interface, it means this component can bind value from/to a Backing Bean, and process data conversation and validation when page submitted.

Not all ZK JSF Components implement EditableValueHolder, only the input components do. Below are the components which implement EditableValueHolder. Data Type is the Class of binding target, for example, the Class of the ‘name’ in UserBean is String. Binding Attribute is the attribute of ZK Component which will be set when wrapping it. For example, in the case of input component, such as Textbox, it means the text value which user inputs. In the case of selection component , such as Listbox, it means the selected item’s value.

ZK JSF Component	Data Type of ValueBinding	Binding Attribute of ZK Component
Bandbox	String	value
Calendar	Date	value
Checkbox	Boolean	checked
Combobox	String	value
Datebox	Date	text
Decimalbox	BigDecimal	text
Doublebox	Double	text
Intbox	Integer	text
Listbox	String String[] (multiple selection)	Binding on selection
Radiogroup	String	Binding on selection
Slider	Integer	curpos
Timebox	Date	text
Textbox	String	value
Tree	String String[] (multiple selection)	Binding on selection

(Table 1: Components which implement EditableValueHolder)

How to use ValueBinding

To bind data with Backing Bean is the same as how you use JSF Component, besides assigning a namesapce of 'http://java.sun.com/jsf/core' (we assume a prefix 'f' with this namespace in all examples). We can see the below code, binding value to a field of ValueBindingBean.

<z:window z:title="ValueBinding Example" width="500px" border="normal">
	<z:textbox id="tbox" f:value="#{ValueBindingBean.text}" /><br/>
	<z:intbox id="ibox" f:value="#{ValueBindingBean.number}" /><br/>
	<z:datebox id="dbox" format="yyyy/MM/dd" f:value="#{ValueBindingBean.date}" />
	<br/>
	<z:listbox id="lbox" f:value="#{ValueBindingBean.selection}">
		<z:listitem value="A" label="Item-A" />
		<z:listitem value="B" label="Item-B" />
		<z:listitem value="C" label="Item-C" />
		<z:listitem value="D" label="Item-D" />
		<z:listitem value="E" label="Item-E" />
		<z:listitem value="F" label="Item-F" />
	</z:listbox>
	<h:commandButton id="submit" action="#{ValueBindingBean.doSubmit}" value="Submit" />				
</z:window>

You can run this demo on the Value Binding Example in the zkjsf-demo. The runtime result will be like below.

How to use Converter

A Converter can convert String(from request submitting) to Object which will be assigned to Backing Bean. The usage is the same as JSF Component, just add a converter element.

<z:window z:title="Converter Example" width="500px" border="normal">
	--Convert string to date--<br/>
	<z:textbox id="tbox" f:value="#{ConverterBean.value}">
		<f:converter converterId="dateConverter"/>
	</z:textbox>
	<h:message
	style="color: red; font-style: oblique;"
		for="tbox" />
	<br/>
	<h:commandButton id="submit" action="#{ConverterBean.doSubmit}" value="Submit" />				
</z:window>

You can run this demo on the Converter Example in the zkjsf-demo. The runtime result will be like below.

Note that, component have a default converter if the Binding Attribute is not String in the Table 1

How to use Validator

A Validator can validate user input and push an error message when validation fails. The usage is the same as JSF Component besides assigning a namespace 'http://java.sun.com/jsf/core'.

<z:window z:title="Validator Example" width="500px" border="normal">
	--Validate input day must in weekend--<br/>
	<z:datebox id="dbox" format="yyyy/MM/dd"
		f:value="#{ValidatorBean.value}" 
		f:validator="#{ValidatorBean.validateDate}"/>
	<h:message
	style="color: red; font-style: oblique;"
		for="dbox" />
	<br/>
	<h:commandButton id="submit" action="#{ValidatorBean.doSubmit}" value="Submit" />				
</z:window>

You can run this demo on the Validator Example in the zkjsf-demo. The runtime result will be like below.

Access Backing Bean in ZUL Components

To cooperate with Backing Bean, we provide a utility org.zkoss.jsf.zul.util.ContextUtil which let you access Backing Bean in ZUL Components. The example code is like below.

<z:zscript>
	var user = ContextUtil.getBean("userBean");
	label.value = user.getName();
</z:zscript>

Some Notes

The 'id' attribute on ZK JSF Component is synchronized to the wrapped ZK Component.

When using input components, do not assign the Binding Attribute in the Table 1 , use 'value' attribute with a namespace 'http: //java.sun.com/jsf/core'. For example, use <z:textbox id="tbox" f:value="#{ConverterBean.value}">('f' is the namespace of 'http: //java.sun.com/jsf/core') instead of <z:textbox id="tbox" value="#{ConverterBean.value}"> .

If you mix ZK Components in other JSF Components which render children themselves(such as panelGrid). This will cause a suppressed status , and ZK components will ignore the plain text in it’s content. To avoid this, use a JSF Verbatim component wrapping your text. For example

  --Mix--  	
  <h:panelGrid columns="1" >
	<z:window title="foo">
		Click button:
		<z:button label="click me">
		Click button:
	</z:window>
  </h:panelGrid>
  equals to
  <h:panelGrid columns="1" >
	<z:window title="foo">
		<z:button label="click me">
	</z:window>
  </h:panelGrid>  
  --Use Verbatim--
  <h:panelGrid columns="1">
	<z:window title="foo">
		<f:verbatim>Click button:</f:verbatim>
		<z:button label="click me" />
		<f:verbatim>Click button:</f:verbatim>
	</z:window>
  </h:panelGrid>

When using Listbox, Radiogroup and Tree , remember to set the value of it’s selectable children, such as Listitem of Listbox.

  <z:listbox id="time" mold="select" f:value="#{ReservationBean.resvTime}">
	<z:listitem value="08" label="08:00"/>
	<z:listitem value="10" label="10:00"/>
	<z:listitem value="12" label="12:00"/>
  <z:listbox>

Although ZK JSF Components are following the JSF 1.1 specification(run on JSP 1.2, Servlet 2.3), there is a restriction on ZK JSF Components. It must run in a Web Container which provides JSP 2.0 implementation.

Installation & Configuration

To Install ZK JSF Components in your web application please follow these steps:

Download zk-bin-2.5.0-FL-2007-08-22.zip. Install and configure it in your web application. You can refer here to know how to install & configure ZK.
Download JSF 1.1, install and configure it in your web application if you have not.
Download zk-JSFComps-bin-0.8.0.zip. Extract the zuljsf.jar to your web application's /WEB-INF/lib directory.

To configure ZK JSF Components, please follow these steps:

1. Modify web.xml, append a filter like below(optional, skip this if you don’t want to access Backing Bean in ZK Component)

  <filter>
	<filter-name>ZK FacesContext Filter</filter-name>
	<filter-class>org.zkoss.jsf.zul.util.HttpFacesContextFilter</filter-class>
	<!-- Must. Specifies URI of the update engine (DHtmlUpdateServlet).
		It must be the same as <url-pattern> for the update engine.
	-->
	<init-param>
		<param-name>update-uri</param-name>
		<param-value>/zkau</param-value>
	</init-param>
  </filter>
  <filter-mapping>
	<filter-name>ZK FacesContext Filter</filter-name>
	<servlet-name>zkLoader</servlet-name>
  </filter-mapping> 
  <filter-mapping>
	<filter-name>ZK FacesContext Filter</filter-name>
	<servlet-name>auEngine</servlet-name>
  </filter-mapping>

2. Modify zk.xml, append content like below if you are using Sun RI.(optional, skip this if you don’t want to access Backing Bean in ZK Component)

  <listener>
	<description>ThreadLocal Variables Synchronizer</description>
	<listener-class>org.zkoss.zkplus.util.ThreadLocalListener</listener-class>
  </listener>
  <preference>
	<name>ThreadLocal</name>
	<value>javax.faces.context.FacesContext=instance;</value>
  </preference>

3. Since 0.8.1, if you are using Apache MyFaces :

Modify web.xml, append a listener like below

  <listener>
	<listener-class>org.apache.myfaces.webapp.StartupServletContextListener</listener-class>
  </listener>

Modify zk.xml, append content like below.(optional, skip this if you don’t want to access Backing Bean in ZK Component)

  <listener>
	<description>ThreadLocal Variables Synchronizer</description>
	<listener-class>org.zkoss.zkplus.util.ThreadLocalListener</listener-class>
  </listener>
  <preference>
	<name>ThreadLocal</name>
	<value>javax.faces.context.FacesContext=_currentInstance;</value>
  </preference>

Download

zk-2.5.0-FL-2007-08-22

ZK JSF Components 0.8.0

Summary

JSF is UI Component technology for building user interfaces for JavaServer applications. Now we create ZK JSF Components which let you run ZK Components in JSF runtime, providing you an alternate way to build rich UI on your web application. We hope you enjoy this new feature and give us feedbacks, so we can do things better.

Anonymous

Enrich Your JSF Applications with ZK Today!

Namespaces

More

Page actions

Contents