Documentation

UI Components

Aspects

linkki can bind more than just the value. In fact, almost every part of the UI state can be taken into account for data binding with linkki. The most common parts of the UI state are for example the enabled state or the visibility. But there are also additional features that may be bound to a component such as the tooltip, available values for selection or CSS class names. For a property, every such UI state part is a so called aspect of the property.

Some aspects are crucial for the functionality of the UI element and are thus directly embedded in the annotation. Besides those, linkki also provides some standalone aspect annotations that can be optionally applied to the UI elements.

Apsects in a PMO

The following example shows two aspects for the property "name".

Value and enabled aspect

    @UITextField(position = 1, label = "Name", enabled = DYNAMIC)
    public String getName() {
        return partner.getName();
    }

    public void setName(String name) {
        partner.setName(name);
    }

    public boolean isNameEnabled() {
        return partner.getType() == PartnerType.NATURAL_PERSON;
    }

The most important aspect is the value aspect. It is also mandatory for the data binding to function. The value aspect is dynamically determined by the getter and setter methods of the property. As the value aspect is critical for the UI element to function, it is always embeded in the UI element annotation.

The second aspect that can be seen is the enabled aspect. This state is defined by the method isNameEnabled.

Each aspect has a name. The enabled aspect has the name "enabled" whereas the value aspect has the empty String as name. In general, the state of the aspect "aspect" for property "property" is determined by the method is/get<Property><Aspect> and set<Property><Aspect>.

Aspects can also apply to the whole PMO if it is also bound to a UI component. In this case, the property name is the empty string.

Aspect on PMO class

@BindStyleNames
@UISection(caption = "Partner")
public class PartnerSectionPmo {

    public List<String> getStyleNames() {
        if (partner.getType() == PartnerType.NATURAL_PERSON) {
            return Arrays.asList("naturalperson");
        } else {
            return Collections.emptyList();
        }
    }
}

Commonly Embedded Aspects

Some aspects are so important or commonly used that they are directly packaged with the UI annotation. Many of those aspects offer configurations that can be set by attributes in the annotation. Most frequently, the attributes share the name of the aspect itself, e.g. @UITextField(enabled = …) in case of the enabled aspect.

Below are the commonly embedded aspects.

Label

Usually there is a label text for each UI element, that describes the element. The content of the label is defined by this attribute.

Exceptions to this are elements whose main feature is their text, such as buttons, checkboxes and links. These UI elements usually do not need a preceding label. Instead, the description of a button is displayed on the button itself, the description of a link is displayed as the link text, while the description of the checkbox is commonly displayed at the right of the checkbox. This kind of describing element can be configured with the property caption in those annotations. Buttons, links and checkboxes can still be configured with a label additionally by overwriting the label property.

If no label/caption is set, the default value "derived.by.linkki" kicks in and linkki uses the default as determined by the PropertyDispatchers (usually the capitalized property name) as label/caption.

The label is used as the column caption in tables.

If an independent label is needed, the UI element UILabel can be used.

Enabled

The property enabled controls whether a component is enabled or disabled. The following configuration options are available:

Table 1. EnabledType
`ENABLED`	the content of the element is modifiable in the UI (default)
`DISABLED`	the content of the element is not modifiable in the UI
`DYNAMIC`	whether the content is modifiable is controlled by the return value of the method `boolean is<PropertyName>Enabled()`

Some components like UILabel and UILink do not offer these options and are always enabled.

Visible

The property visible controls whether the component is visible. There are the following configuration options:

Table 2. VisibleType
`VISIBLE`	the UI element is visible (default)
`INVISIBLE`	the UI element is invisible
`DYNAMIC`	whether the UI element is visible is controlled by the return value of thte method `boolean is<PropertyName>Visible()`

Required

The property required visually highlights required fields. The following configuration options are available:

Table 3. RequiredType
`REQUIRED`	the UI element requires input (a value must be entered/selected)
`REQUIRED_IF_ENABLED`	the UI element requires input if it is `enabled`
`NOT_REQUIRED`	input in the UI element is optional (default)
`DYNAMIC`	whether the element requires input is controlled by the return value of the method `boolean is<PropertyName>Required()`

UILabels, UILinks and UIButtons do not offer these options and are never required.

Fields marked as required are only visually highlighted. No validation is performed.

Standalone Apsect Annotations

Aspects can also be represented by a separate annotation. In this case, those annotations follow the naming convention @Bind[AspectName]. Several frequently used aspects are packaged with linkki as listed below. It is also very easy to create additional custom aspect annotations.

Tooltips

For displaying tooltips on UI elements linkki provides the annotation @BindTooltip. This annotation can be added in the PMO binding to the method to which the UI element is bound. In the case of binding using the @Bind annotation, @BindTooltip must be written directly in the field annotated with @Bind.

The @BindTooltip annotation has two properties:

TooltipType

The following configuration options are available for TooltipType:

Table 4. TooltipType
`AUTO`	the text of the tooltip is read from the attribute `value` if it is not empty, otherwise it reacts like `DYNAMIC` (default)
`STATIC`	the text of the tooltip is read from the attribute `value`
`DYNAMIC`	the text of the tooltip is determined by the return value of the method `String get<PropertyName>Tooltip()`. The `value` is ignored.

Tooltips can only be added to fields and buttons.

    @UITableColumn(width = 50)
    @BindTooltip("Edit")
    @UIButton(position = 30, icon = VaadinIcons.EDIT, showIcon = true, caption = "")
    public void edit() {
        editAction.accept(contact);
    }

Bind Read-Only State

To change a component’s read-only behavior, linkki provides the annotation @BindReadOnly. This annotation can be used in combination with @Bind or UI-annotations.

The @BindReadOnly annotation is evaluated after @Bind or @UI-annotations which might already have set a read-only state.

This annotation should be used only in exceptional cases, since most of the behavior is better controlled by a PropertyBehavior.

The @BindReadOnly Annotation has only one property, ReadOnlyType. Per default, ReadOnlyType#ALWAYS is selected. Following ReadOnlyTypes are available:

Table 5. ReadOnlyType
`ALWAYS`	The component is always read-only (default).
`DYNAMIC`	The read-only behavior of the component is determined by the return value of the method `is<PropertyName>ReadOnly()`.
`DERIVED`	The component is read-only if no setter method exists or the property dispatcher returns read-only for this property.

If a component is supposed to be writable even though the rest of the UI is in read-only-mode, use @BindReadOnlyBehavior with value ACTIVE, e.g. an input field to filter the content of a table.

Bind Read-Only Behavior

@BindReadOnlyBehavior changes a component’s behaviour if it is set to read-only. The read-only status is determined by the property-dispatcher-chain. There is no need to define additional methods as is usually the case with dynamic aspect definitions.

The aspect has a value of type ReadOnlyBehaviorType with the following options available:

Table 6. ReadOnlyBehaviorType
`INVISIBLE`	Component is invisible in read-only-mode. This type is the default value.
`DISABLED`	Component is visible but disabled in read-only-mode.
`WRITABLE`	Component remains writable in read-only-mode.

INVISIBLE and DISABLED are especially useful for buttons which cannot be read-only. The type WRITABLE is useful for components which do not change data like an input field that is used to filter the content in the user interface.

Style Names

Vaadin components get rendered as HTML and styled via CSS. Using the @BindStyleNames annotation custom style names can be bound to a component in addition to those provided by Vaadin.

A single style name can be provided as the annotation’s value (@BindStyleNames("foo")) as well as an array of multiple style names (@BindStyleNames({"bar", "baz"})).

The value can also be omitted, leading to dynamic resolution via a get<Property>StyleNames() method that may return a String or any Collection<String>.

Caption

For sections and applicable fields(e.g. UICheckbox, UIButton), the caption can be set with the separate @BindCaption annotation.

The @BindCaption annotation has two properties:

Value: This is the text displayed on CaptionType.STATIC. Its default value is an empty string ("").

CaptionType: The following configuration options are available for CaptionType:

Table 7. CaptionType
`AUTO`	reacts as `DYNAMIC` if value is empty or `STATIC` if it is not empty (default)
`STATIC`	the caption is read from the attribute `value`
`DYNAMIC`	the caption is determined by the return value of the method `String get<PropertyName>Caption()`. The `value` is ignored.
`NONE`	explicitly set the caption to `null`

Icon

UI elements such as @UIButton or @UILink can have an icon that is shown with the component’s caption. This can be set with the @BindIcon annotation.

The @BindIcon annotation has two properties:

Value: This is the icon displayed on IconType.STATIC. Its default value is a smiley that should alarm the user in case of unintentional usage.

IconType: The following configuration options are available for IconType:

Table 8. IconType
`AUTO`	reacts as `STATIC` if icon is specified or `DYNAMIC` if not (default)
`STATIC`	the icon is read from the attribute `value`
`DYNAMIC`	the icon is determined by the return value of the method `Resource get<PropertyName>Icon()`. The `value` is ignored.

The class VaadinIcons contains many Icons for easy use. The Vaadin documentation includes a reference page listing all available icons as well as documentation how to creating your own FontIcons.

Since annotations do not support a null value and VaadinIcons do not have a "NO_ICON" we cannot really specify "no icon" to automatically use a dynamic one. Hence we decided to use a quite uncommon icon (NATIVE_BUTTON) as default. If you really need exactly this icon, use iconType=STATIC explicitly.