Small Talks/2011/December/Define Composite Component using Java Annotation in ZK6

Author
Ian Tsai, Engineer, Potix Corporation

Date
December 06, 2011

Version
ZK 6+

Introduction

This article will introduce you how to define and implement a ZK Composite Component with java annotation in ZK6.

In previous article Envisage ZK 6: An Annotation Based Composer For MVC Simon Pai showed us the new approach to do ZK MVC in ZK6, which might be the best common solution for layout fragment controller implementation. But in some cases, some UI fragments supposed to be reused in a lot of places, attached and detached by condition, and should be interacted with other parts like a ZK Component (ex: a Permission Inquiry Dialog). In ZK5, we introduced a concept named ZK Composite Component which is more like a practice. And now in ZK 6 with the power that Java Annotation granted, we are able to design an utility API to provide more conveniences.

How to Use

Installation

Here is the prerequisite stuff of using Composite in ZK6.

Install ZK 6 into your Web Project

I assume the reader of this article has used ZK before so I won't explain too much on this part, if you don't know how to start with ZK, please take a look at ZK Installation Guide

Download ZK-Composite.zip from Github.com

Here is the download link: ZK-Composite.zip Download it, unpack it, and copy every jar files(asm4.0.jar, zkcomposite.jar, zkcpr.jar) under /lib/* to your web project's /WEB-INF/lib/.

Copy the sample code into your project

inside the unpacked archive there are two folders: src_demo/ and WebContent/ , copy them into your project.

Implementation of your Composite

Here is a sample code of how to use ZK 6 Composite technology:

 1 package demo.ui.composite;
 2 
 3 import org.zkoss.composite.Composite;
 4 import org.zkoss.composite.Composites;
 5 import org.zkoss.zk.ui.IdSpace;
 6 import org.zkoss.zk.ui.select.Listen;
 7 import org.zkoss.zk.ui.select.Wire;
 8 ...
 9 
10 @Composite
11 public class ImageLabel extends Div implements IdSpace {
12 	
13 	@Wire
14 	private Groupbox item;
15 	@Wire
16 	private Image labelImage;
17 	@Wire
18 	private Label titleLabel;
19 	@Wire
20 	private Label descLabel;
21 	
22 	public ImageLabel(){
23 		Composites.doCompose(this, null);
24 	}
25 	
26 	private InplaceEditor fInplaceEditor;
27 	
28 	@Listen("onClick= #titleLabel")
29 	public void doTitleClick(){
30 		if(fInplaceEditor==null){
31 			fInplaceEditor = new InplaceEditor();
32 			fInplaceEditor.setParent(item);
33 		}else{
34 			fInplaceEditor.doCancel();
35 		}
36 	}

The concept is very simple: you declare a Java class which extends a ZK Component, annotate this class, call Composites.doCompose(this, null); in your constructor, that's all. The detailed steps are listed bellow:

Create a Java class extends from an existing ZK Component (ex: Div or Window)

Normally your composite class will extends from a container component such as Div or Window, but the case to extends from a Collection Component such as Grid or Listbox is also very common, this part is very flexible, all depends on your needs.

Ensure your class implements IdSpace

ZK Composite requires a ZUL as the content template and will do the field-variable auto wiring & Event Listening method registration. In order to prevent id conflict, you must make your Composite class implements IdSpace.

Call Composites.doCompose in constructor

org.zkoss.composite.Composites is the utility API which will do the real hard works.While doCompose(...), Composites will get the meta information(java annotation) from given instance type and do the following process:

1. Getting macroURI from annotation(@Composite) if any, use referenced resource to generate content components of this composite.

2. Using ZK6 org.zkoss.zk.ui.select.Selectors to wire annotated member fields and annotated methods(as event listening methods).

ZK Composite Definition can be registered through package scanning

Use annotated class as some kind of configuration with package scan while application start is a common practice used in a lot of application framework such as Spring JBoss Seam and EJB3. Now in ZK Composite, we support the same mechanism to register a composite as a component definition into application's ZUL Language Definition, which means by given packages in zk.xml, ZK Composite will find all annotated public Composite class and register them. This is a very convenient feature to let you define a composite without creating & configuring a metainfo/zk/lang-addon.xml in your source directory.

Set up zk.xml library property for your target package

Here is an example to config which package in your class path that need to be scanned:

1 <library-property>
2     	<name>org.zkoss.composite.packageScan</name>
3     	<value>demo.ui.homepage.composite, demo.ui.product.composite</value>
4 </library-property>

Currently ZK Composite depends on ZK-CPR and ASM4.0 to implement it's package resource scanning, please make sure you have the jars(which are already packed inside the zip) of them in your project.

Use @Composite to annotate your Composite class

Import: org.zkoss.composite.Composite then mark your component class with @Composite annotation. @Composite has two attributes:

1. macroURI: by default, you don't have to assign this attribute and ZK Composite technology will use [package]/[class_name to lowerCase].zul to get the content template. The macro uri that you can assigned can be a class path resource which use "/" as separator, a zk web context path or a URL that current application can resolve.

2. name: by default, ZK Composite technology will use lower-cased class simple name as component name, which is the tag name that you can use in zul under zul namespace(default xml namespace in ZK).

Here is an example with most detail:

10 import org.zkoss.composite.Composite;
11 ...
12 
13 @Composite(name="imglabel", macroURI="/WEB-INF/partial/_ImageLabel.zul")
14 public class ImageLabel extends Div implements IdSpace {
15 ...

Comments

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.