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"