Define Composite Component using Java Annotation in ZK6"

From Documentation
Line 86: Line 86:
  
 
=== Use @Composite to annotate your Composite class ===
 
=== Use @Composite to annotate your Composite class ===
import: ''org.zkoss.composite.Composite'' then mark this component with '''@Composite''' annotation. '''@Composite'''  has two attributes:
+
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.
 
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).
 
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:
 +
 +
<source lang="java" start="10" line="true">
 +
import org.zkoss.composite.Composite;
 +
...
 +
 +
@Composite(name="imglabel", macroURI="/WEB-INF/partial/_ImageLabel.zul")
 +
public class ImageLabel extends Div implements IdSpace {
 +
 +
</source>
  
 
= How it works =
 
= How it works =

Revision as of 05:34, 8 December 2011

DocumentationSmall Talks2011DecemberDefine Composite Component using Java Annotation in ZK6
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

ZK Composite technology now provides a package scanning mechanism to find all annotated public java class under the given package. 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.

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 {

How it works

Composite's macroURI resolving and Inheritance

Package Resource Scan

Comments



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