Documentation

UI Components

Tables

The basics of table creation were already mentioned in the chapter binding of a table. This section details the definition of table structure and the Container PMO.

For compatibility and performance reasons, linkki uses the Vaadin 7 Table implementation (from the Vaadin 7 compatibility layer included in Vaadin 8).

Definition of the Table Structure with a Row PMO

The structure of the table is defined in a PMO class, whose instances represent rows in the table. Thus, these classes are called "row PMOs".

Row PMO classes are standard PMOs, which do not represent sections and thus shouldn’t be annotated with @UISection.

Here, the annotation UI element defines the column in the table. A column showing the name of a contact, for instance, can be setup as follows:

    @UITableColumn(expandRatio = 1F)
    @UILabel(position = 10, label = "Name")
    public String getName() {
        return contact.getName();
    }

That means every property that was found in the row PMO class provided by the ContainerPmo is set up as a column. Every defined property specifies the setup of the column as well as the concrete field inside the table’s cell. Next to all aspects that are provided by @UITableColumn it takes the label from the field definition.

The properties of a table column are described using the properties in the row PMO. But these properties cannot be bound to any specific row PMO instance (there might be none if the table is empty or many if there are multiple rows). Hence all bindings are directed to the row PMO class. That also means: If you want to translate a column label the key is created using the class name of the row PMO.

@UITableColumn

By design all properties of a PMO are presented in the table. With the annotation @UITableColumn additional properties of a table column could be bound.

To modify the column size you could use the properties width (in pixels) or expandRatio.

If both properties are set, an IllegalStateException will be thrown when the UI is constructed.

Additionally, with the property collapsible, you could specify a CollapseMode to let the column be collapsible or initially collapsed.

Container PMO

In addition to a row PMO, a container PMO is needed to provide the row PMOs that should be rendered in the table. The container PMO can be optionally annotated with @UISection to display the table in a TableSection. For most cases, the standard implementation SimpleTablePmo can be used as super class.

SimpleTablePmo

Most commonly, the row PMO objects are converted from a list of model objects. In this case, the abstract class org.linkki.core.defaults.columnbased.pmo.SimpleTablePmo<MO, ROW> may be extended. It defines a constructor that requires the list or the supplier for the list of model objects. Additionally the method createRow(MO) needs to be implemented. This method simply takes a model object and creates a row PMO for it and is only called once for every model object. A simple example may look like this:

@UISection
public class SimpleContactTablePmo extends SimpleTablePmo<Contact, ContactRowPmo> {

    private final Consumer<Contact> editAction;
    private final Consumer<Contact> deleteAction;

    public SimpleContactTablePmo(List<Contact> Contacts, Consumer<Contact> editAction, Consumer<Contact> deleteAction) {
        super(Contacts);
        this.editAction = editAction;
        this.deleteAction = deleteAction;
    }

    @Override
    protected ContactRowPmo createRow(Contact Contact) {
        return new ContactRowPmo(Contact, editAction, deleteAction);
    }
}

The SimpleTablePmo is an abstract convenience implementation of the ContainerPmo<ROW> interface.

ContainerPmo Interface

In general, a container PMO have to implement the interface ContainerPmo<ROW>. The type parameter ROW is the row PMO class that defines the table structure.

The method List<ROW> getItems() is called by the ContainerBinding to add the elements to the table. It should always return the same instance of List<ROW> as long as the items do not change. The SimpleItemSupplier offers support for that.

By overriding the default method int getPageLength() the number of rows shown can be controlled. By default 15 rows are shown. It is a common tactic to allow tables to 'grow' to a certain size and then limit the number of lines while also enabling the scrolling for the table. If 0 is returned the table grows dynamically with the content, without limit.

    @Override
    public int getPageLength() {
        return Math.min(ContainerPmo.DEFAULT_PAGE_LENGTH, getItems().size());
    }

The column structure of the table is determined by the row PMO class, which is returned by the method Class<? extends ROW> getItemPmoClass. In the default implementation the class of the generic parameter ROW is returned. To support tables which are configured with other components for the cells, the method can be overwritten and return a subclass of ROW.

If the table should support the adding of items, the default method Optional<ButtonPmo> getAddItemButtonPmo must be overwritten. How a ButtonPmo is created is described in the chapter ButtonPmo.

SimpleItemSupplier

The SimpleItemSupplier<PMO, MO> is used to only create a new List<PMO>, if a row was changed. When using ContainerPmo interface directly, SimpleItemSupplier should be used if the displayed rows may change dynamically.

The instantiating is done with two parameters

modelObjectSupplier of type Supplier<List<MO>> is called to access a list of the model objects
mo2pmoMapping of type Function<MO, PMO> is called for the creation of a PMO for a model object

Example initialising of a SimpleItemSupplier

    public ContactTablePmo(List<Contact> contacts, Consumer<Contact> editAction, Consumer<Contact> deleteAction) {
        items = new SimpleItemSupplier<>(() -> contacts,
                p -> new ContactRowPmo(p, editAction, deleteAction));
    }

Hierarchical Tables

Sometimes, the data in a table should be grouped for presentation, for example when summarizing values over certain categories. In that case, the data represents a tree-like structure with parent-child-relationships between rows. The resulting table will be a Vaadin TreeTable which allows collapsing and showing the child-rows of a row.

Figure 1. Hierarchical table

This can be realized by using org.linkki.core.defaults.columnbased.pmo.HierarchicalRowPmo<PMO>, row PMOs that contain further rows as children. It is possible to use multiple subclasses for row PMOs, using HierarchicalRowPmo only for collapsible rows. To indicate that the table contains hierarchical rows, the ContainerPmo should return true in the method isHierarchical(). By default, this method returns true if getItemPmoClass() returns a class that implements HierarchicalRowPmo, which means that all rows are collapsible.

public abstract class SummarizingPersonRowPmo extends AbstractPersonRowPmo
        implements HierarchicalRowPmo<AbstractPersonRowPmo> {

    private final List<? extends AbstractPersonRowPmo> childRows;

    public SummarizingPersonRowPmo(List<? extends AbstractPersonRowPmo> childRows) {
        this.childRows = childRows;
    }

    @Override
    public List<? extends AbstractPersonRowPmo> getChildRows() {
        return childRows;
    }

If the order of the rows might change due to user input, you should use a SimpleItemSupplier as with the ContainerPmo to avoid recreating the PMOs for unchanged rows.

    public CategoryRowPmo(Supplier<Stream<Player>> playerStreamSupplier,
            Function<Stream<Player>, Stream<CMO>> playersToChildModelObjectMapper,
            Function<CMO, CPMO> childModelObject2pmoMapping) {
        this.playerStreamSupplier = playerStreamSupplier;
        childRowSupplier = new SimpleItemSupplier<>(
                () -> playersToChildModelObjectMapper.apply(playerStreamSupplier.get()).collect(Collectors.toList()),
                childModelObject2pmoMapping);
    }

Row selection in Tables

By default, table rows are not selectable. If table row selection should be possible, the ContainerPmo implementation should also implement the interface SelectableTablePmo. This interface requires three methods:

ROW getSelection(): returns the selected row
setSelection(ROW): sets the new selected row
onDoubleClick(): executes action when a double click is made on the selected row. It is safe to assume that setSelection(ROW) is already called.

Note that it is not possible to nullify the selection once a row is selected.

Example for a selectable table

public class MinimalSelectableTableSectionPmo implements SelectableTablePmo<MinimalSelectableTableRowPmo> {

    public static final String NOTIFICATION_DOUBLE_CLICK = "Double clicked on ";

    public MinimalSelectableTableSectionPmo(List<MinimalSelectableTableRowPmo> rows,
            MinimalSelectableTableRowPmo initiallySelectedRow) {
        this.rows = rows;
        this.selected = initiallySelectedRow;
    }

    @Override
    public MinimalSelectableTableRowPmo getSelection() {
        return selected;
    }

    @Override
    public void setSelection(MinimalSelectableTableRowPmo selectedRow) {
        this.selected = selectedRow;
    }

    @Override
    public void onDoubleClick() {
        Notification.show(NOTIFICATION_DOUBLE_CLICK + selected.getValue());
    }

    @Override
    public List<MinimalSelectableTableRowPmo> getItems() {
        return rows;
    }

}

Figure 2. Example result

By overwriting the default method getFooterPmo() a footer row is generated. The implementation of the interface TableFooterPmo must implement the method getFooterText(String column).

The parameter column is the ID of the column for which the text should be displayed. An example for this would be a sum of all items from a column.

    private final TableFooterPmo footer;

    public CarTablePmo(List<Car> carStorage, Handler addCarAction) {
        this.addCarAction = addCarAction;
        this.items = new SimpleItemSupplier<>(() -> carStorage, CarRowPmo::new);

        this.footer = c -> calculateTotalRetention(c, carStorage);
    }

    @Override
    public Optional<TableFooterPmo> getFooterPmo() {
        return Optional.of(footer);
    }

    private String calculateTotalRetention(String column, List<Car> cars) {

        switch (column) {
            case Car.PROPERTY_RETENTION:
                return String.format("%,.2f", cars.stream()
                        .mapToDouble(Car::getRetention)
                        .sum());

            case Car.PROPERTY_CAR_TYPE:
                return "Total Retention:";

            default:
                return "";
        }
    }

ButtonPmo

Currently the ContainerPmo provides a method getAddItemButtonPmo(), by which a plus button can be added besides the name of the table. This part of the API is being refactored in the issue LIN-128.