Professional Documents
Culture Documents
ZK 6 Essentials
ZK 6 Essentials
ZK 6 Essentials
For ZK 6
PDF generated using the open source mwlib toolkit. See http://code.pediapress.com/ for more information. PDF generated at: Wed, 30 May 2012 01:24:30 CST
Contents
Articles
ZK Essentials Introduction An Introduction to ZK's Server client Fusion Architecture Component Based UI Event Driven Programming Working with the Sample Applications The Resources Setting Up the Applications Using Eclipse Store Store with a Database Laying out Your ZK Components How to Layout Components Using ZK Borderlayout Handling the Login Process using ZK MVC and Sessions The Basic Login Implementing ZK MVC Managing credentials using ZK Sessions Displaying Information Using Grid Implementing the View Using a ListModel and RowRenderer The Final Grid Displaying information using the Listbox Implementing the View Using a ListModel and ListitemRenderer The Final Listbox Displaying Information in a Grid Using Data Binding The Concept of Data Binding Implementing Data Binding Working with ZK and databases The Theory of Using ZK with Databases Using Hibernate with ZK Hibernate, Entities and Database Generation Hibernate Session Management and Implementing the DAOs Hibernate Summary 1 1 1 2 10 14 14 15 17 20 24 25 26 30 30 31 33 35 35 38 41 45 45 48 53 54 54 58 63 63 64 66 69 72
72
References
Article Sources and Contributors Image Sources, Licenses and Contributors 75 76
ZK Essentials
ZK Essentials
Documentation:Books/ZK_Essentials If you have any feedback regarding this book, please leave it here. <comment>http://books.zkoss.org/wiki/ZK_Essentials</comment>
Introduction
The aim of ZK Essentials is to provide a step by step resource for a developer to address the creation of a substantial application using ZK. Each chapter navigates a particular ZK topic and explains in details in context of the application why certain choices and implementation techniques were chosen over others. The book chooses a shopping cart driven application as a platform to explore ZK. By the end of this book you should be able to gather enough information about ZK techniques and practices to implement a custom web application. The book starts off by introducing ZK and its architecture then moves into the creation of the application.
When a ZK application runs on the server, it can have access to the backend resources, assemble UI with components, listen to user's activity, and then manipulate components to update UI. All are done at the server. The synchronization of the states of the components between the browser and the server is done automatically by ZK and transparently to the application. When running at the server, the application can access full Java technology stack. User activities, including Ajax and Server Push, are abstracted to event objects. UI are composed of POJO-like components. ZK is the most productive approach to develop a modern Web application.
An Introduction to ZK's Server client Fusion Architecture With ZK's Server+client Fusion architecture, your application will never stop running on the server. The application could enhance the interactivity by adding optional client-side functionality, such as client-side event handling, visual effect customizing or event even UI composing without server-side coding. ZK enables seamless fusion from pure server-centric to pure client-centric. You can have the best of two worlds: productivity and flexibility.
Component Based UI
In ZK, we work with UI components to put our application GUI together. We can declare components using either markup language or Java.
Here we declared a Window [1] component, setting the border to normal and resizing its width to a definite 250 pixels. Enclosed in the Window [1] are two Button [2] components.
ZK components can be easily declared in Java source codes and are also compatible with Java. Please see the following.
Component Based UI package org.zkoss.zkdemo; import org.zkoss.zk.ui.Page; import org.zkoss.zk.ui.GenericRichlet; import org.zkoss.zul.*; public class TestRichlet extends GenericRichlet { //Richlet// public void service(Page page) { final Window win = new Window("ZK Essentials", "normal", false); win.setWidth("250px"); Vlayout vl = new Vlayout(); vl.setParent(win); final Textbox txtbx = new Textbox(); txtbx.setParent(vl); final Label lbl = new Label(); lbl.setParent(vl); txtbx.addEventListener("onChange", new EventListener(){ @Override public void onEvent(Event event) throws Exception { lbl.setValue(txtbx.getValue()); } });
win.setPage(page); } } Please refer to Developer's Reference: Richlet for more details on programming with Richlets.
Component Based UI The ZUL page renders a window containing two buttons as shown in the image below:
The markup in ZUL is equivalent to the following POJO declarations in Java: Window win = new Window(); win.setTitle("ZK Essentials"); win.setBorder("normal"); win.setWidth("250px"); Button helloBtn = new Button(); helloBtn.setLabel("Hello"); helloBtn.setParent(win); Button byeBtn = new Button(); byeBtn.setLabel("Good-bye"); byeBtn.setParent(win); Components on the server are translated into instructions(in JSON) for widget (JavaScript objects) creation and then sent to the client.
Component Based UI
The markup source is: <window title="ZK Essentials" mode="overlapped" border="normal" width="250px"> <label id="lbl"/>World ! <button label="Hello " onClick="lbl.value = self.label"/>
Component Based UI <button label="Good-bye " onClick="lbl.value = self.label"/> </window> The value of the label with ID "lbl" depends on which button the user clicks: "Hello", or "Good-bye". When a button is clicked, the value of the button's label is assigned to the value of the label. Note that the string "World !" is automatically converted to a label. Without firstly assigning "lbl" to the desired label component, it would be impossible to fetch "lbl" and provide it with a value. In fact, ZK assigns each component with a UUID (Universal Unique Identifier) to keep track of its tree of components internally. This UUID is over-ridden when the developer provides it with a more legible ID. Finding a Component Programmatically in Java Suppose we have a POJO declaration for a simple UI that looks something like this: Window outerWin = new Window(); Button outerBtn = new Button(); btn.setParent(outerWin); Window innerWin = new Window(); innerWin.setParent(outerWin); Button innerBtn = new Button(); innerBtn.setParent(innerWin); For better readability, the equivalent declaration above using ZUML in ZUL file is given here: <window id="outerWin"> <button id="outerBtn"> <window id="innerWin"> <button id="innerBtn"/> </window> </window> Now suppose we have a controller class where we want to programmatically access and modify the children components (outerBtn, innerWin, innerBtn); how should we do it if we only have access to the Window component? One of the approaches to accomplish this is to call the component's Component.getFellow() [7] method. For example, if we wish to access the inner Window, we could do the following: Window innerWin = (Window)outerWin.getFellow("innerWin");
We can call the getFellow method on any component to access another component in the same ID Space.
An ID Space is a way to group components into a more manageable collection in ZK so that we're not lost in trying to access a component in a large component tree. This concept is illustrated below:
Component Based UI
The Window [1] component and Page [8] are Space Owners by default. We can make any components a space owner by implementing the IdSpace [9] interface. To identify a component's space owner, call its getSpaceOwner method. There are other methods to accomplish this, we summarize them in a table for clarity:
Component outerBtn method = (Button)outerWin.getFellow("outerBtn"); Note The components outerWin, outerBtn, and innerWin form an ID Space; with outerWin being the Space Owner. Components in the same ID Space can call each other by ID using the getFellow method. innerWin belongs to the same ID Space as outerWin, hence, it could be called using the getFellow method.
innerWin
= (Window)outerWin.getFellow("innerWin");
innerBtn
= (Button)outerWin.getFellow("innerWin").getFellow("innerBtn"); innerWin and innerBtn belong to an ID Space of their own, with innerWin being the Space Owner. innerWin is also a member of the ID Space which outerWin is the Space Owner. Hence, we can call getFellow on outerWin to get innerWin, then call getFellow on innerWin to get innerBtn. = (Button)Path.getComponent("/outerBtn"); [10] The Path provides the utility method getComponent which takes the relative path of the component as its argument. /outerBtn is equivalent to outerWin/outerBtn innerWin and outerBtn both have outerWin as an ID Space Owner. innerBtn has innerWin as its ID Space Owner, innerWin in turn has outerWin as its Space Owner. Hence, we write /innerWin/innerBtn, which is equivalent to outerWin/innerWin/innerBtn The getFirstChild method returns the first child component of the caller. The advantage of using this method is that you don't even need to know the component ID to fetch the component.
outerBtn
innerWin
= (Window)Path.getComponent("/innerWin");
innerBtn
= (Button)Path.getComponent("/innerWin/innerBtn");
outerBtn
= (Button)outerWin.getFirstChild();
Component Based UI
8
The getFirstChild method gets the outerBtn since it's outerWin's first child component. We then call the getNextSibling method to find the innerWin. We compound another getFirstChild method to get the first, and only, child component of innerWin.
innerWin
= (Window)outerWin.getFirstChild().getNextSibling();
innerBtn
= (Button)outerWin.getFirstChild().getNextSibling().getFirstChild();
Component Based UI Correct: <window width="600px"/> Incorrect: <window width=600px/> Using XML tags, we declare a component and set a component's attributes; as an alternative to coding in Java files, we could set a component's attributes to initialize values, evaluate conditions/expressions, and handle events. The figure belows shows an example of how we could easily dictate whether a component is to be displayed on a page when the "if" condition is declared as its attribute.
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Window. html# [2] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Button. html# [3] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Textbox. html# [4] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ ui/ Page. html# [5] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ Component. html# [6] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ ui/ Desktop. html# [7] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ Component. html#getFellow() [8] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ Page. html# [9] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ IdSpace. html# [10] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ Path. html# [11] Please refer to resources on Internet, such as (http:/ / www. w3schools. com/ xml/ xml_whatis. asp) and (http:/ / www. xml. com/ pub/ a/ 98/ 10/ guide0. html) should you need to get comfortable with its syntax and conventions
10
Breaking down how the event driven model works Register Event Listeners At line 3 and 4, we register the onClick events on the buttons so we'll know when and which button is clicked. <button label="Hello " onClick="lbl.value = self.label"/> <button label="Good-bye " onClick="lbl.value = self.label"/> Event Sent with Request When the user clicks one of the buttons, its respective onClick event is sent to the server for processing by default (optionally, we could handle events from the client directly). As shown highlighted in blue, the "onClick" event and the button's UUID (Universal Unique Identifier) is sent by the Ajax request.
Event Handling Instructions From the request, the ZK upload engine knows which component fired the event and what event is fired. It also knows how to handle this request because we've specified the event handling code in ZUL using EL (Expression Language): "lbl.value = self.label", which translates into the following Java code:
Event Driven Programming lbl.setValue(self.getLabel); Where lbl is the ID we assigned to the Label component and self refers to the Button component itself (akin to this in Java) Update Instruction Sent Back in Response The server then sends the instructions back to the client to reflect this change in the label's value:
11
Hello
Good-bye Where the instructions tell the client engine to set the attribute "value" to "Hello" for the component with the UUID "z_d__2", which is the label component.
We could program this behavior entirely in a ZUL file: <window id="win" title="ZK Essentials" border="normal" width="250px"> <button label="Hello"> <attribute name="onClick"> <![CDATA[ Button btn = new Button(); btn.setLabel("World !"); btn.setParent(win); ]]> </attribute>
Event Driven Programming </button> </window> Inside the button declaration, we declare the "onClick" event as the button's attribute and code its event handling instructions directly in ZUL. This is possible because the Java code is interpreted by BeanShell [1] dynamically. In the Java code, we first created a new Button, set its label to "World !", and then set the Window component as its parent. Despite of convenience, registering event directly from ZUL is not recommended if your application is performance sensitive. As all the Java code needs to be interpreted dynamically. Event Handling In a Controller Following the ZK MVC pattern, we create a controller class where the event is forwarded to it for handling. So here we make the necessary changes: At line 1, we declared: apply=controller class name so that the events fired within the window is all forwarded to the controller for event handling. At line 2, we need to give the "Hello" button an ID so the controller would know which button fired during the onClick event.
12
<window id="win" title="ZK Essentials" border="normal" width="250px" apply="demo.zkoss.Sa <button id="helloBtn" label="Hello"/> </window> We then implement our controller class: At line 7, we extend the GenericForwardComposer [2] so all the events fired in its applied component would be forwarded here. At line 9, we declare the Window variable to match that we declared for the Window component's ID so they are wired. At line 11, we follow ZK's convention for naming the event handler 'event_name$component_id' From line 12 to 14, we use the same Java code we did previously to dynamically create a button. package demo.zkoss; import org.zkoss.zk.ui.util.GenericForwardComposer; import org.zkoss.zul.Button; import org.zkoss.zul.Window; public class SampleCtrl extends GenericForwardComposer { Window win; public void onClick$helloBtn(){ Button btn = new Button(); btn.setLabel("World !"); btn.setParent(win); } }
Event Driven Programming Event Handling of Dynamically Generated Components Suppose we take our previous example a step further, we would like to clear off the "Hello" button in the window when we click the dynamically created "World !" button. We'll need to register an event listener to the dynamically created "World !" button. At line 10, we add a new event listener to the newly created button. The addEventListener method takes an event name (String) and an EventListener [3] as its arguments. Within the anonymous EventListener class, we implement the onEvent method to have the Window component fetch its "fellow" component "helloBtn" and call its detach method to clear off the Window component. public class SampleCtrl extends GenericForwardComposer { Window win; public void onClick$helloBtn(){ Button btn = new Button(); btn.setLabel("World !"); btn.setParent(win); btn.addEventListener("onClick", new EventListener(){ public void onEvent(Event event) throws Exception { win.getFellow("helloBtn").detach(); } }); } }
13
References
[1] http:/ / www. beanshell. org/ [2] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ ui/ util/ GenericForwardComposer. html# [3] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ event/ EventListener. html#
14
The Resources
This book comes with two examples: Store - which uses an in memory model defined by Java statements Store with database - which uses a persistent model driven by Hibernate. This is used at the last chapter of the book. If you require the ZK libraries please download ZK first: 1. Go to ZK's download page [1] and choose a package to download. 2. Unzip the package and place it in a folder
Store
The store is available on our svn using the following command:
svn checkout http:/ / zkbooks. googlecode. com/ svn/ trunk/ zkessentials/ store/ zkessentials-store
This will put the store source code into a folder named zkessentials-store. If you prefer to set up the project in eclipse please refer to here.
Having checked this out you will have the source code and a runnable WAR file which also includes the source code. If you prefer to set up the project in eclipse please refer to here.
References
[1] http:/ / www. zkoss. org/ download/ zk. dsp
15
Set-up ZK Studio
1. Open your Eclipse IDE 2. On the main menu bar, select Help > Install New Software... 3. Copy and paste the ZK Studio plugin's update URL : http://studioupdate.zkoss.org/studio/update/eclipse_3_5 For Eclipse 3.5, or http://studioupdate.zkoss.org/studio/update/eclipse_3_6 for Eclipse 3.6 into the input box as shown below:
Setting Up the Applications Using Eclipse 5. Once the download is complete, go to Window > Preferences > ZK > ZK Packages, click Add File/Directory to add the ZK package downloaded 6. Check-mark the package and click "Ok"
16
Store
17
Store
Set-up the ZK Essentials sample
1. Go to the ZK Essentials http://code.google.com/p/zkbooks/source/checkout [1] or http://zkbooks. googlecode.com/svn/trunk/zkessentials/store/ [2] , and checkout the source using svn. This will put the sample code for Store into a folder named zkessentials-store. 2. Create a new ZK project: File > New > Others... > ZK > ZK Project and click Next.
3. Enter project name and specify which ZK package you want to use for this project. And then click Finish.
Store
18
4. Import the sample code by right clicking the project and select Import> Import... 5. Choose import from File System under a folder called General. Click Next.
6. Click Browse for the From directory field. Select the folder containing the sample code and click OK. And then click Finish in the Import dialog window to import.
Store
19
References
[1] http:/ / code. google. com/ p/ zkbooks/ source/ checkout [2] http:/ / zkbooks. googlecode. com/ svn/ trunk/ zkessentials/ store/
20
2. Type WAR into the filter text and then select the storewithdb WAR file you just downloaded. Then, press Next.
3. Download the WAR file from https://zkbooks.googlecode.com/svn/trunk/zkessentials/storewithdb/ storewithdb.war and place it into an accessible folder
Store with a Database 4. In the WAR import screen, browse for the WAR file and select it. The rest of the fields should be filled out automatically.
21
5. Click Next and the WAR file will be imported. 6. You should now have a clean project imported with no errors. At this point you can run the index.zul page on your server. NOTE: When importing, if eclipse is showing a lot of errors, please see the section below the Dealing with Errors label.
22
If you see errors stating that annotations are only available in Java 1.5, please right click on one of the errors and click Quick Fix:
In the following screen, please make sure change project compliance to JRE 1.5 is selected and click Finish:
23
Once it's done, we should have about one item left in the problems list, stating that Java compiler level does not match the version of the installed Java project facet:
Right click on the error and click quick fix as before. Then in the following screen select the item Change Java project facet version to Java 5.0 and press Finish.
24
All the errors should be fixed now and you can continue to run the application.
25
Pop-up
Allow contents contained in an area to be evoked on top of its parent page with its position adjustable Allow contents to be hidden so page space is disclosed
[5]
, Pop-ups
[6]
[7]
, Border Layout
, Border Layout
[8]
ZK offers a variety of layouts that incorporates these elements to bring flexible layout to meet the demands of building diverse web applications. Please see the following references for these ZK components: Border Layout Component Reference Demo [8] Portal Layout Component Reference Demo [7] Column Layout Component Reference Demo [10] Table Layout Component Reference Demo [11] Tab Box Component Reference Demo [2] Group Box Component Reference Demo [12] Vlayout
26
References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Tabbox. html# [2] http:/ / www. zkoss. org/ zkdemo/ tabbox [3] http:/ / www. zkoss. org/ zkdemo/ grid/ hierarchy [4] http:/ / www. zkoss. org/ zkdemo/ grid/ master_detail [5] http:/ / www. zkoss. org/ zkdemo/ window/ modal_dialog [6] http:/ / www. zkoss. org/ zkdemo/ menu/ pop-ups [7] http:/ / www. zkoss. org/ zkdemo/ layout/ business_portal [8] http:/ / www. zkoss. org/ zkdemo/ layout/ border_layout [9] http:/ / www. zkoss. org/ zkdemo/ layout/ splitter [10] http:/ / www. zkoss. org/ zkdemo/ layout/ column_layout [11] http:/ / www. zkoss. org/ zkdemo/ layout/ table_layout [12] http:/ / www. zkoss. org/ zkdemo/ layout/ group_box
Using ZK Borderlayout
Suppose we have the following requirements in our shopping cart application: Product View - A table displaying the available products to purchase Shopping Cart View - A list of items placed in the shopping cart Order View - A record of all the orders placed
Using ZK Borderlayout The borderlayout divides a page into five sections: North, East, Center, West, South.
27
border
<east border="normal">...</east>
collapsible
<west collapsible="true">...</west>
Using ZK Borderlayout
28
The borders can be made adjustable (splittable="true"), and the east and south components can be collapsed to give room to the center component displaying the Product View.
<center title="Product View" border="0"> <div id="PrdoDiv" style="background:#D9E5EF; height:100%" apply="demo.web.ui. //Product View Implementation </div> </center> <east
title="Shopping Cart View" size="30%" flex="true" splittable="true" collapsi <div style="background:#D9E5EF; height:100%" apply="demo.web.ui.ctrl.Shopping //Shopping Cart View Implementation </div> </east> <south
Using ZK Borderlayout
29
<div style="background:#D9E5EF; height:100%" apply="demo.web.ui.ctrl.OrderVie //Order View Implementation </div> </south> </borderlayout> Here we note a few key implementations: The size of the borderlayout is not specified, so its dimensions will assume that it must be the parent component Window [1]. The borderlayout component itself does not have the "border" attribute, only its children (north, west, etc..) do. north, east, center, west, and south, are allowed to have only one child component; therefore, you should use container components such as Div [2] or Window [1] to wrap multiple components when placing them in borderlayout's children components. The center component does not take any size attributes; its height is dependent on the dimensions of north/south, whereas its width is dependent on the dimensions of east/west. The splittable and collapsible attributes are set to "true" to allow the dimensions of east and south to be manipulated. The apply attribute is used here to assign a controller to the container component so components within it are auto-wired with data objects and events are automatically forwarded to event handlers.
Using ZK Borderlayout
30
References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Borderlayout. html# [2] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Div. html#
The first thing we need to do is to create the log-in interface using a ZUL file. The basic ZUL markup representing our login form is shown below. <?page title="ZK Store - Login"?> <window id="loginWin" border="normal" width="300px" title="You are using: ${desktop.webApp.version}"> <grid> <rows> <row> Name: <textbox id="nameTxb"/></row> <row> Password:<textbox id="passwordTxb" type="password"/></row> </rows> </grid> <button id="confirmBtn" label="confirm"/> <label id="mesgLbl"/> </window> The ZUL representation is very simple and consists of a Grid which aids the layout of the Textbox along with a Button to perform the confirm action and a Label to notify the user of any issues with the login process. At the moment the ZUL file represents a dumb login page as the button is not mapped to an action.
The Basic Login The recommended way to add functionality to your UI is to follow the MVC pattern of development. The following section details how to implement ZK using the MVC pattern.
31
Implementing ZK MVC
The MVC is developers' favorite pattern as it neatly separates various application layers in a clear manner. ZK fosters this process by allowing UI declaration to be done using an XML declarative language. It should be noted, however, that we can create Swing programmatic UIs using Richlets. ZK MVC revolves around two key items, the GenericForwardComposer [1] and the apply attribute. The GenericForwardComposer [1] is a utility class which adds auto-wire functionality to provide access to UI objects from Java code without any effort. Lets see the demonstration of how to add this functionality into the login page.
Implementing ZK MVC public class LoginViewCtrl extends GenericForwardComposer { private Textbox nameTxb; private Textbox passwordTxb; private Label mesgLbl; } You can now access the UI components on the server-side and interact with them. All the wiring and communication is taken care of by ZK automatically. The next step is to enable the capturing of events. In this specific case we need to capture the <mp>onClick</mp> event of the button <mp>confirmBtn</mp>. To do so, we need to create a method with a specific signature. In this case, we can use the event name followed by a $ and the component ID. The method signature is as follows: public void onClick$confirmBtn() Notice that the method does not take any parameters, however, if necessary, the method can take an Event [2] object as a parameter or the subsequent subclass which is applicable to the context. Lastly, we need to consider that people coming to the login.zul page may already be logged in just as our use case indicates. Therefore, we need to set up a mechanism that checks whether that is the case before loading the UI. This [1] is done by overriding the GenericForwardComposer method GenericForwardComposer.doAfterCompose(org.zkoss.zk.ui.Component) [3] which would be called when the events and components are wired. Thus, if you override this method, please make sure to call the super method. At this stage, your doAfterCompose(org.zkoss.zk.ui.Component) [3] method should look like this: public void doAfterCompose(Component comp) throws Exception { super.doAfterCompose(comp); //to be implemented, lets check for a login } Now we have the insights of what advantages ZK provides us with by wiring the components, events, and data automatically. We need to move on to deal with our goal of implementing a user management system to check credentials and redirect it according to our use case. The next section walks you through how user credentials is implemented using a session.
32
References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ util/ GenericForwardComposer. html# [2] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ event/ Event. html# [3] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ util/ GenericForwardComposer. html#doAfterCompose(org. zkoss. zk. ui. Component)
33
// Session session = Executions.getCurrent().getDesktop().getSession(); // Session session = Executions.getCurrent().getSession(); Session session = Sessions.getCurrent(); synchronized(zkSession){ UserCredentialManager userModel = (UserCredentialManager) zkSession.getAttribute(KEY_USER_MODEL); if(userModel==null){ zkSession.setAttribute(KEY_USER_MODEL,
Managing credentials using ZK Sessions userModel = new UserCredentialManager()); } return userModel; } } } The manager is very standardized, exposing a login method. If successful, it sets the <mp>User</mp> object and a <mp>isAuthenticated</mp> method which checks to see whether the user is null and returns accordingly. Once this is put into practice, we can now make use of it in our controller to change the page flow of the application.
34
References
[1] [2] [3] [4] [5] [6] [7] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ Session. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ Execution. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ Executions. html#getCurrent() http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ Executions. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ Executions. html#sendRedirect(java. lang. String) http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Grid. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Listbox. html#
35
Here we have six columns, each with a header to denote the data field, and six rows with each row containing a single product entry. The product information is listed from column one to five while the last column contains ZK components which allow end users to choose and submit a product's quantity for purchase. To accommodate these requirements, we'll use the ZK Grid component.
Implementing the View <rows > <row > <label <label </row> <row > <label <label </row> </rows> </grid>
36
A Row component accepts all ZK components as its children components, hence, a Grid component can be treated as a component container for the following: Laying out forms [1] Presenting a collection of data [2] Presenting hierarchical data [3] For our implementation of the "Product View", we could use a Grid to divide product entries into rows, with the first column holding the product's image, second to fifth columns containing the product's properties, and the last column enclosing a Cell component which allows end users to select and submit the quantity of the purchased item.
Grid Configuration
All ZK components can be customized using CSS. In this short snippet, we were able to configure the size of the Grid and its constituents, set alignment, and change text color using minimum attribute declarations. <grid width="400px" > <columns> <column label="Column Header 1" <column label="Column Header 2" </columns> <rows > <row > <label value="Row 1 - Item <label value="Row 1 - Item </row> <row align="center"> <label value="Row 2 - Item <label value="Row 2 - Item </row> </rows>
width="60%"/> width="40%"/>
37
For this particular example, we assigned a percentage value to each Column so their size is shown proportional to the Grid component. Items in a Row are automatically aligned to the center when it's declared in the Row component attribute. The style attribute allows us to specify the CSS for any particular ZK component, for instance, the color of the text is set as blue for the Row 2 -Item 1 label.
<center border="0"> <div id="PrdoDiv" style="background:#E6D92C; height:100%" apply="demo.web.ui.ctrl.Pro <grid id="prodGrid"> <columns sizable="true"> <column image="/image/Bullet-10x10.png" align="center" width="100px"/> <column label="Name" width="100px"/> <column label="Price" width="50px"/> <column label="Quantity" width="50px"/> <column label="Arrive Date" width="110px" /> <column label="operation" /> </columns> </grid> </div> </center>
References
[1] http:/ / www. zkoss. org/ zkdemo/ input/ form_sample [2] http:/ / www. zkoss. org/ zkdemo/ grid/ load_on_demand
38
39
//create renderer prodGrid.setRowRenderer(...);//assign renderer to Grid ... } } Notice that the Grid reference "prodGrid" in ProductViewCtrl.java is auto-wired with the Grid declared in mark up whose ID is "prodGrid".
<div id="PrdoDiv" style="background:#E6D92C; height:100%" apply="demo.web.ui.ctrl.Product <grid id="prodGrid"> <columns sizable="true"> <column image="/image/Bullet-10x10.png" align="center" width="100px" <column label="Name" width="100px"/> <column label="Price" width="50px"/> <column label="Quantity" width="50px"/> <column label="Arrive Date" width="110px" /> <column label="operation" /> </columns> </grid> </div>
40
41
References
[1] [2] [3] [4] [5] [6] [7] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ ListModel. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ ListModelList. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ RowRenderer. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ RowRenderer. html#render(Row http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Image. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Label. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Cell. html#
In the previous section, we saw how the renderer assigns UI components (for example, Image [5] and Label [6]) into rows of a Grid for UI presentation. ProductViewCtrl.java - Rendering Rows public void doAfterCompose(Component comp) throws Exception { ... prodGrid.setRowRenderer(new RowRenderer() { public void render(Row row, Object data) throws Exception { final Product prod = (Product)data; Image img = new Image(prod.getImgPath()); img.setWidth("70px"); img.setHeight("70px");
The Final Grid img.setParent(row); new Label(prod.getName()).setParent(row); new Label(""+prod.getPrice()).setParent(row); new Label(""+prod.getQuantity()).setParent(row); new Label(YYYY_MM_DD_hh_ss.format(prod.getCreateDate())).setParent(row); initOperation(prod).setParent(row); } ... }); } The last column contains a Cell [7] component (returned by the method initOperation) which allows end users to ADD items to be purchased. In this section, we'll look into the implementation of this functionality which fulfills the requirements for the Product View Grid. ProductViewCtrl.java - Implementation for "Adding" Items to Purchase private Cell initOperation(final Product prod){ Cell cell = new Cell(); final Spinner spinner = new Spinner(1); spinner.setConstraint("min 1 max "+prod.getQuantity()); spinner.setParent(cell); Button button = new Button("add"); button.setImage("/image/ShoppingCart-16x16.png"); button.setParent(cell); final Label errorLb = new Label(); errorLb.setParent(cell); button.addEventListener(ON_CLICK, new EventListener() { public void onEvent(Event event) throws Exception { ShoppingCartCtrl ctrl = ShoppingCartViewCtrl.getInstance(desktop); try{ ctrl.addItem(prod, spinner.getValue()); errorLb.setValue(""); }catch(WrongValueException e){ errorLb.setValue(e.getMessage()); } } }); return cell;
42
43
The Final Grid ShoppingCart()); } return cart; } So that when we try to add an item, along with its quantity, we could get the same shopping cart instance for the session and validate whether the addition is allowed. Note that session is an implicit object instantiated by ZK. ShoppingCartViewCtrl.java public void addItem(Product prod, int amount) { try{ getShoppingCart(session).add(prod, amount, new AddToCartCallback() { //validation code }); refresh(); }catch(OverQuantityException e){ throw new WrongValueException(e); } } The ShoppingCartView class is a controller where we access the single shopping cart instance across a session and renders the shopping cart data in the Shopping Cart View. Since only one single controller instance ShoppingCartViewCtrl is needed per desktop, we save and retrieve the ShoppingCartViewCtrl instance in a desktop scope. ShoppingCartViewCtrl.java public static ShoppingCartCtrl getInstance(Desktop desktop){ return (ShoppingCartCtrl) desktop.getAttribute(KEY_SHOPPING_CART); } With the ShoppingCart instance stored as a session attribute, and the ShoppingCartViewCtrl instance stored in the desktop scope, they are made easily accessible to us in the button's event handling code. private Cell initOperation(final Product prod){ ... button.addEventListener(ON_CLICK, new EventListener() { public void onEvent(Event event) throws Exception { ShoppingCartCtrl ctrl = ShoppingCartViewCtrl.getInstance(desktop); try{ ctrl.addItem(prod, spinner.getValue()); errorLb.setValue(""); }catch(WrongValueException e){ errorLb.setValue(e.getMessage()); } }
44
45
References
[1] [2] [3] [4] [5] [6] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Spinner. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ impl/ api/ InputElement. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ impl/ api/ InputElement. html#setConstraint(java. lang. String http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Intbox. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Datebox. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Combobox. html#
Here we have five columns, four of them have headers to denote the data field, and a variable number of rows containing product orders. In this case, we also have a requirement to display a picture of the product selected in the shopping cart. In this case, we use the Listbox as this enables developers to select an item firing an onSelect event when this occurs.
46
can be outputted using Listitems. In the example below, we place 3 Listitems into the
The Select Mold In addition to the Listbox [7] which comes in two molds, default and select. The select mold enables the HTML SELECT tag to be generated thus producing the following content. The following example demonstrates the effect of changing the mold on the Listbox [7]. <zk> <listbox mold=select> <listitem label="Butter Pecan"/> <listitem label="Chocolate Chip"/> <listitem label="Raspberry Ripple"/> </listbox> </zk>
Multiple Columns and Headers The Listbox [7] also supports multiple columns and headers. In the following example we use Listhead [1] and Listheader [2] to create headers with two columns. The following example demonstrates a multi-column Listbox [7] with a header. Please note that you can have a multi-column Listbox [7] without the headers but by specifying more than one Listcell [3] in a particular Listitem [4]. <zk> <listbox width="200px"> <listhead> <listheader label="Name"/> <listheader label="Occupation"/> </listhead> <listitem>
Implementing the View <listcell label="George"/> <listcell label="House Painter"/> </listitem> <listitem> <listcell label="Mary Ellen"/> <listcell label="Candle Maker"/> </listitem> <listitem> <listcell label="Roger"/> <listcell label="Swashbuckler"/> </listitem> </listbox> </zk>
47
The Shopping cart view Implementation The implementation of the shopping cart view is placed in the right side section of the Borderlayout [1]. Just like the previous section, the Listbox [7] is encased by a Div [2] component which is applied with a controller class to extend the GenericForwardComposer [1] class. Well go into details of this controller class in the next section of this book. The only special part of the Listbox [7] that we havent covered is the Listfooter [5] which is encased in the tag Listfoot [6]. This will place the specified components on the buttons. In this case, it would be the subtotal with a button to submit an order and a button to clear the order. <east
title="Shopping Cart" size="30%" flex="true" splittable="true" collapsible="true"> <div style="background:#E6D92C; height:100%" apply="demo.web.ui.ctrl.Shopping
<listbox id="shoppingCartListbox"> <listhead sizable="true"> <listheader label="Name" /> <listheader label="Price" /> <listheader label="Amount" /> <listheader label="subTotal"/> <listheader align="center"/> </listhead> <listfoot> <listfooter span="2" id="subtotalFooter"></listfooter> <listfooter><button id="submitOrderBtn" label="submit"/></l <listfooter><button id="clearBtn" label="clear"/></listfoot </listfoot> </listbox> <textbox id="descTxb" rows="10" width="200px" value="Note for this orde
48
References
[1] [2] [3] [4] [5] [6] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Listhead. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Listheader. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Listcell. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Listitem. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Listfooter. html# http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Listfoot. html#
Using a ListModel and ListitemRenderer and call GenericForwardComposer.doAfterCompose(org.zkoss.zk.ui.Component) [3] method of its super class and implement the code that assigns a model and renderer to our Shopping cart Listbox [7]. ShoppingCartViewCtrl.java public class ShoppingCartViewCtrl extends GenericForwardComposer { private Listbox shoppingCartListbox; @Override public void doAfterCompose(Component comp) throws Exception { super.doAfterCompose(comp); //create model shoppingCartListbox.setModel(...); //assign model to Grid //create renderer shoppingCartListbox.setItemRenderer(...);//assign renderer to Grid ... } }
49
<listbox id="shoppingCartListbox"> <listhead sizable="true"> <listheader label="Name" /> <listheader label="Price" /> <listheader label="Amount" /> <listheader label="subTotal"/> <listheader align="center"/> </listhead> <listfoot> <listfooter span="2" id="subtotalFooter"></listfooter> <listfooter><button id="submitOrderBtn" label="submit"/></l <listfooter><button id="clearBtn" label="clear"/></listfoot </listfoot> </listbox> <textbox id="descTxb" rows="10" width="200px" value="Note for this orde <image id="cartItemImage" /> </div>
50
From here we know that the data passed to the method is a <mp>CartItem</mp> as set in our model. We need to populate 5 columns and therefore need to create 5 Listcells. The first 3 items can be extracted from the data bean and easily placed into Listcells, however, the last two items consist of a sub total and a cancel button. To implement the subtotal and cancel button we create two private functions in our anonymous class named <mp>initSubTotal</mp> and <mp>initCancelBtn</mp> respectively. shoppingCartListbox.setItemRenderer(new ListitemRenderer() { public void render(Listitem listItem, Object data) throws Exception { final CartItem cartItem = (CartItem)data; final Product prod = cartItem.getProduct(); listItem.setValue(cartItem); new Listcell(prod.getName()).setParent(listItem); new Listcell(""+prod.getPrice()).setParent(listItem); new Listcell(""+cartItem.getAmount()).setParent(listItem); initSubTotal(cartItem, new Listcell()).setParent(listItem); initCancelBtn(cartItem, prod, new Listcell()).setParent(listItem); } private Listcell initSubTotal(CartItem cartItem, Listcell cell){ float price = cartItem.getProduct().getPrice(); float subTotal = price * cartItem.getAmount(); Label subTotalLb = new Label("$ "+subTotal); subTotalLb.setStyle("word-wrap: word-break"); subTotalLb.setParent(cell); return cell; } private Listcell initCancelBtn(final CartItem cartItem, final Product prod, Listcell cell){ Button button = new Button();
Using a ListModel and ListitemRenderer button.setImage("/image/DeleteCross-16x16.png"); button.addEventListener(ON_CLICK, new EventListener() { public void onEvent(Event event) throws Exception { _cartModel.remove(cartItem); refresh(); } }); button.setParent(cell); return cell; } }); Lets look more into these two functions. private Listcell initSubTotal(CartItem cartItem, Listcell cell) { float price = cartItem.getProduct().getPrice(); float subTotal = price * cartItem.getAmount(); Label subTotalLb = new Label("$ "+subTotal); subTotalLb.setStyle("word-wrap: word-break"); subTotalLb.setParent(cell); return cell; } private Listcell initCancelBtn(final CartItem cartItem, final Product prod, Listcell cell){ Button button = new Button(); button.setImage("/image/DeleteCross-16x16.png"); button.addEventListener(ON_CLICK, new EventListener() { public void onEvent(Event event) throws Exception { _cartModel.remove(cartItem); refresh(); } });
51
Both these functions take the cartitem along with a Listcell [3] and return a Listcell [3]. In the method <mp>initSubTotal</mp> the subtotal is calculated, placed into a Label [6] which has a style set. Finally the Labels parent is set and returned. Label subTotalLb = new Label("$ "+subTotal); subTotalLb.setStyle("word-wrap: word-break"); subTotalLb.setParent(cell); return cell; The cancel function is slightly more indepth than the subtotal function because it constructs a button, sets its image and then adds an EventListener [3] to itself to listen for the ON_CLICK event. The advantage of a renderer displayed here as a reference to the <mp>Cartitem</mp> is that it becomes very easy to create an anonymous EventListener [3]
Using a ListModel and ListitemRenderer implementation which can remove the <mp>cartitem</mp> from the model as the object reference is freely available. Finally if we return to the original implementation of the ListItemRenderer parent to the given Listitem [4] so they can be displayed appropriately.
[2]
52
[3]
public void render(Listitem listItem, Object data) throws Exception { final CartItem cartItem = (CartItem)data; final Product prod = cartItem.getProduct(); listItem.setValue(cartItem); new Listcell(prod.getName()).setParent(listItem); new Listcell(""+prod.getPrice()).setParent(listItem); new Listcell(""+cartItem.getAmount()).setParent(listItem); initSubTotal(cartItem, new Listcell()).setParent(listItem); initCancelBtn(cartItem, prod, new Listcell()).setParent(listItem); } Just as with the Grids RowRenderer [3], the ListItemRenderer [2] is a series of instructions assigning the UI components with values; using a View-Model-Renderer approach. Any changes in the data model will be translated to update in the UI component when the renderer code is run.
References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ ListitemRenderer. html# [2] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ ListItemRenderer. html#
53
References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ event/ SelectEvent. html# [2] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zk/ ui/ event/ SelectEvent. html#getSelectedItems()
54
55
public String getFullName() { return _firstName + " " + _lastName; } } Declare the data bean in ZUL file Instantiate the Person class in zscript: <window> <zscript><![CDATA[ //prepare the person object import bean.Person; Person person = new Person(); person.setFirstName("Max"); person.setLastName("Planck"); ]]> </zscript> // UI declaration </window> Activate the Annotated Data Binding Manager We activate the data binding manager by declaring the page initiator. Then the initiator will do the following automatically for us: 1. Create an instance of AnnotateDataBinderInit [1]. 2. Sets the AnnotateDataBinder instance as a variable with the name "binder" stored in the component as specified in arg0 "component-path"(if arg0 is not specified, use Page instead). 3. Calls DataBinder.loadAll() to initiate all UI components from the associated data source. <?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit" ?> Declare Components for Annotated Data Binding Now we declare the components in our ZUL file to apply the annotated data binding mechanism: <?init class="org.zkoss.zkplus.databind.AnnotateDataBinderInit" ?> <window> <zscript><![CDATA[ //prepare the person object import bean.Person; Person person = new Person(); person.setFirstName("Max"); person.setLastName("Planck"); ]]> </zscript> <grid width="400px"> <rows> <row> First Name: <textbox value="@{person.firstName}"/></row> <row> Last Name: <textbox value="@{person.lastName}"/></row> <row> Full Name: <label value="@{person.fullName}"/></row>
The Concept of Data Binding </rows> </grid> </window> The result is a table with 3 rows, when user enters values in the textboxes and an onChange event is fired, the lable in the last row is updated instantly.
56
The Concept of Data Binding </window> At line 2, we declare an initiator for the annotated data binder. From line 4 through 14, we prepare the data collection. In this example, we dynamically generate a list of the Person data objects and iteratively set the first and last names for each. Since we are using the data collection to populate the Listbox [7] component, we use ZK's annotated data binding syntax to assign it with a data model (line 17); in this case, persons is the data collection we instantiated earlier in zscript will be applied to the data binder. For each Listitem [4] (an listitem in listbox is analogous to a row in grid), we assign each with a Person object and the object's attributes (first name, last name, full name) to each cell of the listitem. When this simple composition, we are able to populate the whole Listbox with our "Persons" data collection. Let's summarize what needs to be done for annotated data binding a UI component with a data collection: 1. declare the initiator for annotated data binder (line 2) 2. prepare the data collection (zscript is used in this sample, the Java code can be placed in an controller class instead) 3. annotate the UI component (Grid [6], Listbox [7]) for data binding with the data collection name (line 17) 4. annotate the row element (Listitem [4] for Listbox [7]; Row [2] for Grid [6]) with the data object (Person) by iterating through data object collection (Persons). 5. annotate each cell in the row element with the respective data object property
57
References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zkplus/ databind/ AnnotateDataBinderInit. html# [2] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Row. html#
58
Implementing Data Binding return orders; } private static OrderDAO getOrderDAO(){ return new OrderDAO(); } public void onClick$cancelOrderBtn(){ if(orderLibox.getSelectedItem()==null){ return; } Order order = (Order) orderLibox.getSelectedItem().getValue(); cancelOrder(order.getId()); } public void onSelect$orderLibox(){ if(cancelOrderBtn.isDisabled()) cancelOrderBtn.setDisabled(false); } private void cancelOrder(Long orderId) { //1. Do the update using DAO getOrderDAO().cancelOrder(orderId); //2. update UI AnnotateDataBinder binder = (AnnotateDataBinder) page.getAttribute("binder"); binder.loadAll(); } } At line 11, we save this controller class as a desktop attribute so that it could be retrieved anywhere within the desktop scope Since we'll need to supply the annotated data binder in the data collection we use for the grid, we keep the code at line 17 so the data binder could call out this code and fetch the data collection. Now we proceed to applying data binding to the Orders View.
59
Implementing Data Binding From line 12 through 14, we get the order object's properties and append it to the labels in the list cells. (the attribute "converter" will be covered in the subsection to follow) index.zul <south
60
size="250px" flex="true" border="0" splittable="true" collapsible="true" style="o <div id="orderArea" style="background:#E6D92C; height:100%" apply="demo.web.u
<listbox id="orderLibox" model="@{orderArea$composer.orders}" selectedItem="@ <listhead> <listheader label="info"/> <listheader label="description"/> <listheader label="Sub Total"/> </listhead>
<listitem self="@{each='order'}" value="@{order}"> <listcell label="@{order, converter='demo.web.ui.OrderInfoTypeCon <listcell label="@{order.description}" /> <listcell label="@{order.total}" /> </listitem> </listbox>
<grid id="orderItemsGrid" model="@{selectedOrder.items}"> <columns sizable="true"> <column label="Name"/> <column label="Quantity"/> <column label="Price"/> <column label="Sub Total"/> </columns> <rows> <row self="@{each='orderItem'}"> <label value="@{orderItem.name}"/> <label value="@{orderItem.quantity}"/> <label value="@{orderItem.price}"/> <label value="@{orderItem, converter='demo.web.ui.OrderItem </row> </rows> </grid> <button id="cancelOrderBtn" label="Cancel Selected Order"/> </div> </south>
object
61
To convert Date to String, we'll need to implement the TypeConverter [2] interface. OrderInfoTypeConverter.java package demo.web.ui; import org.zkoss.zk.ui.Component; import org.zkoss.zkplus.databind.TypeConverter; import com.sun.jna.FromNativeContext; import demo.model.OrderDAO; import demo.model.bean.Order; public class OrderInfoTypeConverter implements TypeConverter { // Save public Object coerceToBean(Object val, Component comp) { throw new UnsupportedOperationException(); } //Load public Object coerceToUi(Object val, Component comp) { Order order = (Order) val; String info = order.getStatus()+" : "+ Consts.YYYY_MM_DD_hh_ss.format(order.getCreateDate()); return info; } } There are two methods that we must implement, one is coerceToBean (converting data type and save into bean), the other is coerceToUi (converting data type and load to UI component). In our case, we have a Date object in bean and need to convert that to String and then display it in an UI component, so we implement the coerceToUi method as shown in the snippet above. In our UI markup, index.zul, we then include the converter in the databinding annotation as such: <listcell label="@{order, converter='demo.web.ui.OrderInfoTypeConverter'}" />
62
1. We could call Listbox.getSelectedItem() [3] in ZUL (line 4) using annotations to retrieve the list item selected: selectedItem="@{selectedOrder}" 1. here selectedOrder is just an arbitrary variable we declare to reference the Order data object 2. At line 18, we call the Order object's getItems method to retrieve a list of "OrderItem" data objects and assign that list to the grid component as its model. 1. OrderItem is a wrapper for the Product object, with additional information such as the quantity being ordered, the price, and the subtotal. 3. At line 26, we associate each row with each OrderItem; a row is created automatically for each OrderItem 4. From line 27 through 30, the getter methods for the OrderItem's properties are called and their values are assigned to the labels. As it's illustrated here, ZK's data binder automatically does a lot of wiring work for us behind the scenes. In the next subsection, we will discuss when it is a good idea to implement data binding and when it is not.
References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ java/ util/ Date. html# [2] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zkplus/ databind/ TypeConverter. html# [3] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zul/ Listbox. html#getSelectedItem()
63
With ZK handling, transferring the data to the client is substantially easier. A ZK developer is able to leverage any application or ORM framework such as Spring and Hibernate without the need to perform any special tasks. If you are familiar with Hibernate you do not need to read any further as the standard List of objects retrieved from ORM frameworks is compatible with ZK's model concept. Thus from using the knowledge gained in the previous sections you can construct your own application. This chapter introduces to those who are unfamiliar with ORM framworks to Hibernate and ZK. The following sections will provide a simple tutorial on refactoring our current application to make good use of persistent storage.
64
65
Setting up Hibernate
Hibernate requires configuration to work. Our sample application contains two configuration files placed in the folder included in the classpath: 1. log4j.properties 2. hibernate.cfg.xml The log4j.properties file is used to inform Log4j of the level we wish to log. In our case we set the lowest level of logging possible which in this case is DEBUG and TRACE for the hibernate classes. Setting this to such a fine grained setting enables us to see exactly what is going on during hibernate. The second file hibernate.cfg.xml contains detailed configuration for Hibernate in XML format. The content is provided and analyzed below.
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE hibernate-configuration PUBLIC "-//Hibernate/Hibernate Configuration DTD 3.0//E <hibernate-configuration> <session-factory> <property name="hibernate.dialect">org.hibernate.dialect.HSQLDialect</property> <property name="hibernate.connection.driver_class">org.hsqldb.jdbcDriver</property> <property name="hibernate.connection.url">jdbc:hsqldb:file:data/store</property> <property name="hibernate.connection.username">sa</property> <property name="hibernate.show_sql">true</property> <property name="hibernate.current_session_context_class">thread</property> <property name="hibernate.query.factory_class">org.hibernate.hql.classic.ClassicQuery
<property name="hibernate.hbm2ddl.auto">create-drop</property> <mapping class="demo.model.bean.Order"/> <mapping class="demo.model.bean.OrderItem"/> <mapping class="demo.model.bean.User"/> <mapping class="demo.model.bean.Product"/> </session-factory> </hibernate-configuration> Line 5 let hibernate know that we intend to use HSQLDialect as it is an HSQL database Line 6 specifies the jdbc driver class Line 7 is the path to the datastore, in this case informing HSQLDB that we will make use of a file named store in the folder data Line 8 is the username, in this case a default sa Line 9 dictates that we would like Hibernate to print out the SQL Line 10 states that the session context is thread based Line 11 states that the HQL style we would like to use is classic HQL is Hibernates own query language. For more information please click here [1] Lines 14-19 are to do with definition of the entity types within the application and generation of the database. These topics are covered in the following section.
66
References
[1] http:/ / docs. jboss. org/ hibernate/ core/ 3. 3/ reference/ en/ html/ queryhql. html
One of the most important properties in this XML file is hibernate.hbm2ddl.auto which will be set as create-drop. When Hibernates SessionFactory is set, it will automatically create an option which validates or exports the schema DDL to the database. This is very useful during the process of developing a data driven application as it eliminates the need to manually update SQL scripts when your schema needs to change. However, this setting is not recommended for production usage. NOTE: As the database schema is generated and dropped at the beginning and end of every session, this means that the data is not persisted at the end of the application. By changing this to update the data it will be persisted across multiple runs. The other properties enable the mapping of Java classes to Database tables. In general, this mapping is declared in two ways: By providing the class name using the attribute <mp>class</mp> By providing a URI to an XML resource which describes the mapping Both mapping by XML or annotation can achieve the same results but selecting which implementation method to deploy will depend on the developer's preference. Some developers prefer XML while others incline towards annotations. In this case we chose to use annotations.
Hibernate, Entities and Database Generation private long id; @Column(name="productname") private String name; @Temporal(TemporalType.TIMESTAMP) private Date createDate; private float price; private int quantity; private boolean available; private String imgPath; } The above code demonstrates how the <mp>Product</mp> class was annotated to allow persistence. Taking the annotations one at a time we will explore what they do. @Entity An entity can be considered as a lightweight persistence domain object which represents a table in a relational database. In this case we let Hibernate know that the class Product is an entity. This is required if you would like to introduce database persistence to classes. @Table(name="products") The table entity is set at the class level which enables us to define the table, catalog and schema names of the entity mappings. If names are not specified the default values will be used. However, in our case Product is an SQL reserved word therefore we have to change the table name to products. @Id We need to let Hibernate know which field of ours is the ID and this can be easily achieved by applying the annotation @Id. @GeneratedValue(strategy=GenerationType.AUTO) Along with the annotation, @Id, we also need to inform Hibernate that it is auto-incremented by the database. We let Hibernate know by using the @GeneratedValue annotation and setting the strategy to GenerationType AUTO. @Column(name="productname") The next annotation refers to the definition of a column. Under normal circumstances we do not need to provide a name however, in this case without specifying the name of the column it would default to "name." Just as "product", "name" is also an SQL reserved keyword hence we specify a valid column name, "productname".
67
Hibernate, Entities and Database Generation @Temporal(TemporalType.TIMESTAMP) Java APIs do not define the temporal precision of time. Sometimes we would like to describe the expected precision when placing data into persistent storage. To do this we use the Temporal attribute. Types include DATE, TIME and TIMESTAMP. The rest of the classes in our example use the same annotation strategies. There is only one exception present in Order.java which describes the relationship between an <mp>Order</mp> and its <mp>OrderItems</mp>.
68
In order for Hibernate to generate the database schema and map the relationship correctly we need to describe it. To do this we use two annotations: @OneToMany @JoinTable Lets explore the relative code. @OneToMany @JoinTable( name="OrderedItems", joinColumns=@JoinColumn(name="orderid"), inverseJoinColumns=@JoinColumn(name="orderitemid") ) @LazyCollection(value=LazyCollectionOption.FALSE) private List<OrderItem> items = new ArrayList<OrderItem>(); The "name" attribute tells Hibernate the table name which we would like to use or in our case to create. The "joinColumns" attribute requires the foreign key columns of the join table which reference the primary table of the entity owning the association, in this case the order id. On the other hand the "inverseJoinColumns" attribute requires the foreign key columns of the join table which reference the primary table of the entity that does not own the association, in this case the OrderItems id. We provide both attributes a "@joinColumn". Annotations require "name" and "referencedColumnName" which are the name of the column in the table OrderedItems and the name of the referenced column within the entity
Hibernate, Entities and Database Generation respectively. The <mp>Order</mp> owns the association (ie. Owns the Order items) so its key is passed to "joinColumns" and <mp>OrderItem</mp> does not own the association so its information is passed to "inverseJoinColumns."
69
Lazy Loading
There is one last thing to consider; when an <mp>Order</mp> object is loaded we want to load its <mp>OrderItems</mp> at the same time. Hibernate only loads the first object level which can lead to exceptions such as a LazyLoadException when we access the item list which has not been initialized. It means that when the Order object is loaded then the its OrderItems arent. In this case it is easy to fix by making use of the @LazyCollection annotation and setting the option to FALSE: @LazyCollection(value=LazyCollectionOption.FALSE) This will ensure that when an <mp>Order</mp> is loaded its <mp>OrderItems</mp> are too. When designing larger systems we have to take into account how much data should be loaded and whether we should follow lazy loading practices or not. For the purposes of this chapter lazy loading is not required. The final section introduces Hibernate Session management and how we implemented the DAOs.
Hibernate Session Management and Implementing the DAOs } } public static SessionFactory getSessionFactory() { return sessionFactory; } public static Session openSession() { return sessionFactory.openSession(); } } In this class, the SessionFactory is built statically upon first accessing the object and then provides static utility methods to access the SessionFactory and then open a new Session. Please note that there is no need to build the SessionFactory when the application loads or close it when the application terminates. To do so, we implement two ZK interfaces, WebAppInit and WebAppCleanup and specify the implementing class in the zk.xml file: public class HibernateListeners implements WebAppInit, WebAppCleanup { public void init(WebApp webapp) throws Exception { //initialize Hibernate StoreHibernateUtil.getSessionFactory(); } public void cleanup(WebApp webapp) throws Exception { //Close Hibernate StoreHibernateUtil.getSessionFactory().close(); } } <zk> <listener> <listener-class>demo.model.HibernateListeners</listener-class> </listener> </zk> In this case, we named our class <mp>HibernateListeners</mp> and made sure that the <mp>SessionFactory</mp> was built on initialization of the web application and closed in the cleanup method. This initializes and closes Hibernate now and we need to make use of it in the DAOs.
70
Hibernate Session Management and Implementing the DAOs Sessions and Transactions in Hibernate please click here [1]. Lets take a simple use <mp>ProductDAO.java</mp>: case for retrieving all the available <mp>Products</mp> found in
71
public List<Product> findAll(){ //return new ArrayList<Product>(dbModel.values()); Session session = StoreHibernateUtil.openSession(); Query query = session.createQuery("from products"); List<Product> products = query.list(); session.close(); return products; } In this code snippet, we utilize our <mp>HibernateUtil</mp> to open a new session at line 3 and then create a query. The query is written in HQL (Hibernate Query Language) retrieving all the rows from the table products. For more information on HQL please click here [1]. Once we create the Query object, we can use its listed method to retrieve the <mp>List</mp> of products, close the session and then return. At the same time sometimes we need to retrieve all available <mp>Products</mp>. This means we need to retrieve all the Products where available is equal to true. In our example, we do this by creating a Criteria object: public List<Product> findAllAvailable(){ Session session = StoreHibernateUtil.openSession(); Transaction t = session.beginTransaction(); Criteria criteria = session.createCriteria(Product.class).add(Restrictions.eq("available", true)); List<Product> products = criteria.list(); t.commit(); session.close(); return products; } The snippet follows the same session management strategy, however, this time we create a <mp>Criteria</mp> object to add a restriction that "available" must be true. Then we can use the method <mp>criteria.list()</mp> to retrieve a list of products which are available. The retrieval methods in each DAO follow a similar strategy so finally lets take a look at the add method of the <mp>OrderDAO</mp> which persists an <mp>Order</mp>. public void add(Order order){ Session session = StoreHibernateUtil.openSession(); Transaction t = session.beginTransaction(); session.persist(order); t.commit();
Hibernate Session Management and Implementing the DAOs session.close(); } We see that the Session management strategy is exactly the same, however, now we use the sessions persist function to add the <mp>Order</mp> object to the session, then we commit the transaction and close the session. This will then add the Order object to the relative table.
72
References
[1] http:/ / community. jboss. org/ wiki/ sessionsandtransactions
Hibernate Summary
As demonstrated by this tutorial Hibernate is highly configurable and very powerful. This chapter covered the very basic annotations and usage of Hibernate, therefore when employing the power of Hibernate for a larger application we should further explore Hibernate's options such as not allowing null values for certain table columns. For a complete list of Hibernate's annotations please click here [1].
References
[1] http:/ / docs. jboss. org/ hibernate/ annotations/ 3. 5/ reference/ en/ html_single/
Components
Components are UI elements that an application developer put them together to build the application UI, just like LEGO bricks. Consult ZK_Component_Reference guide on what children components a particular component can have. Components can be declared in ZUML (ZK User Interface Markup Language, in XML syntax), or alternatively, in Java. Components (POJO) run on JVM on the server, and they have their counter parts (widgets - JS objects) on the client side. User activities on widgets are reflected to the components on the server. Component updates are reflected back to the widgets on the client side. A Page [8] is a "stage" where components come on and off to play their parts and fulfill their roles. Components are conceptually grouped in ID Spaces; we can call the getFellow() [7] method on one component to get another component as long as they are in the same ID Space. By default, components declared in Window [1] form an ID Space (including Window [1] itself) with Window [1] being the ID Space Owner. By default, a Page [8] is an ID Space Owner; any component can become the ID Space Owner by implementing IdSpace [9]
73
Events
User activities (eg. onClick) and system notifications (eg. server push) are abstracted to event objects. Event listeners on components must be registered so that event objects can be created and forwarded. By default, all events are sent to the server for processing. With ZK's Server+Client Fusion architecture, events could also be handled at the client directly. Event handling code can be declared as a component attribute in ZUL. Events can be forwarded to a controller class for handling. Event listeners can be added dynamically in Java.
ZK MVC
The ZK MVC approach provides a great separation among data (aka. model), UI and business logic (aka. control). Under the ZK MVC pattern, UI components are declared with ZUML in ZUL files. Tasks such as setting a component's data model and renderer, component manipulation are implemented in a Controller class in Java The controller class should extend GenericForwardComposer [1] so the components declared in ZUL can be referenced in Java code. Events are automatically forwarded to the controller class for handling.
74
Performance Tips
Please follow these guidelines for building performance critical enterprise applications: ZK Developer's Reference/Performance Tips
References
[1] http:/ / www. zkoss. org/ javadoc/ latest/ zk/ org/ zkoss/ zki/ ui/ util/ GenericForwardComposer. html#
75
76