Annotate ZUML Pages

Annotations can be applied to declarations of components and properties in ZUML pages. There are two way to annotate them: the classic way and the simple way. Which one to use depends on your favorite. You can mix them in the same page if you like.

The Classic Way to annotate the Component Declarations

The annotation appears before the declaration of the element that you want to annotate:

<window xmlns:a="http://www.zkoss.org/2005/zk/annotation">
    <vbox>    
        <a:author name="John Magic" date="3/17/2006"/>        
        <listbox>        
        </listbox>        
...

The annotation is an element in the http://www.zkoss.org/2005/zk/annotation namespace. The element name and attributes can be anything depending on the tool you use. You can annotate the same component declaration with several annotations:

<a:author name="John Magic"/>
<a:editor name="Mary White" date="4/11/2006"/>
<listbox/>

where author and editor are the annotation names, while name and date are the attribute names. In other words, an annotation consists of a name and a map of attributes.

If the annotations annotating a declaration have the same name, they are merged as a single annotation. For example,

<a:define var1="auto"/>
<a:define var2="123"/>
<listbox/>

is equivalent to

<a:define var1="auto" var2="123"/>
<listbox/>

Note: Annotations don't support EL expressions.

The Classic Way to Annotate the Property Declarations

To annotation a property declaration, you can put the annotation in front of the declaration of a property as shown below.

<listitem a:bind="datasource='author',name='name'" value="${author.name}"/>

Alternatively, you can use the attribute element and annotate the declaration of a property similar to the component declaration. In other words, the above annotation is equivalent to the following:

<listitem>
    <a:bind datasource="author" name="name"/>    
    <attribute name="value">${author.name}</attribute>    
</listitem>

Note: if the attribute name of a annotation is omitted, the name is assumed to be value. For example,

<listitem a:bind="value='selected'" value=""/>

is equivalent to

<listitem a:bind="selected" value=""/>

The Simple Way to Annotate the Property Declarations

In addition to annotating with the special XML namespace as described above, there is a simple way to annotate properties: specify a value with an annotation expression for the property to annotate, as show below.

<listitem label="@{bind(datasource='author',selected)}"/>

The format of the annotation expression is @{annot-name(attr-name1=attr-value1, attr-name2=attr-value2)}. In other words, if the value of the property is an anntation expression, it is considered as the annotation for the corresponding property, rather than its value. In the above example, an annotation called bind is annotated to the label property. Thus, it is equivalent to

<listitem a:bind=" datasource='author',selected" label=""/>

If the annotation name is not specified, the name is assumed to be default. For example, the following code snippet annotates the label property with an annotation named default, and the annotation has one attribute whose name and value are value and selected.name, respectively.

<listitem label="@{selected.name}"/>

In other words, it is equivalent to the following code snippet.

<listitem label="@{default(value='selected.name')}"/>

Note: you can annotate the same property with multiple annotations, as shown below.

<listitem label="@{ann1(selected.name) ann2(attr2a='attr2a',attr2b)}"/>

The Simple Way to Annotate the Component Declarations

Similarly, you can annotate a component by specifying the annotation expression to a specific attribute called self as shown below.

<listitem self="@{bind(each=person)}"/>

where self is a keyword to denote the annotation is used to annotate the component declaration, rather than any property. In other words, it is equivalent to

<a:bind each="person"/>
<listitem/>