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.

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. There is no difference at all

<window>
	<username/>
</window>

Pass Properties to Macro Component

Like an ordinary component, you can specify properties (a.k.a., attributes) when using a macro component. For example,

<?component name="username" macroURI="/WEB-INF/macros/username.zul"?>
<window>
	<username who="John" label="Username"/>
</window>

All these properties specified are stored in a map that is then passed to the template (aka., the macro definition; macroURI) via a variable called arg. Then, in the template, you could access these properties by use of EL expressions as shown below:

<hlayout>
	${arg.username}: <textbox value="${arg.who}"/>
</hlayout>

arg.includer

In additions to the specified properties (a.k.a., attributes), a property called arg.includer is always passed to represent the parent of the components defined in a macro template.

If a regular macro is created, arg.includer is the macro component itself. If an inline macro is created, arg.includer is the parent component, if any. Refer to the Inline Macros section for more information.

In the above example, arg.includer represents the regular macro component, <username who="John"/>, and is the parent of <hbox> (defined in username.zul).

Pass Initial Properties

you can specify a list of initial properties that will be used to initialize a component when it is instantiated.

<?component name="mycomp" macroURI="/macros/mycomp.zul"
   myprop="myval" another="anotherval"?>

Therefore,

<mycomp/>

is equivalent to

<mycomp myprop="myval1" another="anotherval"/>

Version History

Last Update : 2010/11/8

Version	Date	Content