The Component Development Guide

The skeletal implementation of AbstractComponent introduces the concept of molds. A mold is a view of a component. For example, tabbox supports the default and accordion molds to provide different views for the same component.

<tabbox mold="default">
</tabbox>
<tabbox mold="accordion">
</tabbox>

To minimize the development effect, it is recommended to extend from AbstractComponent or one of its deriving classes. With AbstractComponent, you don't implement the redraw method directly. Rather, you can use your favorite Servlet technologies to generate the view, such as DSP^[5] and JSP.

For Ajax browser, the visual presentation is implemented with a collection of HTML tags. For example, assume you want to use the HTML's BUTTON tag to represent a component, and then the visual presentation might look as follows.

<BUTTON id="z_ed_0" z.type="mycomps.MyButton">I am a button</BUTTON>

where z_ed_0 is the component's UUID (which is assigned by ZK Loader), and z.type is a special attribute used to indicate the type of the component.

The visual presentation are running at and interpreted by the browser. However, they are generated at the server, when the redraw method is called. Everything written to the writer argument passed to the redraw method will be sent to the client.

Instead of implementing redraw, you can extend from AbstractComponent and provide a or its deriving classes), and not to implement redraw directly. Rather, implement the so-called mold with your favorite Servlet technology, such as DSP, JSP, and so on. For convenience of description, we will use DSP mostly in this guide.

In addition to Java Servlet technologies, you can implement it with a so-called component renderer (org.zkoss.zk.ui.util.ComponentRenderer) instead. It is a bit harder to read but with better performance. We will talk more about it later.

Except implementing a very simple component, you usually need to provide some JavaScript codes to interact with the user, to manipulate HTML tags, and to communicate with the server. The JavaScript codes depending on their purpose can be grouped into separate methods. For example, assume you want to register an event listener when the component is initialized at the browser, and then the JavaScript codes might look as follows.

zkMyButton.init = function (cmp) {
    zk.listen(cmp, "click", function (evt) {/*my listener*/});    
};

where the method name is determined by the component type and when to call. In this example, the button's z.type is mycomps.MyButton (specified in the z.type attribute as described above). It means the JavaScript codes are located in a JavaScript file called, /web/js/mycomps.js. (and it must be locatable by the class loader), and the component type is MyButton.

Since we want it to run during initialization, the method name shall be zkMyButton.init (= "zk" + "Type" + ".when"). Similarly, If you want a method to be called when the browser is resized, the method name will be zkMyButton.onSize. We will talk more about it later.

AbstractComponent provides three kinds of methods to communicate with the client: invalidates, smart updates and AU responses. Invalidates notify ZK that a component needs to be redrawn completely. Smart updates notify ZK that a property of a component has been changed. AU responses allows a handle to ask the view to do anything it wants, such as change focus, start a timer, execute a piece of JavaScript codes and so on.

public class MyComp extends org.zkoss.zk.ui.AbstractComponent {
    private String _label = "";    
    public String getLabel() {    
        return _label;        
    }    
    public void setLabel(String label) {    
        if (!label.equals(_label)) {        
            _label = label;            
            smartUpdate("label", _label);            
        }        
    }    
    public void updateContent(Object value) {    
        //whatever...        
        invalidate();        
    }    
}

The communication between the view and the handle is one of the most important topic. We will discuss it later more detailedly.

To encapsulate API that are used only for component development, we introduce a concept called extra controls (aka., extra interfaces). If a component needs to provide some extra interfaces that will be used only for component development, it can override the newExtraCtrl method to instantiate an instance carrying the extra interfaces. For example, Slider allows the client to change the position of the slider, and then it has to implements the org.zkoss.zk.ui.ext.client.Scrollable interface. As depicted below, Slider first implements the ExtraCtrl class to implement the Scrollable interface. Then, Slider overrides newExtraCtrl to instantiate an ExtraCtrl instance.

public class Slider extends org.zkoss.zk.ui.HtmlBasedComponent {
    private int _curpos;    
protected Object newExtraCtrl() {
return new ExtraCtrl();
}
protected class ExtraCtrl extends HtmlBasedComponent.ExtraCtrl
implements Scrollable {
            public final void setCurposByClient(int curpos) {            
            _curpos = curpos;            
        }        
    }    
}

Notice that you generally have to extend from base class's extra controls, such that it inherits all extra controls. In the above case, it extends from the HtmlBasedComponent.ExtraCtrl class.

public void invalidate();

When the invalidate method is called, the component is marked as dirty, and then the redraw method will be called to generate the whole view to client in the Rendering phase.

The typical use is to call invalidate(), when the invocation of a method changes the view.

public void setLabel(String label) {
    if (!Objects8org.zkoss.lang.Objects.equals() compares if two objects equal (even both null)..equals(_label, label)) {    
        _label = label;        
        invalidate();        
    }    
}

It is the simplest way to update the view since we don't need to write any JavaScript codes. The view is updated with the redrawn view automatically by ZK. However, if the component contains a lot of child components (such as a grid), it is costly to redraw the whole view (since it has to also redraw all child components). Thus, if the change is mirror, the performance will be better if you use smart updates or AU responses.

Note: ZK optimizes the invalidates before invoking the redraw method. For example, a component will be redrawn at most one time, even if it is invalidated multiple times, or its parent is invalidated, too.

public void smartUpdate(String attrName, String value);public void smartUpdate(String attrName, DeferredValue value);public void smartUpdate(String attrName, boolean value);public void smartUpdate(String attrName, int value);

A smart update is used to modify an attribute of the view. Unlike an invalidate, it won't cause the component to be redrawn.

public void setReadonly(boolean readonly) {
    if (_readonly != readonly) {    
_readonly = readonly;
        smartUpdate("readOnly", _readonly);        
    }    
}

By default, ZK Client Engine will update the attribute of the most outer DOM element (of the view) with the specified name. For example, assume the most outer DOM element of the above example is elem, it is equivalent to invoke the following JavaScript codes at the client:

elem.readOnly = _readonly;

ZK Client Engine is smart enough to invoke the correct method for updating a field. For example, elem.className for the class attribute, elem.setAttribute() for unrecognized attributes, and so on.

In additions, you can provide your own JavaScript codes to handle smart updates at the client, if you want to handle smart updates in a component-specific way.

Note: if both smart updates and invalidates are called against the same component, the smart updates will be ignored – after all, the whole view will be redrawn.

public void response(String key, AuResponse^[8] response);

An AU response is the lowest-level response. You can fully customize it to do whatever you want.

However, you rarely need to use AU responses directly, since invalidates and smart updates can do almost everything you want. Remember you can provide your custom JavaScript codes to handle smart updates at the client. In other words, you can use smart updates to execute something at the client; not just modify an attribute.

Unlike smart updates, an AU responses are always sent to the client even if an invalidate is called against the same component. It is one of the reason we have to use AU responses for certain circumstances.

For example, let us say we want to implement the focus feature. Since we want to change the focus to a component even if it is invalidated, an AU response is the only choice.

    public void focus() {response("focus", new AuFocus(this));}    

where AuFocus is one of built-in AU responses extending from AuResponse with predefined functionality.

public void play() {
    response("play", new AuScript(this, "alert('Hi')"));    
}

A command (org.zkoss.zk.au.Command) is used to process certain type of AU requests. When ZK Update Engine receives an AU request, it associates a command with it. Then, it invokes the process method of the command to process it. The processing, depending on the requirement, usually updates the content of the component and then posts an event to notify the application.

For example, the org.zkoss.zk.au.in.RemoveCommand command is registered to process all AU requests called remove. Thus, if an AU request called remove is received, the process method of RemoveCommand will be invoked. Here is how RemoveCommand is implemented:

public class RemoveCommand extends Command {
    public RemoveCommand(String evtnm, int flags) {    
        super(evtnm, flags);        
    }    
    protected void process(AuRequest request) {    
        final Component comp = request.getComponent();        
        if (comp != null) comp.detach();        
    }    
}

Note: ZK uses the same command instance for the same type of AU requests, so concurrent access of the command is possible.

See Also: Refer to the Process Request at the Server section in the next chapter for more details.

When a command processing a request, it might post one or several events. For example, InputCommand will post the onChange event as an instance of org.zkoss.zk.ui.event.InputEvent. The events are queued until all commands are processed. In other words, the events are processed by the application, after the components have been updated.

There is a common question for developing a component: shall I update the component's state in a command or in an event listener. In general, it is better to use event to notify the application only. And, it is better to update the component's state in a command. After all, the application might stop the event propagation at any time (Event.stopPropagation).

On the other hand, we can utilize the stop-propagation feature to allow the application to customize some behavior. For example, the list box sorts the list items in the onSort listener, such that the application can provide its own sorting by adding its own listener and stop the event propagation.

zkType.init = function (cmp) {
};

Called when a component is attached to a page or redrawn (due to being invalidated).

The order of invocations is the child first (like Java constructor). The child without a parent is called first, then its child, then its grandchild, and so on.

zkType.cleanup = function (cmp) {
};

Called when a component is detached, or will be redrawn (due to being invalidated).

When the invalidate method is called at the server, ZK Client Engine will first call the cleanup callback, replace the DOM tree, and then call the init callback.

The order of invocations is the parent first. The topmost parent being cleanup is called first, then its child, then its grandchild, and so on.

zkType.beforeSize = function (cmp) {
};
zkType.onSize = function (cmp) {
};

When the browser window or a resizable parent (such as Borderlayout) is resized, ZK Client Engine first call the beforeSize callback for all components that are affected, and then call the onSize callback for them. In other words, it is a two-pass mechanism. The beforSize callback is used to do some preparation. For example, you might have to reset style.width in the beforeSize callback and then set the correct size in the onSize callback.

The order of invocations is the parent first. The topmost parent that is affected is called first, then its child, then its grandchild, and so on.

Notes

zkType.onVisi = function (cmp) {
};

Called right after a component has become visible.

The order of invocations is the parent first. The topmost parent becoming visible is called first, then its child, then its grandchild, and so on.

Note

zkType.onHide = function (cmp) {
};

Called right before a component becomes invisible. Notice that when this method is called, the component is still visible.

The order of invocations is the parent first. The topmost parent becoming invisible is called first, then its child, then its grandchild, and so on.

zkType.onScroll = function (cmp) {
};

Called when the user is scrolling the browser window or one of its ancestor component.

The order of invocations is the parent first. The topmost parent affected by scrolling is called first, then its child, then its grandchild, and so on.

Notes

The following is a list of the properties that an AU request might have.

zkau.sendasap and zkau.send are two of most common methods to send an AU request to the server.

zkau.send({uuid: cmp.id, cmd: "onChange", data: [cmp.value]},
zkau.asapTimeout(cmp, "onChange"));

zkau.send(evt, zkau.asapTimeout(evt.uuid, evt.cmd, timeout));

There are two callbacks you can register to do something before sending AU requests, and after receiving the responses.

zkau.addOnSend(function() {
//check any change and call zkau.sendAhead to carry the change back
});

Here is a list of methods to simply the sending of particular AU requests, such as onClose. They are all based on zkau.send.

There are two kinds of commands: global commands and component-specific commands. The global commands are available to all kind of components, while component-specific commands are available only to a particular kind of components. More precisely, global commands are maintained in a global map, while component-specific commands is maintained in an individual component.

If none of built-in command fulfills your requirement, you can develop your own command.

public class SuperButton extends AbstractComponent {
    private static Command _flycmd = new ComponentCommand("onFly", 0) {    
        protected void process(AuRequest request) {        
            final SuperButton btn = (SuperButton)request.getComponent();            
            btn.doFly();            
                    Events.postEvent(new Event(getId(), btn, request.getData()));}                    
    }; //note: it won't register itself to the global map    
        //because it is extended from ComponentCommand)        
    public Command getCommand(String cmdId) {    
        return "fly".equals(cmdId) ? _flycmd: null;        
    }    
    void doFly() {    
        //whatever        
    }    
}

class FlyCommand extends Command {
public FlyCommand(String id, int flags) {
super(id, flags);
}
protected process(AuRequest request) {
final SuperButton btn = (SuperButton)request.getComponent();
        btn.doFly();        
Events.postEvent(new Event(getId(), btn, request.getData()));
}
}

public class SuperButton extends AbstractComponent {
    static {    
            new FlyCommand("onFly", 0); //register itself automatically}            
...

public Object getExtraCtrl();

public interface Flyable {
public void doFly();
}

public class SuperButton extends AbstractComponent {
    public Object newExtraCtrl() {    
        return new ExtraCtrl();        
    }    
    private void doFly() { //make it inaccessible    
        //whatever        
    }    
    private class ExtraCtrl implements Flyable {    
public void doFly() {
SuperButto.this.doFly();
}
}
...

class FlyCommand extends Command {
public FlyCommand(String id, int flags) {
super(id, flags);
}
protected process(AuRequest request) {
final Component comp = request.getComponent();
        if (comp instanceof Flyable)        
((Flyable)comp).doFly();
Events.postEvent(new Event(getId(), comp, request.getData()));
}
}

When implementing a sophisticated component, you might want to pass multiple values (i.e., an array of values) to an attribute. At the server side, you invoke the smartUpdateValues method. At the client, the setAttr callback will be called with additional arguments. For example, at the server, you invoke

smartUpdateValues("fly", new String[] {"low", "fast"});

Then, at the client, you can handle it as follows.

zkSuperButton.setAttr = function (cmp, name, value1, value2) {
if ("fly" == name) {
fly(value1, value2);
...

JavaScript Tip: You can use arguments.length to determine how many arguments are passed.

The invoke response is used to invoke a callback. For example, you can send an AU response at the server as follows.

    public void fly() {response("ctrl", new AuInvoke(this, "fly", "low", "fast"));}    

Then, at the client, the following callback will be called.

    zkSuperButton.fly = function (cmp, height, speed) {//whatever    
}

Tip: As shown above, we can use a AU response and a smart update to do the similar task (fly in this example). But, there is a difference: the AU response is sent even if the component is invalidated, while the smart update won't.

Thus, if the init callback will handle everything, the smart update shall be used (otherwise, you will do it twice when it is invalidated).

The script response is used to execute any JavaScript codes at the client, not just the callbacks. For example,

public void fly() {
    response("ctrl",    
new AuScript(this, "zkSuperButton.fly('" + getUuid() + "','low','fast')"));
}

Since the JavaScript codes are hardcoded, it is sometimes not easy to support multiple molds. For example, assume you want to use the same Java class to implement another mold. Then, the JavaScript codes that implements fly might be different. So, you might have to do as follows.

public void fly() {
    response("ctrl",    
new AuScript(this,
("SuperButton".equals(getMold()) ? "zkSuperButton": "zkGiantButton")
+ ".fly('" + getUuid() + "','low','fast')"));
}

On the other hand, if you use the invoke response, you can have the same response but define a different component type, say GiantButton. Then, you don't modify Java class. Rather, provide another callback:

zkGiantButton.fly = function (cmp, height, speed) {
    //whatever    
}

In general, the invoke response is recommended if applicable.

Unlike the AU request's commands, you rarely need to develop your own AU response since the invoke response can serve almost everything. However, if you prefer to provide your own response, you can follow the instructions described in this section.

First, you have to implement a Java class extending from the org.zkoss.zk.au.AuResponse class.

public AuFly extends AuResponse {
    public AuFly(SuperButton comp, String height, String speed) {    
super("fly", comp, new String[] {comp.getUuid(), height, speed});
}
}

where "fly" is the response name, and the third argument (String[]) of AuResponse's constructor will be passed to the client. The response name must be unique. The third argument is called the response data.

Then, at the client side, you shall provide a method called zkau.cmd1.fly to handle it.

zkau.cmd1.fly = function (uuid, cmp, height, speed) {
//whatever
}

There are two set of response handlers: zkau.cmd0 and zkau.cmd1. zkau.cmd0 is used to handle responses that are applied to the whole browser window, while zkau.cmd1 is for individual component.

If zkau.cmd1 is overridden, the first element of the response data must be the component UUID (comp.getUuid() in the above example). Then, ZK Client Engine will convert it to a reference to a component, and then invoke the response's handler with UUID and the reference as the first two arguments (refer to zkau.cmd.fly in the above example).

If you pack the component definition(s) in a JAR file, the language addon must be named lang-addon.xml and placed at the /metainfo/zk directory accessible by the classpath.

If you pack the component definition(s) in a WAR file, you can specify the path of the XML file in /WEB-INF/zk.xml. For example, let us assume the path of the XML file is /WEB-INF/zk/lang-addon.xml, then specify the following in /WEB-INF/zk.xml. You can specify multiple language addons.

<language-config>
    <addon-uri>/WEB-INF/zk/lang-addon.xml</addon-uri>    
</language-config>

[Required]

<addon-name>name</addon-name>

Specifies the unique name of the language addon.

[Optional]

<depends>another1, another2</depends>

Specifies a list of the names of other addons, which this addon depends on. If specified, this addon won't be loaded until all depended addons are loaded. If not specified, the loading sequence is unpredictable.

[Required]

<language-name>xul/html</language-name>

Specified the language that this addon shall be added to.

[Optional^[16]]

<version>
    <version-class>org.zkforge.fckez.Version</version-class>    
    <version-uid>2.5.1_1</version-uid>    
    <zk-version>2.4.0</zk-version><!-- or later →    
</version>

There are two parts: addon version and ZK version. Addon version is specified in version-uid element. In certain environments, it is possible to have several versions of JAR file containing the same set of component definitions^[17]. To ensure the correct XML file is loaded, you have to specify a class carrying the version. The class must have a static data member called UID as shown below.

public class Version {
    public static final String UID = "2.5.1_1";    
}

Then, ZK will compare UID with the value specified in version-uid, and the addon is ignored if not matched – it means the XML file is not from the same JAR file being loaded.

ZK Version that this addon requires is specified in the zk-version element. The addon is ignored if ZK installed is an older version.

[Optional]

<javascript-module name="fckez.fckez" version="2.5.1_1"/>

Specifies the version of JavaScript codes that will run at the client. If specified, ZK will mangle the URL of JavaScript files with the version, such that the browsers won't use the wrong cached version. It is recommended to change the version each time you deliver a new version of your components (so JavaScript files with the most update version will be loaded by the browser).

<component>
    <component-name>fckeditor</component-name>    
    <component-class>org.zkforge.fckez.FCKeditor</component-class>    
    <mold>    
        <mold-name>default</mold-name>        
        <mold-uri>~./fckez/fckeditor.dsp</mold-uri>        
    </mold>    
</component>

<mold>
    <mold-name>default</mold-name>    
    <mold-uri>~./fckez/fckeditor.dsp</mold-uri>    
</mold>

<custom-attribute>
    <attribute-name>my.attr</attribute-name>    
    <attribute-value>my value</attribute-value>    
</custom-attribute>

<property>
    <property-name>border</property-name>    
    <property-value>blue</property-value>    
</property>

<annotation>
    <annotation-name></annotation-name>    
    <property-name></property-name>    
    <attribute>    
        <attribute-name></attribute-name>        
        <attribute-value></attribute-value>        
    </attribute>    
    <attribute>    
        <attribute-name></attribute-name>        
        <attribute-value></attribute-value>        
    </attribute>    
</annotation>

<component>
    <component-name>mycomp</component-name>    
    <component-class>com.mine.Mycomp</component-class>    
    <macro-uri>~./mine/mycomp.zul</macro-uri>    
</component>

The syntax of a macro definition is similar to the definition of the primitive component, except

<inline>true</inline>

<component>
    <component-name>funnybutton</component-name>    
    <extends>button</extends>    
</component>

In addition to define a new component, you can extend from the existent one. By extending, it inherits all properties such the as component class, molds and so on. You can override any element you want. The syntax is the same, but they are optional except the component-name and extends element.

[Required]

<language-name>xul/html</language-name>

Specified the language name that uniquely identifies this langauge.

[Required]

<<device-type>ajax</device-type>

Specified the device type, such as ajax, xml, mil and hil.

[Required]

<namespace>http://www.zkoss.org/2005/zul</namespace>

Specified the namespace that also uniquely identifies this language.

[Required; Multiple]

<extension>zul</extension>
<extension>xul</extension>

Specified the file extension that shall be considered as using this language. For example, if zul is specified, this language will be used as the default language for all files with the .zul extension. Of course, the file can change the language later with the page directive.

[Optional^[18]]

<version>
    <version-class>org.zkoss.zul.Version</version-class>    
    <version-uid>3.0.5</version-uid>    
    <zk-version>3.0.0</zk-version><!-- or later →    
</version>

There are two parts: language version and ZK version. Language version is specified in version-uid element. In certain environments, it is possible to have several versions of JAR file containing the same set of component definitions^[19]. To ensure the correct XML file is loaded, you have to specify a class carrying the version. The class must have a static data member called UID as shown below.

public class Version {
    public static final String UID = "3.0.5";    
}

Then, ZK will compare UID with the value specified in version-uid, and the language is ignored if not matched – it means the XML file is not from the same JAR file being loaded.

ZK Version that this language requires is specified in the zk-version element. The language is ignored if ZK installed is an older version.