【zk开发】zk引语的秘密

The DataBinder that reads ZUML annotations to create binding info.

You have two ways to annotate ZK components. For ZK data binding, you can use @{...} annotaion expression or <a:bind> annotation expression.

To use <a:bind> annotation expression, in the ZUML page you must declare the XML namespace,xmlns:a="http://www.zkoss.org/2005/zk/annotation"? first. Then declare <a:bind> before component to make the annotation.

We suggest annotating directly on the component property with intuitive @{...} expression because it is more readable.（我们建议直接在组件属性中使用注解指令，因为这样可读性更强）

For example, the following annotation associates the attribute "value" of the component "textbox" to the bean's value "person.address.city".

@{...} way:

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

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

<a:bind> way:

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

You can put more metainfo inside the @{...} or <a:bind> so this DataBinder knows what to do.?The complete format is like this:

@{...} way:

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

<a:bind> way:

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

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(java.lang.String, java.lang.Object) ?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?Page.getZScriptVariable(java.lang.String) ?thenComponent.getVariable(java.lang.String, boolean) ?method. That is, all those variables defined in zscript are also accessible by this DataBinder. Note that you can choose either two formats of annotations as your will and you can even hybrid them together though it is not generally 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 tags includes "load-when", "save-when", "access", "converter", "load-after"(since 3.6.1), and "save-after"(since 3.6.1).

• 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. Note that binding is executed BEFORE other event listeners you defined. (If you want the loading to be executed AFTER your event listener, use load-after). 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.

  The @{...} way that specify directly on the Component's attribute:

  ???注意第三个组件示例中load-when发生的时机：compId.onEventNameXXXX

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

  Or the <a:bind> way that 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"/>
   

• (Since 3.6.1)?load-after . Similar to load-when. You can specify the events concerned when to load the attribute of the component from the bean. The only difference is that the loading is done?AFTER ?other event listeners listening to the same event are processed; while in load-when the loading is done?BEFORE ?other event listeners listening to the same event are processed.
• 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 the specified bean. Note that binding is executed BEFORE other event listeners you defined. (If you want the saving to be executed AFTER your event listener, use save-after). For example, the following code snip tells DataBinder that the property "value" of Textbox "firstName" will save into "person.firstName" when the Textbox itself fire "onChange" event.

  The @{...} way that specify directly on the Component's attribute:

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

  Or the <a:bind> way that declare in front of the Component:

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

  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 characteristic of the component's property 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.

  The @{...} way that specify directly on the Component's attribute:

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

  Or the <a:bind> way that declare in front of the Component:

   <a:bind value="person.firstName"/>
   <textbox id="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.

  ??以下配置情况采用默认事件触发

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

  or

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

  or

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

  or

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

• (Since 3.6.1) save-after. Similar to save-when. You can specify the events concerned when to save the attribute of the component to the bean. The only difference is that the saving is doneAFTER ?other event listeners listening to the same event are processed; while in save-when the saving is done?BEFORE ?other event listeners listening to the same event are processed.
• 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). ?save允许修改bean值，load仅访问属性值，both具有save/load二者功能? 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() ?andDataBinder.loadComponent(org.zkoss.zk.ui.Component) ?would load only those attributes with "both" or "load" access mode. The?DataBinder.saveAll() ?andDataBinder.saveComponent(org.zkoss.zk.ui.Component) ?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.

  The @{...} way that specify directly on the Component's attribute:

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

  Or the <a:bind> way that declare in front of the Component:

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

• converter. ?可 以指定实现TypeConverter接口的converter类名字，它将负责组件属性和bean属性之间的互相转换.converter不允许配置多 个，如果定义多个那么后一个将覆盖前一个。大多说情况下你无需指定它，因为DataBinder支持大多说通常使用的类型，然后如果你指定 TypeConverter类名，那么DataBinder实例化这个转换器，替代默认转换器转换

(Since 3.1)如果你指定了其他的非特定的标签，那么他们将被放入map参数中，作为组件属性（key=bindingArgs）存储在组件作用域内，例如?<label id="mylabel" value="@{person.name, answer='yes'}" style="@{person.mystyle, question='no'}">

?然后 mylabel.getAttribute("bindingArgs") 将返回{answer=yes, question=no}两个记录， (自从 3.1)我们支持"distinct" 的概念，用于具有model属性的组件(即Grid, Listbox, Comobobox, 等等.).你可以像下面那样指定该属性告诉 Data Binder 多条记录中或许有相同的对象

 <grid model="@{persons, distinct=false}" ...>
    ...
 </grid>
 

or

 <a:bind model="persons; distinct:false"/>
 <grid ...>
    ...
 </grid>
 

The default value for distinct is "true". However, if you specify distinct=false, the DataBinder will scan the whole ListModel to find out all items with the specified objects (thus worse performance if a big ListModel).

?

自从 3.6.2，如果你指定非特定标签，那么他们将被放入map参数中，并存储在以Xxx_bindingArgs命名的组件作用域内容， 其中Xxx表示注解组件属性的名字

 <label id="mylabel" value="@{person.name, answer='yes'}" style="@{person.mystyle, question='no'}"> 
 

然后 mylabel.getAttribute("value_bindingArgs") 返回{answer=yes} ， mylabel.getAttribute("style_bindingArgs") 返回另外一个map{question=no} entry.

?

自从3.0.0,DataBinder 支持保存前验证阶段，注：DataBinder "save"由save-when或者save-after指定事件触发时执行的行为。 在保存之前，首先触发注解绑定组件的onBindingSave事件，然后在触发onBindingValidate事件 ，在实际保存组件属性内容到bean属性之前触发 ,因此应用开发者可以在保存之前处理输入值的验证， 在下面的例子中，当user点击savebtn按钮结束以后，onBindingSave发送到firtName和lastName文本框，然后 onBindingValidate事件发送到savebtn按钮.应用开发者可以注册适当的事件处理程序做他们想做的事情

 <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="..."/>
 

注意：textbox原有的约束机制让然起作用，该DataBinder验证阶段仅是一个附加特性，它可以用于所有组件的所有属性，

?

?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Listbox listbox = new Listbox();
listbox.addAnnotation("some", null);

void dump(StringBuffer sb, Component comp) {
   ComponentCtrl compCtrl = (ComponentCtrl)comp;
   sb.append(comp.getId()).append(": ")
     .append(compCtrl .getAnnotations()).append('\n');

   for (Iterator it = compCtrl.getAnnotatedProperties().iterator(); it.hasNext();) {
      String prop = it.next();
      sb.append(" with ").append(prop).append(": ")
         .append(compCtrl .getAnnotations(prop)).append('\n');
   }
}