ZK Developer's Reference/UI Composing/Macro Component

There are two ways to implement a component. One is to implement a component in a Java class, extending from other component or one of skeletal implementations, with an optional JavaScript class. It is flexible and, technically, able to implement any functionality you wants. For more information please refer to ZK Component Development Essentials.

On the other hand, we could implement a new component by using the others and composing them in a ZUML page. In other words, we could define a new component by expressing it in a ZUML page. It works like composition, macro expansion, or inline replacement.

For sake of convenience, we call the first type of components as primitive components, while the second type as macro components. In this section we will discuss the details about how to implement a macro component and how to use it.

There is a similar concept called composite components. It is more a way to utilize ZK rather than a feature. For more information please refer to the Composite Component section.

Definition, Declaration and Use

It is straightforward to apply macro components to an application:

1. Define (aka., Implement) a macro component in a ZUML page.
2. Declare the macro component in the page or the whole application that is going to use the macro component.
3. Use the macro components. The use of a macro component is the same of using primitive components. There is no difference at all.

Define Macro Component

The definition of a macro component is expressed in a ZUML page. In other words, the page is the template of the macro component. It is the same as any other ZUML pages; no special syntax at all. Furthermore, any ZUML page can be used as a macro component too.

For example, assume we want to pack a label and a text box as a macro component. Then we could create page, say /WEB-INF/macros/username.zul, as follows.

<hbox>
	Username: <textbox/>
</hbox>

It is done.

Declare Macro Component

Before using a macro component, you have to declare it first. It is straightforward by use of the component directives. For example, we could add the first line to the page that is going to use the username macro component:

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

As shown, we have to declare the component's name (the name attribute) and the URI of the page defining the macro component (the macroURI attribute).

If you prefer to make a macro component available to all pages, you could add the component definition to the so-called language addon and add it to WEB-INF/zk.xml.

Use Macro Component

Using a macro component in a ZUML page is the same as the use of any other components.

<window>
	<username/>
</window>

Version History

Last Update : 2010/11/8

Version	Date	Content