Integrating Yui-Ext into ZK Framework.

From Documentation
DocumentationSmall Talks2007JulyIntegrating Yui-Ext into ZK Framework.
Integrating Yui-Ext into ZK Framework.

Author
Jumper Chen, Engineer, Potix Corporation
Date
July 6, 2007
Version
Applicable to ZK 2.4 and later.
Applicable to yuiextz 0.5.0 only.


Introduction

Yui-Ext-- now called Ext JS, is a world famous client-side, JavaScript library for building web applications. However, using Yui-Ext JavaScript library with server side Java code is very complicated. But don't worry, ZK framework will as always do the complicated part for you.

In Yui-Ext library, there are many useful and amazing widgets and functions, In this small talk, Yui-Ext Grid is the one being focused on integrating into ZK framework. We will discuss how to use this ZK-ified Yui-Ext grid (we will call it Y-Grid for convenience) in this article. Basically, Y-Grid is a set of components following original ZK grid structure; i.e. grid, columns, column, rows, and row.


Prerequisite Software

The component is based on the ZK Ajax Framework, so you must download and install the ZK Ajax Framework.


Installation

Installation of Y-Grid is quite an easy task. Just follow these simple steps:

  • Step 1. Download the yuiextz release which can always be found here:yuiextz
  • Step 2. Unpack the Library distribution into a convenient directory.
lib/*.jar - The yuiextz.jar contains Java classes.
src - The src contains whole source code, and you will find it on ZK.forge Subversion.
  • Step 3. Copy the lib/*.jar file from the Library distribution into the WEB-INF/lib directory of your web application.


Let's Get Start

You can download the example file in yuiextz-example.zip. This zip only contains one file with "yuiextz-sample.zul", e.g.

<window title="Simply Yui-ext Componet Example" border="normal" 
  xmlns:y="http://www.zkoss.org/2007/yui">
  ...
  <y:grid onSelect="(org.zkoss.zk.ui.event.SelectEvent)event" 
    onColumnMoved="(org.zkforge.yuiext.event.ColumnMovedEvent)event" 
    trackMouseOver="true" multiple="true"> 
    <y:columns onColumnLockChange="(org.zkforge.yuiext.event.ColumnLockChangeEvent)event" >
      <y:column width="150px" label="Author"/>
      <y:column width="300px" label="Title"/>
      <y:column width="150px" label="Manufacturer"/>
      <y:column width="100px" label="ProductGroup"/>
    </y:columns>
    <y:rows>
      <y:row>
        <label value="Henri Chen"/>
        <label value="ZK Step-By-Step"/>
        <label value="Amazon"/>
        <label value="Book"/>
      </y:row>
      ...
    </y:rows>
  </y:grid>
  ...
</window>

Note : Using Y-Grid component needs to specify other namespace with http://www.zkoss.org/2007/yui and if you want to use Y-Grid component in the <zscript> tag with ZK component, you need to specify full package name for Java code to avoid confusion.


Run yuiextz-sample.zul in browser, then you will see the Y-Grid like the following:

Yuiextz-grid-1.gif


Here are two different styles. The top window is a new Y-Grid component, and the other one is ZK Grid component.

In this example,

<y:grid onSelect="(org.zkoss.zk.ui.event.SelectEvent)event" 
    onColumnMoved="(org.zkforge.yuiext.event.ColumnMovedEvent)event" 
    trackMouseOver="true" multiple="true">

You can see the <y:grid> tag including the following properties.

  • trackMouseOver: Sets whether to highlight rows when the mouse is over. Default: true.

Yuiextz-grid-2.gif


  • multiple: Sets whether multiple selection is allowed. Default: true.

Yuiextz-grid-3.gif

Note: When the Y-Grid has registered an onSelect event, you will get these rows from this event. You can use the "event.getSelectedItems()" way to receive these rows.


  • onColumnMoved:

Yuiextz-grid-4.gif


When a column is moved, you will get information of the moved column from this event (org.zkforge.yuiext.event.ColumnMovedEvent). Use the following method to get information of this event.

  • getOldColumn(): Returns the old column which is pre-stay in the place.(as Author)
  • getNewColumn(): Returns the new column which is staying now in the place.(as Title)
  • getOldIndex(): Returns the index of the old column from the list of Columns children.
  • getNewIndex(): Returns the index of the new column from the list of Columns children.


In this example,

<y:columns onColumnLockChange="(org.zkforge.yuiext.event.ColumnLockChangeEvent)event" >


You can also register an onColumnLockChange event on the <y:columns> tag. When you press right-click on the mouse from the header column, you will see as follows.

Yuiextz-grid-5.gif


And then click the Lock Column on the menu, you will see the first column to be locked as below.

Yuiextz-grid-6.gif

Note: When the column is locked or unlocked, the event(org.zkforge.yuiext.event.ColumnLockChangeEvent) will be fired. Therefore, you can use the "event.getLockedColumns()" way to receive these locked columns.


Download

Summary

Using this Y-Grid component is as easy as using other ZK components, and you can also enable rich UI operation , such as lock column, move column, select row, and so forth. You don't need to write JavaScript nor to know the Yui-Ext details. If you have any good ideas please feel free to let us know.




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