Annotate in ZUML"

From Documentation
(10 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
{{ZKDevelopersReferencePageHeader}}
 
{{ZKDevelopersReferencePageHeader}}
Annotations can be applied to declarations of components and properties in ZUML pages.
+
Annotations can be applied to the declarations of components and properties in ZUML pages.
  
= Annotate Properties ===
+
= Annotate Properties =
To annotate a property, you could specify a value with an annotation expression for the property to annotate. The format of an annotation expression is <tt>@{''annot-name''(''attr-name1''=''attr-value1, attr-name2=attr-value2'')}</tt>. For example,
+
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,
  
 
<source lang="xml" >
 
<source lang="xml" >
<listitem label="@{bind(datasource='author',selected)}"/>
+
<listitem label="@bind(datasource='author',value='selected')"/>
 
</source>
 
</source>
  
In other words, if the value of the property is an annotation expression, it is considered as the annotation for the corresponding property, rather than its value. In the above example, an annotation called <tt>bind</tt> is annotated to the <tt>label</tt> property, and the <tt>bind</tt> property has two attributes: <tt>datasource</tt> and <tt>selected</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 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">
 +
<textbox value="@bind(vm.p1.firstName)"/>
 +
<textbox value="@bind(value=vm.p1.firstName)"/>
 +
</source>
  
If the annotation name is not specified, the name is assumed to be <tt>default</tt>. For example, the following code snippet 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.
+
Here is a more complex example.
  
<source lang="xml" >
+
<source lang="xml">
<listitem label="@{selected.name}"/>
+
<textbox value="@save(vm.person.firstName,  before={'cmd1', 'cmd2'})"/>
 
</source>
 
</source>
  
In other words, it is equivalent to the following code snippet.
+
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="@{default(value='selected.name')}"/>
+
<textbox value="@bind(vm.value1) @validator('validator1')" errorMessage="@bind(vm.lastMessage1)" />
 
</source>
 
</source>
  
To annotate the same property with multiple annotations, you could specify them one-by-one and separated with a space, as shown below.
+
In additions, you could annotate with multiple annotations that have the same name. For example,
  
<source lang="xml" >
+
<source lang="xml">
<listitem label="@{ann1(selected.name) ann2(attr2a='attr2a',attr2b)}"/>
+
<textbox value="@bind(vm.first) @bind(vm.second)"/>
 
</source>
 
</source>
 +
 +
where two annotations are annotated to the <code>value</code> property.
  
 
= Annotate Components =
 
= Annotate Components =
Similarly, you can annotate a component by specifying the annotation expression to a specific attribute called <tt>self</tt> as shown below.
+
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 self="@{bind(each=person)}"/>
+
<label self="@title(value='Hello World')"/>
 +
</source>
 +
 
 +
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">
 +
<textbox value="a property's value" a:value="@save(vm.user)" xmlns:a="annotation"/>
 +
</source>
 +
 
 +
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>.
 +
 
 +
==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">
 +
<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 43: 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.