Formerly in ZK 8 Philosophy, we focused on the main idea of dealing with front-end technologies. Regarding this concept, we are pleased to introduce a simple but powerful way of working with front-end technologies – the Data-handler API. Through this method, developers can easily define their own data-handler, and use client attribute as additional DOM attributes for creating extra functionalities.

By using Data-handler API, any ZK Components working with Javascript libraries can become modularized and reusable. Developers no longer have to wait for the ZK Team to release a new component, as by combining data-handler with Client-binding, they will be able to incorporate any 3rd party Javascript library efficiently themselves. This ultimate flexibility makes it extremely easy to leverage the evolving front-end technology.

Version: 8.0.0.FL.20150827 and later


In this demo, we created 11 data-handler samples in different categories.
These samples use different Javascript libraries, such as dhtmlx and Kendo, to work with ZK components like Label, Textbox, Selectbox, and Div.


By implementing the Data-handler API, developers will be able to freely integrate 3rd party Javascript libraries with ZK components. For many, the knowledge required to build a component from scratch may be too complex. Hence, in zk.xml, we have created the setting client-config, which simplifies the process considerably, especially since developers are able to directly apply data-handler or package it into an add-on.

Every sample in the following demo contains three parts.

First, we choose a Javascript library and download it.
Afterwards, we set the config file (zk.xml) in our application.

For example, (data-dhtmlxscheduler)

    <link href="~./css/dhtmlxscheduler.css" rel="stylesheet" />
    <script src="~./js/lib/dhtmlxscheduler.js" />
    <script src="~./js/data-dhtmlxscheduler.js" />

The name we define in line 3 would correspond with a client attribute “data-dhtmlxscheduler” in ZK component, and the next two lines represent the Javascript library files we want to import.
Moreover, the last <script> tag indicates the data-handler script, which is the third part we need to implement.
To create a great combination between JS library and ZK component, there are a few things we need to consider in the data-handler script.
First, we have to initialize the JS library. It’s easy to find a solution on the library’s website.
Next, we can handle the transfer of data between client and server (optional).

Example 1: data-markdown

function (wgt, dataValue) {
  var converter = new showdown.Converter();
  //Initial markdown conversion
  wgt.$n().innerHTML = converter.makeHtml(wgt.getValue());
  //Do markdown conversion after value of the wgt has been set
  wgt.setOverride("setValue", function(value) {
    this.$n().innerHTML = converter.makeHtml(value);

In this example, we override the “setValue” function in ZK widget. Once the value has been changed,
the markdown converter would turn the markdown value into HTML.

Example 2: data-dhtmlxscheduler

function (wgt, dataValue) {
  //Code to init scheduler...
  var self = this;
  if (self.command) {
    scheduler.attachEvent("onEventAdded", function(id, ev){
      self.command("$addServerEvent", {id: ...});
    //other events to server...
//MVVM only
  if (self.after) {
    self.after('$addClientEvent', function (evt) {
      if (evt != null) {
        for (var i = 0 ; i < evt.length; i++) {
    //other events from server...

In this demo, after initializing dhtmlxscheduler, we can use client binding to handle the communication between client and server. The dhtmlxscheduler library provides some events, such as “onEventAdded”, and we can use the method “command” to send the data back.
Also, we can use the “after” method as a listener to detect the changes from server.

Notice that the first parameter (command name) in the two methods would be expanded by adding a prefix “dhtmlxscheduler-” automatically.


After setting the zk.xml and data-handler script, we can use it in zul file: (data-markdown)

<label xmlns:ca="client/attribute" ca:data-markdown="true" />

If the data-handler has defined the “command” and “after” function, we can use a view model to deal with the transfer of data.

@NotifyCommand(value = "dhtmlxscheduler$addClientEvent", 
  onChange = "_vm_.addEventList")
public class DhtmlxSchedulerVM {

The annotations of class would build the connection between server and client. (Client binding API.)
@ToServerCommand: Trigger command in server by client.
@ToClientCommand: Trigger the aftercommand in client.
@NotifyCommand: Trigger a command in viewmodel whenever the given expression changes at the server.

Click here to see more details about this sample.

To see more samples, please refer to here.


The complete implementation of this demo can be found on GitHub.

Those data-handler samples are under Apache 2.0 License. Contributions are welcome! Show your creativity and share it with our ever-advancing Java community via Github.

If you enjoyed this post, please consider leaving a comment or subscribing to the RSS feed to have future articles delivered to your feed reader.

One Response to “ZK8: Simple but Powerful; Using Data-handler API to Work with Front-End Technologies”

  1. […] ZK8: Simple but Powerful; Using Data-handler API to Work with Front-End Technologies […]

Leave a Reply