Appendix A. User Interface Definition Language (UIDL)

<button id="PID2" immediate="true"
        caption="My Button" focusid="1">
    <boolean id="v1" name="state"
             value="false"></boolean>
</button>

["button",
 {"id": "PID2",
  "immediate":true,
  "caption": "My Button",
  "focusid":1,
  "v":{"state":false}
 }
]

Serialization or "painting" of user interface components from server to the client-side engine running in the browser is done through the PaintTarget interface. In Vaadin Release 5, the only implementation of the interface is the JsonPaintTarget, detailed in Section A.2, “JSON Rendering” below.

The abstract AbstractComponent class allows easy painting of user interface components by managing many basic tasks, such as attributes common for all components. Components that inherit the class need to implement the abstract getTag() method that returns the UIDL tag of the component. For example, the implementation for the Button component is as follows:

public String getTag() {
    return "button";
}

AbstractComponent implements the paint() method of the Paintable interface to handle basic tasks in painting, and provides paintContent() method for components to paint their special contents. The method gets the PaintTarget interface as its parameter. The method should call the default implementation to paint any common attributes.

/* Paint (serialize) the component for the client. */
public void paintContent(PaintTarget target)
                throws PaintException {
    // Superclass writes any common attributes in
    // the paint target.
    super.paintContent(target);
    
    // Set any values as variables of the paint target.
    target.addVariable(this, "colorname", getColor());
}

Serialized data can be attributes or variables, serialized with the addAttribute() and addVariable() methods, respectively. You must always serialize the attributes first and the variables only after that.

The API provides a number of variations of the methods for serializing different basic data types. The methods support the native Java data types and strings of the String class. addVariable() also supports vectors of strings.

Contained components are serialized by calling the paint() method of a sub-component, which will call the paintContent() for the sub-component, allowing the serialization of user interfaces recursively. The paint() method is declared in the server-side Paintable interface and implemented in the abstract base classes, AbstractComponent and AbstractComponentContainer (for layouts).

Layout components have to serialize the essential attributes and variables they need, but not the contained components. The AbstractComponentContainer and AbstractLayout baseclasses manage the recursive painting of all the contained components in layouts.

The AbstractField provides an even higher-level base class for user interface components. The field components hold a value or a property, and implement the Property interface to access this property. For example the property of a Button is a Boolean value.

public void paintContent(PaintTarget target)
                 throws PaintException {
    super.paintContent(target);

    // Serialize the switchMode as an attribute
    if (isSwitchMode())
        target.addAttribute("type", "switch");

    // Get the state of the Button safely
    boolean state;
    try {
        state = ((Boolean) getValue()).booleanValue();
    } catch (NullPointerException e) {
        state = false;
    }
    target.addVariable(this, "state", state);

}