Introduction

When we create an application such as an image manager for a blog we would always provide the user with an easy way to select images and move them from one category to another. We could use components such as checkboxes or radio components for the selection, but that doesn’t provide a very user friendly experience.
In this small talk, I will introduce this new component for ZK 5.
This component is a container in which you can place images. It is then possible to select images by clicking or dragging your mouse just as you would in Windows Explorer. This provides better user functionality and makes it much easier to select the items the user desires.

Live Demo

Let's have a look at the demo of the ZK Imagepicker.

The following code fragment demonstrates how to use the Imagepicker component

Behind The Scene: How to Implement a ZK5 component

A component class in Java

The component class must extend from AbstractComponent or one of its derived class. There are several skeletal implementations available and you can choose the appropriate one for your usage. For this component, we will use the XulElement,

You can create a java class extends XulElement, then provide getter and setter methods for all attributes. The setter methods must be updated using smartUpdate.

Why renderProperties and smartUpdate?

A common question is why renderProperties (and redraw) are required to render value again when we notify the client with smartUpdate in setValue?

The simple answer is renderProperties is used to send all properties at once when a component is attached to the page at the first time. On the other hand, smartUpdate is used to send a property that was modified after the initial attachment.

A widget class in JavaScript

You can create javascript which extends zul.Widget, then define a setter and getter of all attributes by $define.

The $define function is a util function to declare set/get/is functions automatically

All attributes within the $define function will have set/get/is functions created automatically for them by zk.js

The function within $define will call syncAttr() to realign all images when some images have their values set.

The four class attributes will also call the same method (syncAttr()) after an attribute has a new value set.

You can then override the doClick_, doMouseOver_, and doMouseOut_ functions, to change the CSS of the target (div) when an event is triggered,

doClick_ , doMouseOver_ , doMouseOut_: you can receive the clicked target by event.Target, or domTarget by event.domTarget, and change target’s css, then the function must be call this.$supers('doClick_', arguments) at last, doMouseOver_ and doMouseOut_ are the same with pervious one.

After this we create a div as a selector, and monitor all edges of the selector, check the position of all items. If the edge of the selector touches any items, those items will be selected. We use this.fire(‘onSelect’) to notify the server side when an image is selected.

A JavaScript method to generate the DOM content (so-called mold)

The DOM content of a widget is called a mold. A widget can have several molds and each mold should be placed in an independent JavaScript file.

This component is created by div tags. We use div tags to define the container area, then enclose all children because we want the div to “frame” each image, and every div will change color (modify css) when some specific event is triggered.

The debug-js attribute specifies whether to turn on the debugging of JavaScript files. By default, it is false and the compressed version of JavaScript files will be loaded which are hard to read and debug, though the footprint is much smaller.

To debug JavaScript files, you can set the attribute to true and the original uncompressed JavaScript files will be loaded instead.

org.zkoss.web.classWebResource.cache:

ZK, by default, allows the browser to cache static resources like images and JavaScript files. When you are developing a component, it is better to turn it off.

Download

Summary

The Imagepicker is an image container, creating a transparent frame for image selection. The component not only provides a click action for selecting images but a lasso effect similar to Windows Explorer, making it easy to use.

ZK 5 component operations can be split between the server-side and/or the client-side. The java class handles the server-side’s component tree and the javascript widget class handles the widget tree of client side. The widget tree will be create a dom tree in the browser and the component tree updates the widget tree by calling the methods renderProperties() or smartUpdate().