Inline Macros"

From Documentation
m
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
 +
 +
There are two kinds of macro components: inline and regular. By default, regular macros are assumed. To specify inline macros, you have to specify <tt>inline="true"</tt> in the component directive.
 +
 +
An inline macro behaves like ''inline-expansion''. ZK doesn't create a macro component if an inline macro is encountered. Rather, it inline-expands the components defined in the macro URI. In other words, it works as if you type the content of the inline macro directly to the target page.
 +
 +
 +
use.zul: (target page)
 +
 +
<source lang="xml" >
 +
<?component name="username" inline="true" macroURI="username.zul"?>
 +
<grid>
 +
<rows>
 +
<username id="ua" name="John"/>
 +
</rows>
 +
</grid>
 +
</source>
 +
 +
username.zul: (macro definition)
 +
 +
<source lang="xml" >
 +
<row>
 +
Username
 +
<textbox id="${arg.id}" value="${arg.name}"/>
 +
</row>
 +
</source>
 +
 +
Equivalent page:
 +
 +
<source lang="xml" >
 +
<grid>
 +
<rows>
 +
<row>
 +
Username
 +
<textbox id="ua" value="John"/>
 +
</row>
 +
</rows>
 +
</grid>
 +
</source>
 +
 +
All properties, including <tt>id</tt>, are passed to the inline macro.
 +
 +
On the other hand, ZK will create a real component (called a macro component) 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 <tt>rows</tt> accepts only <tt>row</tt>, 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 ===
 +
<tt>inline.zul</tt>: (the macro definition)
 +
 +
<source lang="xml" >
 +
<row>
 +
<textbox value="${arg.col1}"/>
 +
<textbox value="${arg.col2}"/>
 +
</row>
 +
</source>
 +
 +
<tt>useinline.zul</tt>: (the target page)
 +
 +
<source lang="xml" >
 +
<?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>
 +
</source>
  
 
=Version History=
 
=Version History=

Revision as of 08:02, 8 November 2010


DocumentationZK Developer's ReferenceUI ComposingMacro ComponentInline Macros
Inline Macros


There are two kinds of macro components: inline and regular. By default, regular macros are assumed. To specify inline macros, you have to specify inline="true" in the component directive.

An inline macro behaves like inline-expansion. ZK doesn't create a macro component if an inline macro is encountered. Rather, it inline-expands the components defined in the macro URI. In other words, it works as if you type the content of the inline macro directly to the target page.


use.zul: (target page) 

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

username.zul: (macro definition) 

<row>
	Username
	<textbox id="${arg.id}" value="${arg.name}"/>
</row>

Equivalent page: 

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

All properties, including id, are passed to the inline macro.

On the other hand, ZK will create a real component (called a macro component) 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
     



Last Update : 2010/11/08

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


Retrieved from "https://www.zkoss.org/_w/index.php?title=ZK_Developer%27s_Reference/UI_Composing/Macro_Component/Inline_Macros&oldid=9700"