ZK Developer's Reference/UI Composing/Macro Component/Inline Macros

An inline macro is a special macro component that behaves like inline-expansion. Unlike a regular macro component, ZK doesn't create a macro component. Rather, it inline-expands the components defined in the macro URI, as if the content of the in-line macro's template is entered directly in the target page.

Declare Inline Macro

To declare an inline macro, we have to specify inline="true" in the component directive, while the definition and the use of an inline macro is the same as the regular macro components (i.e., non-inline).

For example, suppose we have a macro definition (aka., template) as follows:

<!-- username.zul: (macro definition) -->
<row>
	Username
	<textbox id="${arg.id}" value="${arg.name}"/>
</row>

We can declare it as an line macro as follows:

<!-- target page -->
<?component name="username" inline="true" macroURI="username.zul"?>
<grid>
	<rows>
		<username id="ua" name="John"/>
	</rows>
</grid>

Then, it is equivalent to:

<grid>
	<rows>
		<row>
			Username
			<textbox id="ua" value="John"/>
		</row>
	</rows>
</grid>

Notice that all properties, including id, are passed to the inline macro too.

Regular Macro

On the other hand, ZK will create a real component (an instance of HtmlMacroComponent) to represent the regular macro. That is, the macro component is created as the parent of the components that are defined in the macro.

Inline macros are easier to integrate into sophisticated pages. For example, you cannot use regular components in the previous example since rows accepts only row, not macro components. It is easier to access to all components defined in a macro since they are in the same ID space. It also means the developers must be aware of the implementation to avoid name conflicts.

Regular macros allow the component developers to provide additional API and hide the implementation from the component users. Each regular macro component is an ID space owner, so there is no name conflicts. The users of regular macros usually assume nothing about the implementation. Rather, they access via the well-defined API.

An Example

inline.zul: (the macro definition)

<row>
	<textbox value="${arg.col1}"/>
	<textbox value="${arg.col2}"/>
</row>

useinline.zul: (the target page)

<?component    name="myrow"    macroURI="inline.zul"  inline="true"?>
<window    title="Test of inline macros"    border="normal">
	<zscript><![CDATA[
		import    org.zkoss.util.Pair;
		List  infos = new LinkedList();
		for(int j     = 0;j    <10;++j){
			infos.add(new Pair("A" + j, "B" +j));
		}
	]]>
	</zscript>
	<grid>
		<rows>
			<myrow    col1="${each.x}"    col2="${each.y}"    forEach="${infos}"/>
		</rows>
	</grid>
</window>

Version History

Last Update : 2010/11/8

Version	Date	Content