ZK Framework Tutorials

Home

ZK-Framework - Creating the Pages

Read from beginning sample Chapter 2 - Online Media Library
ZK-Framework - Online Media Library
Setting up Eclipse to Develop with ZK
Setting up a New Project

Creating the Pages

After the implementation of the model classes (which is not in the scope of this book) it's time to start with implementing the ZUL pages. The first page is index.zul which should be a simple navigation page for the individual pages.

A simple way to execute the individual pages is to offer links for each page on the starting page. In a simple HTML page, we would use a href tag. In a ZUL page the preferred way is to use toolbarbutton. With the following line we add a link to add-media.zul:

We need four navigation points, and therefore, four pages to fulfill the requirements of the CRUD feature. These four pages are:

Add a new media item: add-media.zul
Update an existing media item: update-media.zul
Delete an existing media item: delete-media.zul
Show media: show-media.zul

The navigation page is depicted in the following figure:

To have a border with a title, the window component of ZK is used. With the help of the div component, the window component is centered. The next problem we have to solve is that each link should appear on a new line. This is achieved by using the br tag from HMTL. Hence, we have to define the XHTML namespace.

The complete implementation of the page is shown below:

{qbacode language=XML}

{/qbacode}

{qbapagebreak title=Menu Page with Result Page}

A better solution for the scenario is to combine the result page and the menu on one page. Therefore, we need no extra page for showing the media. The redesigned first page (index.zul) is shown in the figure below:

For displaying the result in the first step, we use the listbox component. The first column is an image with a link to remove a media item. Here, we can use the toolbarbutton component with the image attribute.

<toolbarbutton image="images/trashcan.gif" />

To define the header of the grid, we can use the listhead component in combination with the listheader component.

<listhead>
<listheader label="" />
<listheader label="Id" />
<listheader label="Title" />
</listhead>

NOTE: To represent a list of data you can use the listbox component or the grid component. To decide whether to use the grid component or the listbox component you have to define what you want to do with the data. A grid component is designed for showing data. The main use of listbox is to show data that should be selected by the user.

The data for the listbox component is provided from the underlying model classes. The model classes are simple POJO (Plain Ordinary/Old Java Objects).

NOTE: How to use the ${each} variable inside a zscript block
The ${each} is an Expression Language variable, and therefore, it cannot be used directly inside a zscript block. But in some cases (especially in event handlers) it's very useful to use ${each}. It's possible to define a custom attribute, and place the variable in the custom-attributes map for the component. With <custom-attributes thename="${each}"/> the ${each} is stored with key thename in the mentioned map. In the zscript block, it's now possible to access this object with componentScope.get("thename").

The data int he listbox component is shown with the help for the forEach attribute in combination with the ${each} EL (Expression Language) variable.

{qbacode language=xml} {/qbacode}

{qbapagebreak title=Redesigned Page}

The full implementation of the redesigned page is given below. Here, we want to mix elements from XHTML with elements from ZUL. For that we need a clear separation of the two worlds. In an XML file, there is an element that helps us to do this separation, the namespace. If we use a namespace we have to add a prefix to each tag from that namespace (e.g. <html:br />). For further information about namespaces visit http://"www.w3.org/TR/REC-xml-names/" target="_blank" rel="nofollow".

{qbacode language=xml}

MediaDAO dao = MediaDAOFactory.getDAO(); Collection list = dao.getMedia();

Remove the media. {/qbacode}

NOTE: How to implement a tooltip
One aim in the design of user interfaces should be 'as easy as possible'. However, the user should also be guided with some help by the application itself on his or her first touch. One help could be a tooltip for the elements. For this, most of the ZK elements have the tooltip attribute (e.g: <button label="Upload" tooltip="tooltip.upload">). The tooltip itself is realized with the help of the popup component. That means, beyond the tooltip attribute, you have to provide a popup implementation for the tooltip (e.g. <popup id="tooltip.upload">Upload a image for the media.</popup>).

Sometimes we m ay want to provide some error handling for the page, especially, if we have to add a warning dialog before we really remove a media item from the underlying persistent storage.

{qbapagebreak title=Store data in model classes}

The last screen that we want to implement in the first round is the page for adding new media.

The following figure shows the page:

NOTE: How to store data in the model classes
On one side, we have the ZUL page, and on the other side the model classes. In the case of entering data, the programmer would want to use the model class directly to store the data. For this, we need some "glue" code. The ZK framework solves that by binding of data with annotations in the ZUL pages. To use such annotations we have to define a namespace for them: xmlns:a=http://"www.zkoss.org/2005/zk/annotation" target="_blank" rel="nofollow". Additionally, we also have to initiate the mechanism of annotation in the page. This is done with a special init class (org.zkoss.zkplus.databind.AnnotateDataBinderInit). Now the page is ready to bind the input directly to the model classes. To bind data, we have to place an annotation over a normal element (e.g. <a:bind value="object. name" /> binds the following input to the name property to object; note: we have to create an instance object in the zscript block).

The uploading of an image is done with the Fileupload dialog from the ZK framework.

NOTE: If you want to upload more than one file within one dialog you should use the Fileupload.get(int) method. For example Fileupload. get(5) presents a dialog with five fields for five uploads.

First we have to define a button component where we connect the onClick event (<attribute name="onClick">) with the opening of the dialog.

{qbacode language=XML}{/qbacode}

If the uploaded file is an unacceptable media we would like to provide an error message to the user. For that, we use Messagebox from the ZK framework.

Messagebox.show("Not an image: "+media, "Error",
Messagebox.OK, Messagebox.ERROR);

The mentioned Messagebox is shown as a modal dialog. An example of the appearance in the case of an error is shown in the following figure.

The gray background comes from the ZK framework. You have to acknowledge the message by clicking the OK button.

After the upload of a correct image it is shown directly, and without reloading the page. To set the image on the correct component, we address the component with id. For that we defined an image component with id="image".

{qbapagebreak title=Validations}

The field id is extended with two validations. The first validation is done while the user inserts some input into the field. For that we provided some code for the onChanging handler. If the user types only white spaces there is the warning not valid on the right side. Otherwise the green note valid is presented.

{qbacode language=XML} if (event.getValue().trim().length() > 0) { idstatus.setValue("valid"); idstatus.setStyle("color:green"); } else { idstatus.setValue("not valid"); idstatus.setStyle("color:red"); } {/qbacode}

The next validation is done in the onChange handler.

{qbacode language=XML} if (self.value != null && self.value.trim().length() == 0) { self.value = ""; throw new WrongValueException(self, "The id shouldn't be the empty string."); } {/qbacode}

We use the possibility to throw a org.zkoss.zk.ui.WrongValueException. If this exception occurs the framework shows an error message linked to the concerned field. The following figure shows such an error message.

NOTE: It's important to say that the code in an event handler or a zscript must bevalid XML, because a ZUL page is an XML page. Here, we are confronted with the problem of using some special characters (e.g. & or <). We have two possibilities to use such characters. The first is to use valid XML entities (e.g. && for &&) or we can embed the code in a CDATA block (<![CDATA[ ? ]]>). For more readable code it's recommended to use the CDATA block variant.

{qbapagebreak title=Complete Implementation}

The complete implementation of add-media.zul is presented below:

{qbacode language=XML} import com.packtpub.zk.media.model.MediaType; import com.packtpub.zk.media.dao.*; if (event.getValue().length() == 0) { titlecount.setValue(""); } else { //titlecount.setValue("" +event.getValue().length()); titlecount.setValue(com.packtpub.zk.media. MyDataProvider.next()); } MediaType[] types ={ MediaType.Song,MediaType.Movie}; if (event.getValue().trim().length() > 0) { idstatus.setValue("valid"); idstatus.setStyle("color:green"); } else { idstatus.setValue("not valid"); idstatus.setStyle("color:red"); } if (self.value != null && self.value.trim().length() == 0) { self.value = ""; throw new WrongValueException(self, "The id shouldn't be the empty string."); } //prepare the media instance com.packtpub.zk.media.model.Media media = com.packtpub.zk.media.model.MediaFactory.create(); MediaDAO dao = MediaDAOFactory.getDAO(); The title of the media. A Song. A Movie. The id for the media. That is a user defined id. The id must be unique. The description for the media. Upload a image for the media. {/qbacode}

NOTE: How to redirect to other pages
It is often necessary to redirect to another page after an action is executed. In that case, the ZK framework offers the general utility class org.zkoss.zk.ui.Executions. This method offers the sendRedirect method. In a ZUL page, you could directly access the Executions instance and redirect to another page (e.g. Exectutions. sendRedirect('index.zul')). A redirect sends a response to the client giving it a new URL. The client then requests the new URL. A forward happens internally in the servlet container. The target is given the chance to respond to the original request. If you use the browser's back button the same request is sent again.

{qbapagebreak title=Adding textbox component}

For the first version of the update, we extend index.zul with a textbox component beside a toolbarbutton of Update a media.

The extended index.zul is shown below:

{qbacode language=XML}

MediaDAO dao = MediaDAOFactory.getDAO(); Collection list = dao.getMedia();

Remove the media. {/qbacode}

{qbapagebreak title=Toolbarbutton component}

The interesting point is the extended toolbarbutton component. The data is transferred with the sessionScope instance.

{qbacode language=XML} {/qbacode}

The page update-media.zul is similar to add-media.zul except that the creation of a media instance is replaced with retrieving of the media from sessionScope. For completeness the full implementation of update-media.zul is shown next.

{qbacode language=XML} import com.packtpub.zk.media.model.MediaType; import com.packtpub.zk.media.dao.*; if (event.getValue().length() == 0) { titlecount.setValue(""); } else { //titlecount.setValue(""+event.getValue().length()); titlecount.setValue(com.packtpub.zk.media. MyDataProvider.next()); } MediaType[] types = {MediaType.Song,MediaType.Movie}; if (event.getValue().trim().length() > 0) { idstatus.setValue("valid"); idstatus.setStyle("color:green"); } else { idstatus.setValue("not valid"); idstatus.setStyle("color:red"); } if (self.value != null && self.value.trim().length() == 0) { self.value = ""; throw new WrongValueException(self, "The id shouldn't be the empty string."); } The title of the media. A Song. A Movie. The id for the media. That is a user defined id. The id must not be unique. The description for the media. Upload a image for the media. {/qbacode}

Now we have a small, but running CRUD application with the ZK framework. In the coming chapters, we will improve this application step by step.

Summary

In this chapter, we started implementing a CRUD (Create?Read?Update?Delete) application. Before starting the implementation of the application, we created the setup of the ZK application in the web container.

After the preparation of the project, we defined some model classes to store data. After these cornerstones, we designed and implemented the pages with the ZK framework. We have not used the full functionality of the framework here, but showed some solutions for daily work with it.

The application has not finished with this chapter, but we have some base functionality, which we will further expand in the coming chapters.

Read Next: ZK-Framework - Online Media Library

ZK Framework Tutorials

ZK-Framework - Creating the Pages

Summary

Comments

Post Your Comment:

Sponsored Links