Inline Macros"

From Documentation
m
m (remove empty version history (via JWB))
 
(21 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
  
=Version History=
+
__TOC__
Last Update : {{REVISIONYEAR}}/{{REVISIONMONTH}}/{{REVISIONDAY}}
+
 
{| border='1px' | width="100%"
+
=Overview=
! Version !! Date !! Content
+
An inline macro is a special macro component which behaves like ''inline-expansion''. Unlike a regular macro component, ZK does not 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 into the target page.
|-
+
 
|  
+
= Declare an Inline Macro =
|  
+
 
|  
+
To declare an inline macro, we have to specify <code>inline="true"</code> in the component directive, while the definition and the use of an inline macro are the same as the regular macro components (i.e., non-inline).
|}
+
 
 +
For example, suppose we have a macro definition (aka., template) as follows:
 +
 
 +
<source lang="xml" >
 +
<!-- username.zul: (macro definition) -->
 +
<row>
 +
Username
 +
<textbox id="${arg.id}" value="${arg.name}"/>
 +
</row>
 +
</source>
 +
 
 +
 
 +
We can declare it as an inline macro as follows:
 +
 
 +
<source lang="xml" >
 +
<!-- target page -->
 +
<?component name="username" inline="true" macroURI="username.zul"?>
 +
<grid>
 +
<rows>
 +
<username id="ua" name="John"/>
 +
</rows>
 +
</grid>
 +
</source>
 +
 
 +
 
 +
Then, it is equivalent to:
 +
 
 +
<source lang="xml" >
 +
<grid>
 +
<rows>
 +
<row>
 +
Username
 +
<textbox id="ua" value="John"/>
 +
</row>
 +
</rows>
 +
</grid>
 +
</source>
 +
 
 +
Notice that all the properties, including <code>id</code>, are passed to the inline macro too.
 +
 
 +
= Inline versus Regular Macro =
 +
 
 +
As described above, an inline macro is expanded inline when it is used as if they are entered directly. On the other hand, ZK will create a component (an instance of <javadoc>org.zkoss.zk.ui.HtmlMacroComponent</javadoc> or deriving) to represent the regular macro. That is, the macro component is created as the parent of the components that are defined in the template.
 +
 
 +
Inline macros are easier to integrate into sophisticated pages. For example, you ''cannot'' use ''regular'' macro components in the previous example since <code>rows</code> accepts only <code>row</code> as children, not macro components. It is also easier to access all components defined in a macro since they are expanded inline. However, it also means that the developers must take care of <code>id</code> themselves. In addition, there is no way to instantiate inline macros in pure Java (rather, <javadoc method="createComponents(java.lang.String, org.zkoss.zk.ui.Component, java.util.Map)">org.zkoss.zk.ui.Execution</javadoc> shall be used)<ref>ZK Loader does create a component for an inline macro when rendering, and then drop it after ''expanding'' into the parent component. Technically, an application can do the same thing but it is not recommended since we might change it in the future.</ref>.
 +
 
 +
On the other hand, regular macros allow the component developers to provide a custom Java class to represent the component so a better abstraction and addition functionality can be implemented. We will discuss it more in the [[ZK Developer's Reference/UI Composing/Macro Component/Implement Custom Java Class|following section]].
 +
 
 +
<blockquote>
 +
----
 +
<references/>
 +
</blockquote>
 +
 
 +
== arg.includer ==
 +
 
 +
Unlike regular macros, <code>arg.includer</code> for an inline macro is the parent component of the macro (after all, the inline macro does not really exist).
 +
 
 +
= An Example =
 +
<code>inline.zul</code>: (the macro definition)
 +
 
 +
<source lang="xml" >
 +
<row>
 +
<textbox value="${arg.col1}"/>
 +
<textbox value="${arg.col2}"/>
 +
</row>
 +
</source>
 +
 
 +
<code>useinline.zul</code>: (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>
 +
 
 +
 
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Latest revision as of 05:53, 6 February 2024

Overview

An inline macro is a special macro component which behaves like inline-expansion. Unlike a regular macro component, ZK does not 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 into the target page.

Declare an 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 are 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 inline 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 the properties, including id, are passed to the inline macro too.

Inline versus Regular Macro

As described above, an inline macro is expanded inline when it is used as if they are entered directly. On the other hand, ZK will create a component (an instance of HtmlMacroComponent or deriving) to represent the regular macro. That is, the macro component is created as the parent of the components that are defined in the template.

Inline macros are easier to integrate into sophisticated pages. For example, you cannot use regular macro components in the previous example since rows accepts only row as children, not macro components. It is also easier to access all components defined in a macro since they are expanded inline. However, it also means that the developers must take care of id themselves. In addition, there is no way to instantiate inline macros in pure Java (rather, Execution.createComponents(String, Component, Map) shall be used)[1].

On the other hand, regular macros allow the component developers to provide a custom Java class to represent the component so a better abstraction and addition functionality can be implemented. We will discuss it more in the following section.


  1. ZK Loader does create a component for an inline macro when rendering, and then drop it after expanding into the parent component. Technically, an application can do the same thing but it is not recommended since we might change it in the future.

arg.includer

Unlike regular macros, arg.includer for an inline macro is the parent component of the macro (after all, the inline macro does not really exist).

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>




Last Update : 2024/02/06

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