Integrating Yui-Ext into ZK Framework.

{{Template:Smalltalk_Author|
|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=

[http://www.extjs.com/ 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:[http://sourceforge.net/project/showfiles.php?group_id=152762&package_id=238024 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 [http://zkoss.org/smalltalks/yuiextz-grid-1/yuiextz-example.zip yuiextz-example.zip]. This zip only contains one file with "yuiextz-sample.zul", e.g.

<source lang="xml" >
<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>       
</source>

'''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:

[[Image: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,

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

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

* <span style="color:green">trackMouseOver:</span> Sets whether to highlight rows when the mouse is over. Default: true.

[[Image:Yuiextz-grid-2.gif]]


* <span style="color:green">multiple:</span> Sets whether multiple selection is allowed. Default: true.

[[Image: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.


* <span style="color:green">onColumnMoved:</span>

[[Image: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.

:* <span style="color:purple">getOldColumn()</span>: Returns the old column which is pre-stay in the place.(as '''Author''')
:* <span style="color:purple">getNewColumn()</span>: Returns the new column which is staying now in the place.(as '''Title''')
:* <span style="color:purple">getOldIndex()</span>: Returns the index of the old column from the list of Columns children.
:* <span style="color:purple">getNewIndex()</span>: Returns the index of the new column from the list of Columns children.


In this example,

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


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.

[[Image:Yuiextz-grid-5.gif]]


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

[[Image: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=

*Download the [http://zkoss.org/smalltalks/yuiextz-grid-1/yuiextz-example.zip yuiextz-example.zip] for the article here.

*Download the <tracker url="http://sourceforge.net/project/showfiles.php?group_id=152762&package_id=238024" > yuiextz-0.5.0</tracker> version.

=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.


<comment>http://docs.zkoss.org/wiki/Integrating_Yui-Ext_into_ZK_Framework.</comment>

[[Category:Framework ]]
[[Category:Installation]]
[[Category:ZK]]
[[Category:3rd Pary Components]]
[[Category:Other Frameworks]]
{{Template:Smalltalk_Footer|
|name=Potix Corporation
}}