ZK Developer's Reference/UI Composing/ZUML

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>. 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.

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 doesn't represent any component. For example,

 <window>
     <zk if="${whater}">
         <textbox/>
         <textbox/>
     </zk>
 </window>

is equivalent to

 <window>
     <textbox if="${whater}"/>
     <textbox if="${whater}"/>
 </window>

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, 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 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 object 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 ZUML Reference

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

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.

<?page title="Grey background" style="background: grey"?>

Notice that there shall 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 to initialize a page, the variable resolver for EL expressions, and so on. For more information about directives, please refer to ZUML Reference.

Language

A language (LanguageDefinition) is a collection of component definitions. It is also known as a component set.

For example, Window, Button and Combobox all belong to the same language called xul/html, which is also known as zul.

Component designers are free to designate a component definition to any component set they prefer, as long as there is no name conflict. In additions, it is OK to use components from several languages in the same ZUML page.

How ZK Identify Language

There are two ways to identify a language: filename's extension and XML namespace.

Identify by Filename's Extension

First, when a ZUML file is parsed, the language will be decided based on the extension of the filename (LanguageDefinition.getByExtension(String)). For example, the extensions associated with xul/html are zul and xul. Thus, if any file whose extension is zul or xul, the default language used to parse it will be assumed to be the xul/html language.

Another example: xhtml is another language (aka., a component set). It is associated with the extensions including zhtml, html, html, and xhtml. Thus, any file whose extension matches one of them will be considered as applying the zhtml language as default.

Notice that the association of filename's extension with a language is about how ZK Loader processes a ZUML page. To really have ZK Loader to process a file, you have to configure WEB-INF/web.xml correctly. For example, if you want to map all XUL files to ZK Loader, you could add the following to WEB-INF/web.xml:

<servlet-mapping>
	<servlet-name>zkLoader</servlet-name>
	<url-pattern>*.xul</url-pattern>
</servlet-mapping>

Identify by XML Namespace

If you map ZK Loader to a filename's extension that is not recognized, you could use XML namespaces to specify the language used to parse it. Each language is associated with a unique XML namespace that you can identify it easily in a ZUML document.

For example, you map ZK Loader to *.foo, then you could specify the xul/html language's namespace, which is http://www.zkoss.org/2005/zul:

<window xmlns="http://www.zkoss.org/2005/zul">
...

where the xmlns attribute declares a XML namespace to associate all element without explicit prefix, such as window in this case.

If you want to several languages in the same XML document, you could use XML namespaces to distinguish them too. For example, the xhtml language's namespace is http://www.w3.org/1999/xhtml, and we could do as follows.

<window xmlns:h="http://www.w3.org/1999/xhtml">
    <h:table>
        <h:tr>
            <h:td>
                <button/>
            </h:td>
        </h:tr>
    </h:table>
</window>

Notice that table, tr and td are also components though they are very simple -- a simple wrapper of HTML tags. There is a better way to generate HTML tags: the native namespace. For more information please refer to the Native Namespace section.

Identify by XML Namespace with Shortcut

To make it easy to specify a namespace, ZK Loader allows shortcut. That is, you need to only specify the last word of the namespace. For example, zul for http://www.zkoss.org/2005/zul, and xhtml for http://www.w3.org/1999/xhtml. Thus, we can simply the previous example as follows.

<window xmlns:h="xhtml">
    <h:span>
        <h:tr>
            <h:td>
                <button/>
            </h:td>
        </h:tr>
    </h:table>
</window>

Version History

Last Update : 2010/11/4

Version	Date	Content
5.0.4	August, 2010	The shortcut was introduced to make it easy to specify a standard namespace, such as native, client and zk.
5.0.5	October, 2010	The shortcut was introduced to make it easy to specify a component set, such as zul and zhtml.