Basic Rules"
m (remove empty version history (via JWB)) |
|||
| (26 intermediate revisions by 3 users not shown) | |||
| Line 4: | Line 4: | ||
If you are not familiar with XML, please take a look at [[ZK Developer's Reference/UI Composing/ZUML/XML Background|XML Background]] first. | If you are not familiar with XML, please take a look at [[ZK Developer's Reference/UI Composing/ZUML/XML Background|XML Background]] first. | ||
| − | = | + | =An XML Element Represents a Component= |
| − | Each XML element represents a component, except special elements like <zk> and <attribute>. Thus, the following will cause three components (window, textbox and button) | + | Each XML element represents a component, except for special elements like <zk> and <attribute>. Thus, the following example will cause three components (window, textbox and button) to be created when ZK Loader processes it. |
<source lang="xml"> | <source lang="xml"> | ||
| Line 15: | Line 15: | ||
</source> | </source> | ||
| − | In | + | In addition, the parent-child relationship of the created components will follow the same hierarchical structure as the XML document. In the previous example, window will be the parent of textbox and button, while textbox is the first child and button is the second. |
=Special XML Elements= | =Special XML Elements= | ||
| Line 25: | Line 25: | ||
</source> | </source> | ||
| − | [[ZUML Reference/ZUML/Elements/zk|The zk element]] is a special element used to aggregate other components. Unlike a real component (say, < | + | [[ZUML Reference/ZUML/Elements/zk|The zk element]] is a special element used to aggregate other components. Unlike a real component (say, <code>hbox</code> or <code>div</code>), it is not part of the component tree being created. In other words, it does not represent any components. For example, |
<source lang="xml" > | <source lang="xml" > | ||
| Line 47: | Line 47: | ||
For more information about special elements, please refer to [[ZUML Reference/ZUML/Elements|ZUML Reference]]. | For more information about special elements, please refer to [[ZUML Reference/ZUML/Elements|ZUML Reference]]. | ||
| − | = | + | =An XML Attribute Assigns a Value to a Component's Property or Event Listener= |
| − | Each attribute, except special attributes like <code>if</code> and <code>forEach</code>, represents a value that | + | Each attribute, except for special attributes like <code>if</code> and <code>forEach</code>, represents a value that should be assigned to a property of a component after it is created. The attribute name is the property name, while the attribute value is the value to assign. For example, the following example assigns <code>"Hello"</code> to the window's title property. More precisely, <javadoc method="setTitle(java.lang.String)">org.zkoss.zul.Window</javadoc> will be called with the argument <code>"Hello"</code>. |
<source lang="xml"> | <source lang="xml"> | ||
| Line 55: | Line 55: | ||
</source> | </source> | ||
| − | Like JSP, you could use EL | + | Like JSP, you could use EL for the value of any attributes. The following example assigns the value of the request parameter called name to window's title. |
<source lang="xml"> | <source lang="xml"> | ||
| Line 63: | Line 63: | ||
For more information about EL expressions, please refer to [[ZUML Reference/EL Expressions|ZUML Reference]]. | For more information about EL expressions, please refer to [[ZUML Reference/EL Expressions|ZUML Reference]]. | ||
| − | ==Assign Event Listener if Name Starts With <code>on</code>== | + | ==Assign Event Listener if the Name Starts With <code>on</code>== |
| − | If the attribute name starts with <code>on</code> and the third letter is uppercase, an event listener is assigned. For example, we can register an event listener to handle the onClick event as follows | + | If the attribute name starts with <code>on</code> and the third letter is uppercase, an event listener is assigned. For example, we can register an event listener to handle the onClick event as follows: |
<source lang="xml"> | <source lang="xml"> | ||
| Line 86: | Line 86: | ||
==Special Attributes== | ==Special Attributes== | ||
| − | There are a few special attributes dedicated to special functionality rather than assigning properties or handling events. For example, the forEach attribute is used to specify a collection of | + | There are a few special attributes dedicated to special functionality rather than assigning properties or handling events. For example, the forEach attribute is used to specify a collection of objects such that the XML element it belongs will be evaluated repeatedly for each object of the collection. |
<source lang="xml"> | <source lang="xml"> | ||
| Line 94: | Line 94: | ||
</source> | </source> | ||
| − | For more information about special attributes, please refer to the [[ZK Developer's Reference/UI Composing/ZUML/Iterative Evaluation|Iterative Evaluation]] section | + | For more information about special attributes, please refer to the [[ZK Developer's Reference/UI Composing/ZUML/Iterative Evaluation|Iterative Evaluation]] section and the [[ZUML Reference/ZUML/Attributes|ZUML Reference]] |
| − | = | + | =An XML Text Represents Label Component or Property's Value= |
| − | In general, | + | In general, an XML text is interpreted as a label component. For example, |
<source lang="xml"> | <source lang="xml"> | ||
| Line 114: | Line 114: | ||
</source> | </source> | ||
| − | == | + | ==An XML Text as Property's Value== |
| − | Depending on component's implementation, the text nested in | + | Depending on the component's implementation, the text nested in an XML element can be interpreted as the value of a component's particular property. For example, <javadoc>org.zkoss.zul.Html</javadoc> is one of these kinds of components, and |
<source lang="xml"> | <source lang="xml"> | ||
| Line 128: | Line 128: | ||
</source> | </source> | ||
| − | + | This is designed to make it easy to specify multiple-line value. This is usually used by a particular component that requires a multiple-lines value. For a complete list of components that interpret the XML text as a property's value, please refer to the [[ZUML Reference/ZUML/Texts|ZUML Reference]]. | |
| − | = | + | =An XML Processing Instruction Specifies the Page-wide Information= |
| − | Each XML processing instruction specifies the instruction how to process the XML document. It is called directives in ZK. For example, the following specifies the page title and style. | + | Each XML processing instruction specifies the instruction on how to process the XML document. It is called directives in ZK. For example, the following specifies the page title and style. |
<source lang="xml"> | <source lang="xml"> | ||
| Line 138: | Line 138: | ||
</source> | </source> | ||
| − | Notice that there | + | Notice that there should be ''no'' whitespace between the question mark and the processing instruction's name (i.e., page in the above example). |
| − | The other directives include the declaration of components, the class | + | The other directives include the declaration of components, the class for initializing a page, the variable resolver for EL expressions, and so on. |
For more information about directives, please refer to [[ZUML Reference/ZUML/Processing Instructions|ZUML Reference]]. | For more information about directives, please refer to [[ZUML Reference/ZUML/Processing Instructions|ZUML Reference]]. | ||
| − | + | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
{{ZKDevelopersReferencePageFooter}} | {{ZKDevelopersReferencePageFooter}} | ||
Latest revision as of 05:54, 6 February 2024
If you are not familiar with XML, please take a look at XML Background first.
An XML Element Represents a Component
Each XML element represents a component, except for special elements like <zk> and <attribute>. Thus, the following example will cause three components (window, textbox and button) to be created when ZK Loader processes it.
<window>
<textbox/>
<button/>
</window>
In addition, the parent-child relationship of the created components will follow the same hierarchical structure as the XML document. In the previous example, window will be the parent of textbox and button, while textbox is the first child and button is the second.
Special XML Elements
There are a few elements dedicated to special functionality rather than a component. For example,
<zk>...</zk>
The zk element is a special element used to aggregate other components. Unlike a real component (say, hbox or div), it is not part of the component tree being created. In other words, it does not represent any components. For example,
<window>
<zk if="${whatever}">
<textbox/>
<textbox/>
</zk>
</window>
is equivalent to
<window>
<textbox if="${whatever}"/>
<textbox if="${whatever}"/>
</window>
For more information about special elements, please refer to ZUML Reference.
An XML Attribute Assigns a Value to a Component's Property or Event Listener
Each attribute, except for special attributes like if and forEach, represents a value that should be assigned to a property of a component after it is created. The attribute name is the property name, while the attribute value is the value to assign. For example, the following example assigns "Hello" to the window's title property. More precisely, Window.setTitle(String) will be called with the argument "Hello".
<window title="Hello"/>
Like JSP, you could use EL for the value of any attributes. The following example assigns the value of the request parameter called name to window's title.
<window title="${param.name}"/>
For more information about EL expressions, please refer to ZUML Reference.
Assign Event Listener if the Name Starts With on
If the attribute name starts with on and the third letter is uppercase, an event listener is assigned. For example, we can register an event listener to handle the onClick event as follows:
<button onClick="do_something_in_Java())"/>
The attribute value must be a valid Java code, and it will be interpreted[1] when the event is received. You could specify different languages by prefixing the language name. For example, we could write the event listener in Groovy as follows.
<vlayout onClick="groovy:self.appendChild(new Label('New'));">
Click me!
</vlayout>
Special Attributes
There are a few special attributes dedicated to special functionality rather than assigning properties or handling events. For example, the forEach attribute is used to specify a collection of objects such that the XML element it belongs will be evaluated repeatedly for each object of the collection.
<listbox>
<listitem forEach="${customers}" label="${each.name}"/>
</listbox>
For more information about special attributes, please refer to the Iterative Evaluation section and the ZUML Reference
An XML Text Represents Label Component or Property's Value
In general, an XML text is interpreted as a label component. For example,
<window>
Begin ${foo.whatever}
</window>
is equivalent to
<window>
<label value="Begin ${foo.whatever}"/>
</window>
An XML Text as Property's Value
Depending on the component's implementation, the text nested in an XML element can be interpreted as the value of a component's particular property. For example, Html is one of these kinds of components, and
<html>Begin ${foo.whatever}</html>
is equivalent to
<html content="Begin ${foo.whatever}"/>
This is designed to make it easy to specify multiple-line value. This is usually used by a particular component that requires a multiple-lines value. For a complete list of components that interpret the XML text as a property's value, please refer to the ZUML Reference.
An XML Processing Instruction Specifies the Page-wide Information
Each XML processing instruction specifies the instruction on how to process the XML document. It is called directives in ZK. For example, the following specifies the page title and style.
<?page title="Grey background" style="background: grey"?>
Notice that there should be no whitespace between the question mark and the processing instruction's name (i.e., page in the above example).
The other directives include the declaration of components, the class for initializing a page, the variable resolver for EL expressions, and so on. For more information about directives, please refer to ZUML Reference.