ZUML"

From Documentation
Line 75: Line 75:
 
</blockquote>
 
</blockquote>
  
==The Text among Elements Is Label Component or Property's Value==
+
==A XML Text Represents Label Component or Property's Value==
 +
 
 +
In general, a XML text is interpreted as a label component. For example,
 +
 
 +
<source lang="xml">
 +
<window>
 +
  Begin ${foo.whatever}
 +
</window>
 +
</source>
 +
 
 +
is equivalent to
 +
 
 +
<source lang="xml">
 +
<window>
 +
  <label value="Begin ${foo.whatever}"/>
 +
</window>
 +
</source>
 +
 
 +
===A XML Text as Property's Value===
 +
 
 +
Depending on component's implementation, the text nested in a XML element could be interpreted as the value of a component's particular property. For example, <javadoc>org.zkoss.zul.Html</javadoc> is one of this kind of components, and
 +
 
 +
<source lang="xml">
 +
<html>Begin ${foo.whatever}</html>
 +
</source>
 +
 
 +
is equivalent to
 +
 
 +
<source lang="xml">
 +
<html content="Begin ${foo.whatever}"/>
 +
</source>
 +
 
 +
It is designed to make it easy to specify multiple-line value, so it is usually used by particular components that requires the multi-line value. Here is a list of components that interprets the XML text as a property's value.
 +
 
 +
{| border='1px'
 +
! Component Name !! Property Name !! Method
 +
|-
 +
| a
 +
| label
 +
| <javadoc method="setLabel(java.lang.String)">org.zkoss.zul.A</javadoc>
 +
|-
 +
| button
 +
| label
 +
| <javadoc method="setLabel(java.lang.String)">org.zkoss.zul.Button</javadoc>
 +
|-
 +
| comboitem
 +
| content
 +
| <javadoc method="setContent(java.lang.String)">org.zkoss.zul.Comboitem</javadoc>
 +
|-
 +
| html
 +
| content
 +
| <javadoc method="setContent(java.lang.String)">org.zkoss.zul.Html</javadoc>
 +
|-
 +
| label
 +
| value
 +
| <javadoc method="setValue(java.lang.String)">org.zkoss.zul.Label</javadoc>
 +
|-
 +
| script
 +
| content
 +
| <javadoc method="setContent(java.lang.String)">org.zkoss.zul.Script</javadoc>
 +
|-
 +
| style
 +
| content
 +
| <javadoc method="setContent(java.lang.String)">org.zkoss.zul.Style</javadoc>
 +
|}
  
 
==A XML Processing Instruction Specifies the Page-wide Information==
 
==A XML Processing Instruction Specifies the Page-wide Information==

Revision as of 05:09, 4 November 2010

Overview

There are two ways to compose UI: XML-based approach and pure-Java approach. Here we describe XML-based approach. For pure-Java approach, please refer the next chapter.

The declaration language is called ZK User Interface Markup Language (ZUML). It is based on XML. Each XML element instructs the ZK Loader which component to create. Each XML attribute describes what value to be assigned to the created component. Each XML processing instruction describes how to process the whole page, such as the page title. For example,

<?page title="Super Application"?>
<window title="Super Hello" border="normal">
    <button label="hi" onClick='alert("hi")'/>

where the first line specifies the page title, the second line creates a root component with title and border, and the third line creates a button with label and an event listener.

This chapter is about the general use of ZUML. For a complete reference, please refer to ZUML Reference.

Basic Rules

If you are not familiar with XML, please take a look at XML Background first.

A XML Element Represents a Component

Each XML element represents a component, except special elements like <zk> and <attribute>[1]. Thus, the following will cause three components (window, textbox and button) being created when ZK Loader processes it.

<window>
  <textbox/>
  <button/>
</window>

In additions, the parent-child relationship of the created components will follow the same hierarchical structure of 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.


  1. For more information about special elements, please refer to ZUML Reference

A XML Attribute Assigns a Value to a Component's Property or Event Listener

Each attribute, except special attributes like if and forEach[1], represents a value that shall 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 assigns "Hello" to window's title property. More precisely, Window.setTitle(String) will be called with "Hello".

<window title="Hello"/>

Like JSP, you could use EL as the value of any attribute. For example, the following 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 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[2] 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>

  1. For more information about special attributes, please refer to ZUML Reference
  2. ZK uses BeanShell to interpret it at run time

A XML Text Represents Label Component or Property's Value

In general, a 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>

A XML Text as Property's Value

Depending on component's implementation, the text nested in a XML element could be interpreted as the value of a component's particular property. For example, Html is one of this kind of components, and

<html>Begin ${foo.whatever}</html>

is equivalent to

<html content="Begin ${foo.whatever}"/>

It is designed to make it easy to specify multiple-line value, so it is usually used by particular components that requires the multi-line value. Here is a list of components that interprets the XML text as a property's value.

Component Name Property Name Method
a label A.setLabel(String)
button label Button.setLabel(String)
comboitem content Comboitem.setContent(String)
html content Html.setContent(String)
label value Label.setValue(String)
script content Script.setContent(String)
style content Style.setContent(String)

A XML Processing Instruction Specifies the Page-wide Information

Component Set and File Extension

Create Components from ZUML Document

Version History

Last Update : 2010/11/4

Version Date Content
     



Last Update : 2010/11/04

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