Three Steps to Use Macro Components"
m (correct highlight (via JWB)) |
|||
| Line 18: | Line 18: | ||
All you need to do is to prepare a ZUML page that describes what the component consists of. In other words, the page is a template of the macro. | All you need to do is to prepare a ZUML page that describes what the component consists of. In other words, the page is a template of the macro. | ||
| − | For example, assume we want to pack a label and a text box as a macro component. Then we could create page, say < | + | For example, assume we want to pack a label and a text box as a macro component. Then we could create page, say <code>/WEB-INF/macros/username.zul</code>, as follows. |
<source lang="xml" > | <source lang="xml" > | ||
| Line 37: | Line 37: | ||
</source> | </source> | ||
| − | As shown, you have to declare the name (the < | + | As shown, you have to declare the name (the <code>name</code> attribute) and the URI of the page (the <code>macroURI</code> attribute). |
==== Other Properties ==== | ==== Other Properties ==== | ||
| − | In additions to the < | + | In additions to the <code>name</code>, <code>macroURI</code> and <code>class</code><ref>The class attribute will be discussed later.</ref> attributes, you can specify a list of initial properties that will be used to initialize a component when it is instantiated. |
<source lang="xml" > | <source lang="xml" > | ||
| Line 80: | Line 80: | ||
</source> | </source> | ||
| − | All these properties specified are stored in a map that is then passed to the template via a variable called < | + | All these properties specified are stored in a map that is then passed to the template via a variable called <code>arg</code>. Then, in the template, you could access these properties as follows. |
<source lang="xml" > | <source lang="xml" > | ||
| Line 88: | Line 88: | ||
</source> | </source> | ||
| − | '''Note''': < | + | '''Note''': <code>arg</code> is available only when rendering the macro page. To access in the event listener, you have to use <code>getDynamicProperty</code> instead. Refer to the '''Provide Additional Methods''' section for more details. |
==== arg.includer ==== | ==== arg.includer ==== | ||
| − | In additions to the specified properties (a.k.a., attributes), a property called < | + | In additions to the specified properties (a.k.a., attributes), a property called <code>arg.includer</code> is always passed to represent the parent of the components defined in a macro template. |
| − | If a regular macro is created, < | + | If a regular macro is created, <code>arg.includer</code> is the macro component itself. If an inline macro is created, <code>arg.includer</code> is the parent component, if any. Refer to the '''Inline Macros''' section for more information. |
| − | In the above example, < | + | In the above example, <code>arg.includer</code> represents the regular macro component, <code><username who="John"/></code>, and is the parent of <code><hbox></code> (defined in <code>username.zul</code>). |
{{ ZKDevelopersGuidePageFooter}} | {{ ZKDevelopersGuidePageFooter}} | ||
Latest revision as of 10:40, 19 January 2022
This documentation is for an older version of ZK. For the latest one, please click here.
This documentation is for an older version of ZK. For the latest one, please click here.
It takes three steps to use macro components as follows.
- Implements a macro component by a ZUML page.
- Declare the macro component in the page that is going to use it.
- Use the macro components, which is no difference that other components.
Tip: In addition to define a macro component in page, you can put its definition into a language addon such all pages are able to access the macro component.
Step 1. The Implementation
All you need to do is to prepare a ZUML page that describes what the component consists of. In other words, the page is a template of the macro.
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!
The ZUML page implementing a macro component is the same as any other pages, so any ZUML page can be used as a macro component.
Step 2. The Declaration
Before instantiating a macro component, you have to declare first. One of simplest way to declare is to use the component directives.
<?component name="username" macroURI="/WEB-INF/macros/username.zul"?>
As shown, you have to declare the name (the name attribute) and the URI of the page (the macroURI attribute).
Other Properties
In additions to the name, macroURI and class[1] attributes, 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"/>
- ↑ The class attribute will be discussed later.
Step 3. The Use
The use of a macro component is no different than others.
<window>
<username/>
</window>
Pass Properties
Like an ordinary component, you can specify properties (a.k.a., attributes) when using a macro component as follows.
<?component name="username" macroURI="/WEB-INF/macros/username.zul"?>
<window>
<username who="John"/>
</window>
All these properties specified are stored in a map that is then passed to the template via a variable called arg. Then, in the template, you could access these properties as follows.
<hbox>
Username: <textbox value="${arg.who}"/>
</hbox>
Note: arg is available only when rendering the macro page. To access in the event listener, you have to use getDynamicProperty instead. Refer to the Provide Additional Methods section for more details.
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).