Java Doc for AnnotateDataBinder.java in  » Ajax » zk » org » zkoss » zkplus » databind » Java Source Code / Java DocumentationJava Source Code and Java Documentation

The DataBinder that reads ZUML annotations to create binding info. The ZUML page must declare the XML namespace, xmlns:a="http://www.zkoss.org/2005/zk/annotation", to use the ZUML annotations. The annotation is declared before each Component or specified directly on the Component attributes. For example, the following annotation associates the attibute "value" of the component "textbox" to the bean's value "person.address.city".

 <a:bind value="person.address.city"/>
 <textbox/>
 

Or since ZK 2.4 you can annotate directly on the attribute "value" of the component "textbox" like this.

 <textbox value="@{person.address.city}"/>
 

The @{...} pattern tells the ZUML parser that this is for annotation.

The AnnotateDataBinder knows "a:bind" annotation only. The complete format is like this if you declared it before the Component.

 <a:bind attrY="bean's value;[tag:expression]..."/>
 <componentX/>
 

You can also specify directly on the Component attribute, the complete format is like this:

 <componentX attrY="@{bean's value,[tag='expression']...}"/>
 

This associates the componentX's attribute attrY to the bean's value. The bean's value is something in the form of beanid.field1.field2... You can either call DataBinder.bindBean to bind the beanid to a real bean object or you can neglect it and this DataBinder would try to find it from the variables map via ( org.zkoss.zk.ui.Component.getVariable method. That is, all those variables defined in zscript are accessible by this DataBinder. Note that you can choose either two formats of annotaion as your will and you can even hybrid them together though it is generaly not a good practice.

The tag:expression or tag='expression' is a generic form to bind more metainfo to the attrY of the componentX. The currently supported tag includes "load-when", "save-when", "access", and "converter"

• load-when. You can specify the events concerned when to load the attribute of the component from the bean. Multiple definition is allowed and would be called one by one. For example, the following code snip tells DataBinder that the attribute "value" of Label "fullName" will load from "person.fullName" when the Textbox "firstName" or "lastName" fire "onChange" event.

  Declare in front of the Component:

   <a:bind value="person.firstName"/>
   <textbox id="firstname"/>
   <a:bind value="person.lastName"/>
   <textbox id="lastname"/>
   <a:bind value="person.fullName; load-when:firstname.onChange; load-when:lastname.onChange"/>
   <label id="fullname"/>
   

  Or specify directly on the Component's attribute:

   <textbox id="firstname" value="@{person.firstName}"/>
   <textbox id="lastname" value="@{person.lastName}"/>
   <label id="fullname" value="@{person.fullName, load-when='firstname.onChange,lastname.onChange'}"/>
   

• save-when. You can specify the events concerned when to save the attribute of the component into the bean. Since ZK version 3.0.0, you can specify multiple events in save-when tag (i.e. before ZK 3.0.0, you can specify only one event). The events specified, if fired, will trigger this DataBinder to save the attribute of the component into bean. For example, the following code snip tells DataBinder that the attribute "value" of Textbox "firstName" will save into "person.firstName" when the Textbox itself fire "onChange" event.

  Declare in front of the Component:

   <a:bind value="person.firstName; save-when:self.onChange"/>
   <textbox id="firstName"/>
   

  Or specify directly on the Component's attribute:

   <textbox id="firstName" value="@{person.firstName, save-when='self.onChange'}"/>
   

  However, you don't generally specify the save-when tag. If you don't specify it, the default events are used depends on the natural charactieric of the component's attribute as defined in lang-addon.xml. For example, the save-when of Label.value is default to none while that of Textbox.value is default to self.onChange. That is, the following example is the same as the above one.

  Declare in front of the Component:

   <a:bind value="person.firstName"/>
   <textbox id="firstName"/>
   

  Or specifies directly on the Component's attribute:

   <textbox id="firstName" value="@{person.firstName}"/>
   

  On the other hand, you might not specify the save-when tag nor you want the default events to be used. Then you can specify a "none" keyword or simply leave empty to indicate such cases.

   <a:bind value="person.firstName; save-when:none;"/>
   <textbox id="firstName"/>
   

  or

   <a:bind value="person.firstName; save-when: ;"/>
   <textbox id="firstName"/>
   

  or

   <textbox id="firstName" value="@{person.firstName, save-when='none'}"/>
   

  or

   <textbox id="firstName" value="@{person.firstName, save-when=''}"/>
   

Since 3.0.0, DataBinder supports validation phase before saving attribute content into bean property when triggered by the specified event in save-when tag. It will fire onBindingSave event to the data-binding component and then fire onBindingValidate to the triggering component before really saving component attribute contents into bean's property. So application developers get the chance to handle the value validatiion before saving. In the following example when end user click the "savebtn" button, an "onBindingSave" is first fired to "firtName" and "lastName" textboxes and then an "onBindingValidate" is fired to "savebtn" button. Application developers can register proper event handlers to do what they want to do.

 <textbox id="firstName" value="@{person.firstName, save-when="savebtn.onClick"}" onBindingSave="..."/>
 <textbox id="lastName" value="@{person.lastName, save-when="savebtn.onClick"}" onBindingSave="..."/>
 <button id="savebtn" label="save" onBindingValidate="..."/>
 

Note that the original textbox constraint mechanism is still there. This DataBinder validation phase is an add-on feature that can be applied to all components and attributes that use data binding mechanism.

• access. You can set the access mode of the attrY of the componentX to be "both"(load/save), "load"(load Only), "save"(save Only), or "none"(neither). Multiple definition is NOT allowed and the later defined would override the previous defined one. The access mode would affects the behavior of the DataBinder's loadXxx and saveXxx methods. The DataBinder.loadAll and DataBinder.loadComponent would load only those attributes with "both" or "load" access mode. The DataBinder.saveAll and DataBinder.saveComponent would save only those attributes with "both" or "save" access mode. If you don't specify it, the default access mode depends on the natural characteristic of the component's attribute as defined in lang-addon.xml. For example, Label.value is default to "load" access mode while Textbox.value is default to "both" access mode. For example, the following code snips tells DataBinder that Textbox "firstName" would allowing doing save into bean only not the other way.

  Declare in front of the Component:

   <a:bind value="person.firstName;access:save;"/>
   <textbox id="firstName"/>
   

  Or specify directly on the Component's attribute:

   <textbox id="firstName" value="@{person.firstName, access='save'}"/>
   

• converter. You can specify the class name of the converter that implments the TypeConverter interface. It is used to convert the value between component attribute and bean field. Multiple definition is NOT allowed and the later defined would override the previous defined one. Most of the time you don't have to specify this since this DataBinder supports converting most commonly used types. However, if you specify the TypeConverter class name, this DataBinder will new an instance and use it to cast the class.