Small Talks/2009/July/ZK 5.0 and jQuery

Author
Timothy Clare, Technology Evangelist, Potix Corporation

Date
July 9, 2009

Version
ZK 5.0 preview release

Introduction

ZK5 now uses jQuery client side opening up a wide range of possibilities. One of the biggest benefit to use jQuery is that there are a lot of excellent plug-ins, in this Small Talk we will demonstrate the implementation of a client side effect using the jQuery plug-in jQuery Tools which provides a collection of the most important user-interface components for today's websites.

This article is part 1 of a two part series, the second part is located here.

The application’s premise

The premise of the application is to highlight a login area when the user interacts with it. We have a window containing two textboxes which will be highlighted while the background will be masked.

Demo

Including the client side javascript

Including jQuery tools

To get started we need to include the plug-in jQuery tools within the page, this is accomplished by ZK’s script component, shown below.

<?script src="/scripts/tools.expose-1.0.3.js" ?>

We then use the expose method provided by jQuery tools to highlight the Window.

Creating a function to highlight a component

To implement the client side effect we need to create a method which takes a widget as a parameter. The expose functionality is then applied to the widget resulting in highlighting of the given widget.

There are a couple points which need to be noted, firstly, the onLoad event retrieves the inner window which contains the content (in this case the textboxes and labels) to prevent the coloring effect from interfering with the title. Secondly, the onClose event is used to reset the background to the originally defined color. This color must be specified by us or retrieved from elsewhere.

The javascript function to accomplish this task is defined below.

Please remember to house this within <script> tags in your ZUL file.

function exposeLogin (widget) {		
	jq(widget).expose({

		// when exposing is done, change form's background color 
		onLoad: function() { 
			jq(widget.$n('cave')).css({backgroundColor: '#c7f8ff'});		
		}, 
			 
		// when "unexposed", return to original background color 
		onClose: function() { 
			jq(widget.$n('cave')).css({backgroundColor: ""});
		}, 
			 
		api: true

	}).load();
}

Implementing the ZK controls

Using a client side namespace

It is necessary when implementing client side functionality to declare a namespace. By declaring a client side namespace, these events will be resolved at the client rather than server side. Without this namespace applied to your events ZK will think that your code is Java and should be executed at the server.

Defining a namespace

Defining a namespace is easy, you add the following as an attribute to any ZK tag you want to.

xmlns:w=http://www.zkoss.org/2005/zk/client

In the case of our example, this is added to the ZK tag so the namespace is available to all components.

<zk xmlns:w="http://www.zkoss.org/2005/zk/client">

Defining a client side event

The easiest way to define a client side event is to utilize the namespace and utilize attribute tags to encase the javascript code. The following is an extract from our example, please notice that name=”onClick” is prefixed with the declared namespace in the form [NAMESPACE]:name=”[EVENT]”.

<attribute w:name="onClick">
	//javascript code goes here
</attribute>

Applying the effect to the window

In the example the window contains a client side event named onClick (similar to the above code). Within this event the exposeLogin function is called passing “this” as the argument. In this case the argument “this” will reference the window.

Source code

For the complete example please download the source code below.

Download here!

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