Package org.zkoss.stateless.annotation

Annotation Interface ActionVariable

@Target({FIELD,PARAMETER})
@Retention(RUNTIME)
public @interface ActionVariable

Annotation which indicates that a method parameter of an Action or a field member of a POJO class should be bound to a value of IComponent attribute at client if possible.

Purpose:

1. To specify on a field of a POJO class to retrieve the value from the field() of the IComponent with the targetId() at client.
2. To specify on a method parameter to retrieve the value from the field() of the IComponent with the targetId() at client.

Example:

Default Behavior

With the annotation without any arguments.

For example,

 @Action(type=Events.ON_CLICK)
 public void doClick(@ActionVariable String email) {

 }
 
 

As shown above, it will be treated as the same as @ActionVariable(targetId="email", field="value"), it means to retrieve the value from the email of a IComponent at client.

AutoMapping with Primitive Type, String, and Date Time Objects in JDK 8

In a usage of @Action or IComponent.withAction() to bind an action handler, the @ActionVariable annotation can be omitted with Primitive Type, String, ActionType, and Date Time Objects in JDK 8. The following example is the same as the declaration with @ActionVariable String email.

 @Action(type=Events.ON_CLICK)
 public void doClick(String email) {

 }
 
 

Note: need to enable -parameters compiler flag to allow the Parameter reflection API since Java 8.

POJO Mapping

The annotation can be specified on POJO fields to indicate that the value of that field from the id of IComponent can be bound to the field.

For example,

 @Action(type=Events.ON_CLICK)
 public void doClick(MyAccount account) {

 }

 public static class MyAccount {
     @ActionVariable
     private String email;

     // getter and setter.
 }
 
 

Or to specify the annotation on a method parameter to indicate all fields of POJO should be bound to the id of IComponent with all its fields.

For example,

 @Action(type=Events.ON_CLICK)
 public void doClick(@ActionVariable(targetId="listbox") MyScrollData listboxScrollData) {

 }

 public static class MyScrollData {
     private int scrollTop;
     private int scrollLeft;
     private int scrollHeight;
     private int scrollWidth;

   // getter and setter.
 }
 

As you can see above, the MyScrollData POJO with four fields, scrollTop, scrollLeft, scrollHeight, and scrollWidth, will be bound to the values of the fields of the listbox immutable component from client.

Note: if some fields are aliases, these fields need to be specified with @ActionVariable(field="alias") and their id will inherit from the declaration of the method parameter, and all the other fields without the declaration annotation will be ignored.

For example,

 @Action(type=Events.ON_CLICK)
 public void doClick(@ActionVariable(targetId="listbox") MyScrollData listboxScrollData) {

 }

 public static class MyScrollData {

     @ActionVariable(field="scrollTop") // the id is inherited from "listbox", not the "top" itself.
     private int top;

     private int scrollLeft; // will be ignored
     private int scrollHeight; // will be ignored
     private int scrollWidth; // will be ignored

     // getter and setter.
 }
 
 

Note: need to enable -parameters compiler flag to allow the Parameter reflection API since Java 8.

Author:

jumperchen

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element	Description
String	field	The field name of the IComponent.
String	targetId	The target id of the IComponent or an empty string to indicate the name of the method parameter or the name of field member is the same as the id.

Element Details

targetId

String targetId

The target id of the IComponent or an empty string to indicate the name of the method parameter or the name of field member is the same as the id.

Reserved IDs

ID equals with SELF meaning the action target itself.

For example,

 public class InputData {
     private String value;

     @ActionVariable(targetId = ActionTarget.SELF, field = "value")
     private Object oldValue;
     // omitted
 }
 
 

As you can see above, the oldValue is bound to the value of the "value" field from the action target that triggers an onChange action or other similar input actions.

Default:

""

field

String field

The field name of the IComponent. By default, it's "value" meaning IComponent#getValue() if any.
For example:

 @ActionVariable(targetId="SelectboxID", field="selectedIndex")
 private int index;
 

Expressions

The string value can be the following.

Note: The expression target can be either the action target or the DOM element of the action target. (The getter priority of DOM element is lower than the client widget).

Expression	Result
"value"	The value of getValue() of the expression target at client
"a.b.c" (Expert only)	The value of getC() of the result of getB() of the result of getA() of the expression target at client Note: if any of the fields is null, then null is returned.
"a|b" (Expert only)	The value of getA() if any, otherwise, the value of getB() is assumed Note: the parentheses "()" can be used to wrap the expression, for example, "(a|b)"

Default:

"value"