Annotate in ZUML"

From Documentation
(3 intermediate revisions by 2 users not shown)
Line 3: Line 3:
  
 
= Annotate Properties =
 
= Annotate Properties =
To annotate a property, you could specify an annotation expression as the value of the property. In other words, if the value of the property is an annotation expression, it is considered as an annotation for the property, rather than a value be be assigned.
+
To annotate a property, you could specify an annotation expression as the value of the property. In other words, if the value of the property is an annotation expression, it is considered as an annotation for the property, rather than a value to be assigned.
  
The format of an annotation expression is <tt>@{''annot-name''(''attr-name1''=''attr-value1, attr-name2=attr-value2'')}</tt>.  That is, an annotation expression is an annotation enclosed with <tt>@{</tt> and <tt>}</tt>.  An annotation consists of a name and a map of attributes which is enclosed with parenthesis. Each attribute is a pair of name-value. For example,
+
The format of an annotation expression:
 +
 
 +
'''@'''''annotation-name'' '''()'''
 +
'''@'''''annotation-name'' '''(''' ''attr-name1'' '''=''' ''attr-value1''''',''' ''attr-name2'' '''=''' ''attr-value2'' ''')'''
 +
'''@'''''annotation-name'' '''(''' ''attr-name1'' '''=''' '''{''' ''attr-value1-1''''',''' ''attr-value1-2'' '''},''' ''attr-name2'' '''=''' ''attr-value2'' ''')'''
 +
 
 +
As shown, an annotation consists of an annotation name and any number of attributes, and an attribute consists of an attribute name and an attribute value. The name of an annotation must start with a letter ('a' - 'z' or 'A' - 'Z'), an underscore ('_'), or a dollar sign ('$').
 +
 
 +
If an attribute has multiple values, these values have to be enclosed with the curly braces (as shown in the third format).
 +
 
 +
For example,
  
 
<source lang="xml" >
 
<source lang="xml" >
<listitem label="@{bind(datasource='author',value='selected')}"/>
+
<listitem label="@bind(datasource='author',value='selected')"/>
 
</source>
 
</source>
  
 
where an annotation called <tt>bind</tt> is annotated to the <tt>label</tt> property, and the <tt>bind</tt> annotation has two attributes: <tt>datasource</tt> and <tt>value</tt>.
 
where an annotation called <tt>bind</tt> is annotated to the <tt>label</tt> property, and the <tt>bind</tt> annotation has two attributes: <tt>datasource</tt> and <tt>value</tt>.
  
If the annotation name is not specified, it is assumed to be <tt>default</tt>. For example, the following two statements are equivalent:
+
If the attribute name is not specified, the name is assumed to be <tt>value</tt>. For example, the following two statements are equivalent:
  
 
<source lang="xml">
 
<source lang="xml">
<listitem label="@{datasource='foo'}"/>
+
<textbox value="@bind(vm.p1.firstName)"/>
<listitem label="@{default(datasource='foo')}"/>
+
<textbox value="@bind(value=vm.p1.firstName)"/>
 
</source>
 
</source>
  
If the attribute name is not specified, it is assumed to be <tt>value</tt>. For example, the following two statements are equivalent:
+
Here is a more complex example.
  
 
<source lang="xml">
 
<source lang="xml">
<listitem label="@{bind(foo)}"/>
+
<textbox value="@save(vm.person.firstName,  before={'cmd1', 'cmd2'})"/>
<listitem label="@{bind(value='foo')}"/>
 
 
</source>
 
</source>
  
Here is a more complex example.
+
where it annotates the <tt>value</tt> property with an annotation named <tt>save</tt>, and the annotation has two attributes: <code>value</code> and <code>before</code>. The value of the <code>before</code> attribute is a two-element array: <code>'cmd1'</code> and <code>'cmd2'</code>. Notice that the quotations, <tt>'</tt> and <tt>"</tt>, will be preserved, so they will be retrieved exactly the same as they are specified in the ZUML document.
 +
 
 +
To annotate the same property with multiple annotations, you could specify them one-by-one and separate them with a space, as shown below.
  
 
<source lang="xml" >
 
<source lang="xml" >
<listitem label="@{selected.name}"/>
+
<textbox value="@bind(vm.value1) @validator('validator1')" errorMessage="@bind(vm.lastMessage1)" />
 
</source>
 
</source>
  
where it annotates the <tt>label</tt> property with an annotation named <tt>default</tt>, and the annotation has one attribute whose name and value are <tt>value</tt> and <tt>selected.name</tt>, respectively. In other words, it is equivalent to the following code snippet.
+
In additions, you could annotate with multiple annotations that have the same name. For example,
 +
 
 +
<source lang="xml">
 +
<textbox value="@bind(vm.first) @bind(vm.second)"/>
 +
</source>
 +
 
 +
where two annotations are annotated to the <code>value</code> property.
 +
 
 +
= Annotate Components =
 +
To annotate a component, you could specify an annotation expression in a specific attribute called <tt>self</tt> as shown below.
  
 
<source lang="xml" >
 
<source lang="xml" >
<listitem label="@{default(value='selected.name')}"/>
+
<label self="@title(value='Hello World')"/>
 
</source>
 
</source>
  
To annotate the same property with multiple annotations, you could specify them one-by-one and separate them with a space, as shown below.
+
where <tt>self</tt> is a keyword to denote the annotation which is used to annotate the component declaration, rather than any property.
 +
 
 +
=The annotation Namespace=
 +
 
 +
ZK Loader detects the annotation automatically. However, it may not be what in you expect. Here we discuss how to resolve these conflicts.
 +
 
 +
==Specify both value and annotation==
 +
If you'd like to specify both the value and the annotations of a given property, you could specify a namespace called annotation to distinguish them. For example,
  
<source lang="xml" >
+
<source lang="xml">
<listitem label="@{ann1(selected.name) ann2(attr2a='attr2a',attr2b)}"/>
+
<textbox value="a property's value" a:value="@save(vm.user)" xmlns:a="annotation"/>
 
</source>
 
</source>
  
= Annotate Components =
+
Then, the textbox's value property will be assigned with a value, <code>"a property's value"</code>, and an annotation, <code>@save(vm.user)</code>.
To annotate a component, you could specify an annotation expression in a specific attribute called <tt>self</tt> as shown below.
+
 
 +
==Specify a value that looks like an annotation==
 +
 
 +
If the value of a property looks like an annotation, you could specify a namespace other than annotation to tell ZK Loader not to interpret it as an annotation. For example,
  
<source lang="xml" >
+
<source lang="xml">
<listitem self="@{bind(each=person)}"/>
+
<textbox u:value="@value()" xmlns:u="zul"/>
 
</source>
 
</source>
  
where <tt>self</tt> is a keyword to denote the annotation is used to annotate the component declaration, rather than any property.
+
Then, <code>@value()</code> will be considered as a value rather an annotation, and assigned to the textbox's value property directly.
  
 
=Version History=
 
=Version History=
Line 59: Line 89:
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
| &nbsp;
+
| 6.0.0
| &nbsp;
+
| December 2011
| &nbsp;
+
| The new syntax was introduced. For ZK 5's syntax, please refer to ZK 5's Developer's Reference. Though not recommended, it is OK to use ZK 5's syntax in ZK 6.
 
|}
 
|}
  
 
{{ZKDevelopersReferencePageFooter}}
 
{{ZKDevelopersReferencePageFooter}}

Revision as of 11:29, 9 February 2012


Annotate in ZUML


Annotations can be applied to the declarations of components and properties in ZUML pages.

Annotate Properties

To annotate a property, you could specify an annotation expression as the value of the property. In other words, if the value of the property is an annotation expression, it is considered as an annotation for the property, rather than a value to be assigned.

The format of an annotation expression:

@annotation-name ()
@annotation-name ( attr-name1 = attr-value1, attr-name2 = attr-value2 )
@annotation-name ( attr-name1 = { attr-value1-1, attr-value1-2 }, attr-name2 = attr-value2 )

As shown, an annotation consists of an annotation name and any number of attributes, and an attribute consists of an attribute name and an attribute value. The name of an annotation must start with a letter ('a' - 'z' or 'A' - 'Z'), an underscore ('_'), or a dollar sign ('$').

If an attribute has multiple values, these values have to be enclosed with the curly braces (as shown in the third format).

For example,

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

where an annotation called bind is annotated to the label property, and the bind annotation has two attributes: datasource and value.

If the attribute name is not specified, the name is assumed to be value. For example, the following two statements are equivalent:

<textbox value="@bind(vm.p1.firstName)"/>
<textbox value="@bind(value=vm.p1.firstName)"/>

Here is a more complex example.

<textbox value="@save(vm.person.firstName,  before={'cmd1', 'cmd2'})"/>

where it annotates the value property with an annotation named save, and the annotation has two attributes: value and before. The value of the before attribute is a two-element array: 'cmd1' and 'cmd2'. Notice that the quotations, ' and ", will be preserved, so they will be retrieved exactly the same as they are specified in the ZUML document.

To annotate the same property with multiple annotations, you could specify them one-by-one and separate them with a space, as shown below.

<textbox value="@bind(vm.value1) @validator('validator1')" errorMessage="@bind(vm.lastMessage1)" />

In additions, you could annotate with multiple annotations that have the same name. For example,

<textbox value="@bind(vm.first) @bind(vm.second)"/>

where two annotations are annotated to the value property.

Annotate Components

To annotate a component, you could specify an annotation expression in a specific attribute called self as shown below.

<label self="@title(value='Hello World')"/>

where self is a keyword to denote the annotation which is used to annotate the component declaration, rather than any property.

The annotation Namespace

ZK Loader detects the annotation automatically. However, it may not be what in you expect. Here we discuss how to resolve these conflicts.

Specify both value and annotation

If you'd like to specify both the value and the annotations of a given property, you could specify a namespace called annotation to distinguish them. For example,

<textbox value="a property's value" a:value="@save(vm.user)" xmlns:a="annotation"/>

Then, the textbox's value property will be assigned with a value, "a property's value", and an annotation, @save(vm.user).

Specify a value that looks like an annotation

If the value of a property looks like an annotation, you could specify a namespace other than annotation to tell ZK Loader not to interpret it as an annotation. For example,

<textbox u:value="@value()" xmlns:u="zul"/>

Then, @value() will be considered as a value rather an annotation, and assigned to the textbox's value property directly.

Version History

Last Update : 2012/02/09


Version Date Content
6.0.0 December 2011 The new syntax was introduced. For ZK 5's syntax, please refer to ZK 5's Developer's Reference. Though not recommended, it is OK to use ZK 5's syntax in ZK 6.



Last Update : 2012/02/09

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