Creation of a UI with linkki

Manual Binding With @Bind

Due to special requirements or custom Fields it is sometimes not possible to use the automatic creation via @UISection. For this case linkki offers the option of 'only' using the data binding. This way, control over creation, arrangement and configuration (e.g. setNullRepresentation() or setConverter()) of the component is kept.

To activate the manual binding the component must be marked with the @Bind annotation. Both fields and methods can be annotated. Manual binding with @Bind supports different component types depending on the Vaadin Framework version. Components based on the following classes and interfaces can be used with @Bind:

  • com.vaadin.ui.Component

  • com.vaadin.ui.AbstractField<T>

  • com.vaadin.ui.Label

  • com.vaadin.ui.Button

  • com.vaadin.data.HasValue<V>

  • com.vaadin.data.HasItems<T>

For Vaadin 7 the base classes allowed for @Bind annotated fields are

  • com.vaadin.ui.Field

  • com.vaadin.ui.Label

  • com.vaadin.ui.Button

  • com.vaadin.ui.AbstractSelect

Then, the data binding can be created via the Binder.

@Bind on Fields
public class AddressFields {

    @Bind(pmoProperty = "street", modelAttribute = Address.PROPERTY_STREET)
    private final TextField streetTxt;

    /* uses the field's name as pmoProperty and modelAttribute */
    @Bind
    private final TextField city;

    /* name of pmoProperty is different from the field name */
    @Bind(pmoProperty = "country", availableValues = AvailableValuesType.DYNAMIC, modelAttribute = Address.PROPERTY_COUNTRY)
    private final ComboBox<Country> countryCb;

}
@Bind on Methods
    @Bind(pmoProperty = "street")
    public TextField getStreetTxt() {
        return streetTxt;
    }

    /* uses the pmoProperty and modelAttribute "city" derived from the method name */
    @Bind
    public TextField getCity() {
        return cityTxt;
    }

    @Bind(pmoProperty = "country", availableValues = AvailableValuesType.DYNAMIC)
    public ComboBox<Country> getCountryCb() {
        return countryCb;
    }
When the data binding of a Vaadin component of a third party library should be used by linkki, it can be activated via inheritance of 'delegate proxies' and @Bind on the methods.
Binding Activation
        new Binder(addressFields, addressPmo).setupBindings(bindingContext);

You can find a sample project with the different binding options on GitHub.

Binding summary:

  • @UISection → simple and quick template with limited configuration options

  • UiElementCreator → automated creation and binding of UI components with control over the layout

  • manual binding → full control, but more effort and direct UI framework dependencies

linkki uses certain naming conventions. That way sources of errors and refactoring complexity are reduced.

The values used in the annotations for pmoProperty and modelAttribute should be defined as constants in the corresponding classes.