Package org.zkoss.stateless.annotation

Annotation Type 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
      java.lang.String field
      The field name of the IComponent.
      java.lang.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 Detail

      • targetId

        java.lang.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

        java.lang.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"