Implement Custom Java Class

From Documentation


Implement Custom Java Class


As described in the earlier sections, a macro component is instantiated to represent a regular macro. By default, HtmlMacroComponent is assumed (and instantiated). However, you provide a custom Java class to provide a better API to simplify the access and to encapsulate the implementation.

Implement Custom Java Class for Macro

The implementation is straightforward. First, the custom Java class for macro components must extend from HtmlMacroComponent. Second, it shall invoke HtmlMacroComponent.compose() in the constructor[1], such that the template will be applied in the constructor.

For example, suppose we have a macro template as follows.

<hlayout>
	Username: <textbox id="who"/>
</hlayout>

Then, we could implement a Java class for it:

package foo;

import org.zkoss.zk.ui.HtmlMacroComponent;
import org.zkoss.zul.Textbox;

public class Username extends HtmlMacroComponent {
    private Textbox who; //will be wired when compose() is called
    public Username() {
        compose(); //fore the template to be applied
    }
    public String getWho() {
        return this.who.getValue();
    }
    public void setWho(String who) {
        this.who.setValue(who);
    }
    //public void onOK() {..} //you could add event listeners too
}

Notice that HtmlMacroComponent.compose() will wire fellows and event listener automatically, so we could access them directly (such as the who member).

Also notice that the arg variable is still available to the template to represent properties set by DynamicPropertied.setDynamicProperty(String, Object). However, it is pointless to use it if we provide all required setters.


  1. HtmlMacroComponent.compose() is available in 5.0.5. For 5.0.4 or earlier, please invoke HtmlMacroComponent.afterCompose() instead.

Declare Macro with Custom Java Class

To make ZK Loader to know which custom Java class to use, we have to specify the class attribute. For example,

<?component name="username" macroURI="/WEB-INF/macros/username.zul"
   class="foo.Username"?>

Use Macro with Custom Java Class

In ZUML

The use of the macro component with a custom Java class in a ZUML page is the same as other macro components.

In Java

The main purpose of introducing a custom Java class is to simplify the use of a macro component in Java. For example, you could invoke a more meaningful setter, say, setWho, directly rather than DynamicPropertied.setDynamicProperty(String, Object). In additions, the instantiation could be as simple as follows:

Username ua = new Username();
ua.setParent(wnd);
ua.setWho("Joe");

Version History

Last Update : 2010/11/8

Version Date Content
5.0.5 October, 2010 HtmlMacroComponent.compose() was introduced.



Last Update : 2010/11/08

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