How to Wrap a jQuery UI Widget

{{Template:Smalltalk_Author|
|author=Peter Kuo, Engineer, Potix Corporation
|date=December, 2010
|version=ZK 5.0 and above
}}


= Introduction =

ZK5 has adapted the famous jQuery as underlying javascript library.
jQuery UI is also looking very promising. In this article, we'll see how jQuery UI's widgets can be easily wrapped to zk widget now, and enjoy the power of ZK.

= Demo =

<source lang="xml">
<datepicker id="target" numberOfMonths="2,2"/>
<button label="setNumberOfMonths(1)" onClick="target.setNumberOfMonths(1)"/>
</source>

<gflash width="700" height="600">Datepicker_sample_1.swf</gflash>


In above example,
we declare <code>datepicker</code> in zul, and then modify its property in Java.

= Benefit =

Any pure client widget can now easily connect to server.
ZK provides many server side ability.
Such as DataModel, Databindng, Event Handling.

You can use jQuery UI widget in more simplified syntax in zul, expression language is available too.
In extreme cases, you can even use only Java without any markup language or JavaScript, just like ZK always do.
You can also modify widget option at run time with Java.

And the best of all, you can modify the content of underlying data model with Java.
Then the widget content will be updated accordingly.

Through databinding, your interaction with client UI widget can automatically sync with java bean in server.<ref>under construction.</ref>
<references/>

= How to wrap =

Since it is only a wrapping, it's far more easy than implementing a whole new actual ZK component.

== setup files ==

*lang-addon.xml : Define <code>component-name</code>,<code>component-class</code>,<code>widget-class</code>, and load needed CSS file
*zk.wpd : Define widget package and load needed javascript file.
*zk.xml : Settings to make debug Javascript possible. Includes <code>debug-js</code>, <code>org.zkoss.web.classWebResource.cache</code>

Please download source code at [http://code.google.com/p/jquery4j/ jQuery4j]. It's concrete to work.

== JavaScript part==

In most common cases, you have to implement 4 methods:

===[http://www.zkoss.org/javadoc/latest/jsdoc/_global_/zk.html $define]===
It's the catcher to set initial options from <code>renderProperties()</code> in server. Also It's the catcher of setter function from server to modify widget option after it is initialized.

===redraw===
Provide html content as jQuery UI expected. The rest job will be delegated to jQuery UI in <code>bind_</code>.
	
===bind_===
Client event handler may send Event back to server.<ref>May search "fire" in *.js</ref>. Get options sended from <code>renderProperties()</code> in java. And call jQuery UI api to init it.<ref>If an field of option is undefined, jQuery UI will use its default value</ref>

<references/>

===unbind_===
Release jQuery UI widget, and zk widget.
	
== Java part==

Jobs includes updating data to client, and handle client event.

===getter, setter of fields===
<code>smartUpdate()</code> inside setter function will effect at client side <code>#define</code>. Setter function may do some check to see if the input value is acceptable. Some datatype conversion may need extra work. For example <code>"2,2"</code> inside <code><datepicker numberOfMonths="2,2"/></code> is String, and need to be converted int[].

===renderProperties===
It's used to initialize widget properties. Properties rendered will be catched by <code>$define</code> in client side, value would be available at client side <code>redraw</code>, <code>bind_</code>
	
===Event Handling===
You may use ZK defined event, or define your own event. To make your own event work, you have to do following things:

In Server side
*addClientEvent(): Adds an event that the client might send to the server
*service(): Processes an AU request. Event reported from client is handled here first. Update field in server side, <code>postEvent()</code> for further event handling.
*Register event handler at controller for test: Event without event handler may be not send to save network bandwidth.

In Client side
*call <code>fire("eventname",DataObject)</code>:It will send event to notify server<ref>eventName please follow <code>onXXX</code> naming convention.</ref>
<references/>
		
== Code example ==	

Because the field related code is much the same, you may define some template for different data type.
It's more easy to code and less error.

For example, related code for a boolean option field <code>disabled</code>

In Java:	
<source lang="java" >
	private boolean _disabled = false;
	
	public boolean getDisabled() {
		return _disabled;
	}
	
	public void setDisabled(boolean disabled) {
		if(_disabled != disabled){
			_disabled = disabled;
			smartUpdate("disabled", _disabled);					
		}
	}
	
	//inside renderProperties
	if(_disabled)
		render(renderer, "disabled", _disabled);
		(*if false, try renderer.render("disabled", _disabled))

</source>

In javascript
<source lang="javascript" >		
	//inside $define
	disabled :  function(){
		$(this.$n('cnt')).datepicker('option','disabled',this._disabled);
	},
	
	//options for init inside bind_
	,disabled: this._disabled	
</source>
	
===Execution sequence for both	server and client===

For example <code><datepicker disabled="true"/></code> sets the option <code>disabled</code> in zul, the execution sequence would be like:

#setDisabled:Modify <code>_disabled</code> variable in server. 
#renderProperties: Render the <code>_disabled</code> property to client side
#$define:catch <code>renderProperties()</code>, and set client side variables of widget <code>_disabled</code>
#redraw:<code>_disabled</code> is available now. <ref>If it's <code>_model</code>, can be used to change html output here. Please refer to source code of <code>accordion</code>, search "model")</ref>
#bind_:Use client side variable <code>_disabled</code> to initialize jQuery UI widget.

<references/>

== Test ==

To test ZK component functionality , you may test several use case:


<source lang="xml">
<datepicker id="target" numberOfMonths="2,2"/>
</source>
Above example can test if rendering is OK, and if String conversion to field is OK.

<source lang="xml">
<button label="setNumberOfMonths(1)" onClick="target.setNumberOfMonths(1)"/>
</source>
Above example can test if the setter function works fine.<ref>If the jQuery UI option not work as we think, you may test it in pure html first</ref>

<source lang="java">	
Datepicker target;	
public void onSelection$target(Event e) {
	System.out.println("Datepicker selection happen : "+ e);
}
</source>		
Above example can tell if event is send accordingly.

<references/>

= Demo Model Usage =
<source lang="xml">
<zscript>
<![CDATA[
	import org.zkoss.jquery4j.jqueryui.accordion.AccordionModel;    
	String[][] model = {{"t1","c1"},{"t2","c2"}};
	String[][] model2 = {{"tc1","cc1"},{"tc2","cc2"},{"tc3","cc3"}};
	AccordionModel tm = new AccordionModel(model);
	AccordionModel tm2 = new AccordionModel(model2);
	]]>
</zscript>

<accordion id="target" model="${tm}"/>
<button label="setModel(date)">
	<attribute name="onClick"><![CDATA[		
		target.setModel(tm2);
		]]>
	</attribute>    
</button>	
</source>
	
<gflash width="300" height="400">Accordion_sample_1.swf</gflash>
	
In above example, you can see the content of <code>accordion</code> is changed as we set different model to it.

= Differences between wrapped widget and ZK widget =	

*Childable: Currently wrapped jQuery UI widget must be leaf node of component tree. We're trying to found a way to implement such childable feature.

*styling: Since the HTML structure of widget is managed by jQuery UI, its styling does not follow ZK's rule. You can use [http://jqueryui.com/themeroller/ jQuery UI Themeroller] to customize

= Summary =
Although jQuery UI has only 8 widgets now, but it has planned to provide more in [http://wiki.jqueryui.com/ roadmap]. In [http://code.google.com/p/jquery4j/ jQuery4j], we already wrapped all 8 widgets.

There is still jobs to perfect this project. Including databinding, and childable component.

It's fun to have many other little widgets to enrich ZK. It's easier to wrap jQuery UI widget than jQuery widget than javascript widget. Since the former followes more coding discipline, less "surprise" to overcome.
Sometimes, widget from different source may conflict. For example, a fancy calculator jQuery Widget conflict
with jQuery UI library, because jQuery UI library rewrites some jQuery function <code>show()</code>.

It also provides another way to implement your own ZK component.
You may implement jQuery UI widget first, and then wrap it to ZK component.

= See Also =
*[http://code.google.com/p/jquery4j/ jQuery4j] in google code.
*[[ZK_Component_Reference]]
*[http://jqueryui.com/home jQuery UI]
*[http://wiki.jqueryui.com/ Roadmap of jQuery UI]

= Download =
[http://code.google.com/p/jquery4j/ jQuery4j] : Link /src,/src/archive as java src folder in Eclipse

{{Template:CommentedSmalltalk_Footer|
|name=Potix Corporation 
}}