table elements

table attributes

Methods of the Table interface

rows – a required element if the datasource attribute is used for data binding.

@Inject
private Table<Customer> table;

@Subscribe
protected void onInit(InitEvent event) {
    table.setIconProvider(new ListComponent.IconProvider<Customer>() {
        @Nullable
        @Override
        public String getItemIcon(Customer entity) {
            CustomerGrade grade = entity.getGrade();
            switch (grade) {
                case PREMIUM: return "icons/premium_grade.png";
                case HIGH: return "icons/high_grade.png";
                case MEDIUM: return "icons/medium_grade.png";
                default: return null;
            }
        }
    });
}

columns – an element defining the set of columns for a table. If not specified, columns will be automatically determined from the attributes from the view that is defined in dataContainer. Element columns has the following attributes:

<columns>
    <column property="name" sort="DESCENDING"/>
    <column property="parent" sort="ASCENDING"/>
</columns>

rowsCount − an optional element adding the RowsCount component for the table; this component enables loading the table data in pages. Page size can be defined by limiting the number of records in the data container using the loader’s setMaxResults() method. Typically, this is performed by a Filter component linked to the table’s data loader. However, if there is no generic filter, this method can be called directly from the screen controller.

<rowsCount autoLoad="true"/>

boolean autoLoadEnabled = rowsCount.getAutoLoad();
rowsCount.setAutoLoad(false);

actions − an optional element describing the actions, related to the table. In addition to custom arbitrary actions, the element supports the following standard actions, defined in the com.haulmont.cuba.gui.actions.list package: create, edit, remove, refresh, add, exclude, excel.

buttonsPanel – an optional element, which adds a ButtonsPanel container to show action buttons above the table.

emptyStateMessage attribute enables to set the message when no data is loaded, null items are set, or empty container is used. This attribute is often used together with the emptyStateLinkMessage attribute. The message should contain information about why the table is empty. For example:

<table id="table"
       emptyStateMessage="No data added to the table"
       ...
       width="100%">

emptyStateLinkMessage attribute enables to set the link message when no data is loaded, null items are set, or empty container is used. This attribute is often used together with the emptyStateMessage attribute. The message should describe the action that needs to be performed to fill the table. For example:

<table id="table"
       emptyStateMessage="No data added to the table"
       emptyStateLinkMessage="Add data (Ctrl+\)"
       ...
       width="100%">

@Install(to = "customersTable", subject = "emptyStateLinkClickHandler")
private void customersTableEmptyStateLinkClickHandler(Table.EmptyStateClickEvent<Customer> emptyStateClickEvent) {
    screenBuilders.editor(emptyStateClickEvent.getSource())
            .newEntity()
            .show();
}

multiselect attribute enables setting multiple selection mode for table rows. If multiselect is true, users can select multiple rows in the table using keyboard or mouse holding Ctrl or Shift keys. By default, multiple selection mode is switched off.

sortable attribute enables sorting data in the table. By default, it is set to true. If sorting is allowed, clicking a column header will show a / icon to the right of the column name. You can disable sorting for a particular column by using its sortable attribute.

<table id="ordersTable"
       dataContainer="ordersDc">
    <columns>
        <column id="customer.name"/> <!-- the 'name' attribute of the 'Customer' entity -->
        <column id="contract"/>      <!-- the 'Contract' entity -->
    </columns>
</table>

presentations attribute controls the mechanism of presentations. By default, the value is false. If the attribute value is true, a corresponding icon is added to the top right corner of the table . The mechanism of presentations is implemented for the Web Client only.

If the columnControlVisible attribute is set to false, users cannot hide columns using the drop-down menu of the button in the right part of the table header. Currently displayed columns are marked with checkmarks in the menu. There are additional menu items:

If the reorderingAllowed attribute is set to false, users cannot change columns order by dragging them with a mouse.

If the columnHeaderVisible attribute is set to false, the table has no header.

If the showSelection attribute is set to false, a current row is not highlighted.

contextMenuEnabled attribute enables the context menu. By default this attribute is set to true. The context menu shows table actions (if any) and the System Information item containing information on the selected entity (if the user has cuba.gui.showInfo permission).

Setting multiLineCells to true enables multi-line display for cells containing several lines of text. In this mode, the web browser will load all the rows of the current table page at once, instead of lazy-loading the visible part of the table. It is required for proper scrolling in the Web Client. The default value is false.

aggregatable attribute enables aggregation for table rows. The following operations are supported:

<table id="itemsTable" aggregatable="true" dataContainer="itemsDc">
    <columns>
        <column id="product"/>
        <column id="quantity"/>
        <column id="amount">
            <aggregation type="SUM"/>
        </column>
    </columns>
</table>

<column id="amount">
    <aggregation type="SUM">
        <formatter class="com.company.sample.MyFormatter"/>
    </aggregation>
</column>

public class TimeEntryAggregation implements AggregationStrategy<List<TimeEntry>, String> {
    @Override
    public String aggregate(Collection<List<TimeEntry>> propertyValues) {
        HoursAndMinutes total = new HoursAndMinutes();
        for (List<TimeEntry> list : propertyValues) {
            for (TimeEntry timeEntry : list) {
                total.add(HoursAndMinutes.fromTimeEntry(timeEntry));
            }
        }
        return StringFormatHelper.getTotalDayAggregationString(total);
    }
    @Override
    public Class<String> getResultClass() {
        return String.class;
    }
}

AggregationInfo info = new AggregationInfo();
info.setPropertyPath(metaPropertyPath);
info.setStrategy(new TimeEntryAggregation());

Table.Column column = weeklyReportsTable.getColumn(columnId);
column.setAggregation(info);

editable attribute enables switching the table to in-place editing mode. In this mode, the columns with editable = true attribute show components to edit the attributes of the corresponding entity.

In Web Client with a Halo-based theme, stylename attribute enables setting predefined styles to the Table component either in the XML descriptor or in the screen controller:

<table id="table"
       dataContainer="itemsDc"
       stylename="no-stripes">
    <columns>
        <column id="product"/>
        <column id="quantity"/>
    </columns>
</table>

table.setStyleName(HaloTheme.TABLE_NO_STRIPES);

addColumnCollapsedListener() method is useful for tracking the columns visibility with the help of the ColumnCollapsedListener interface implementation.

getSelected(), getSingleSelected() return instances of the entities corresponding to the selected rows of the table. A collection can be obtained by invoking getSelected(). If nothing is selected, the application returns an empty set. If multiselect is disabled, it is more convenient to use getSingleSelected() method returning one selected entity or null, if nothing is selected.

addSelectionListener() enables tracking the table rows selection. For example:

customersTable.addSelectionListener(customerSelectionEvent ->
        notifications.create()
                .withCaption("You selected " + customerSelectionEvent.getSelected().size() + " customers")
                .show());

@Subscribe("customersTable")
protected void onCustomersTableSelection(Table.SelectionEvent<Customer> event) {
    notifications.create()
            .withCaption("You selected " + customerSelectionEvent.getSelected().size() + " customers")
            .show();
}

addGeneratedColumn() method allows you to define custom representation of data in a column. It takes two parameters: identifier of the column and an implementation of the Table.ColumnGenerator interface. Identifier can match one of the identifiers set for table columns in XML-descriptor – in this case the new column is inserted instead of the one defined in XML. If the identifier does not match any of the columns, a new column is added to the right.

@Inject
private GroupTable<Car> carsTable;
@Inject
private CollectionContainer<Car> carsDc;
@Inject
private CollectionContainer<Color> colorsDc;
@Inject
private UiComponents uiComponents;
@Inject
private Actions actions;

@Subscribe
protected void onInit(InitEvent event) {
    carsTable.addGeneratedColumn("color", entity -> {
        LookupPickerField<Color> field = uiComponents.create(LookupPickerField.NAME);
        field.setValueSource(new ContainerValueSource<>(carsTable.getInstanceContainer(entity), "color"));
        field.setOptions(new ContainerOptions<>(colorsDc));
        field.addAction(actions.create(LookupAction.class));
        field.addAction(actions.create(OpenAction.class));
        return field;
    });
}

carsTable.getColumn("colour").setCaption("Colour");

requestFocus() method allows you to set focus on the concrete editable field of a certain row. It takes two parameters: an entity instance which identifies the row and the column identifier. Example of requesting a focus:

table.requestFocus(item, "count");

scrollTo() method allows you to scroll table to the concrete row. It takes one parameter: an entity instance identifying the row.

table.scrollTo(item);

setCellClickListener() method can save you from adding generated columns with components when you need to draw something in cells and receive notifications when a user clicks inside these cells. The CellClickListener implementation passed to this method receives the selected entity and the column identifier. The cells content will be wrapped in span element with cuba-table-clickable-cell style which can be used to specify the cell representation.

@Inject
private Table<Customer> customersTable;
@Inject
private Notifications notifications;

@Subscribe
protected void onInit(InitEvent event) {
    customersTable.setCellClickListener("name", customerCellClickEvent ->
            notifications.create()
                    .withCaption(customerCellClickEvent.getItem().getName())
                    .show());
}

You can use the setAggregationDistributionProvider() method to specify the AggregationDistributionProvider that defines the rules for distributing the aggregated value between rows in a table. If the user enters a value in an aggregated cell, it is distributed to the constituent cells according to a custom algorithm. Supported only for the TOP aggregation style. To make aggregated cells editable, use the editable attribute of the aggregation element.

The getAggregationResults() method returns a map with aggregation results, where map keys are table column identifiers, and values are aggregation values.

The setStyleProvider() method enables setting table cell display style. The method accepts an implementation of Table.StyleProvider interface as a parameter. getStyleName() method of this interface is invoked by the table for each row and each cell separately. If the method is invoked for a row, the first parameter contains the entity instance displayed by the row, the second parameter is null. If the method is called for a cell, the second parameter contains the name of the attribute displayed by the cell.

@Inject
protected Table customersTable;

@Subscribe
protected void onInit(InitEvent event) {
    customersTable.setStyleProvider((customer, property) -> {
        if (property == null) {
            // style for row
            if (hasComplaints(customer)) {
                return "unsatisfied-customer";
            }
        } else if (property.equals("grade")) {
            // style for column "grade"
            switch (customer.getGrade()) {
                case PREMIUM: return "premium-grade";
                case HIGH: return "high-grade";
                case MEDIUM: return "medium-grade";
                default: return null;
            }
        }
        return null;
    });
}

.v-table-row.unsatisfied-customer {
  font-weight: bold;
}
.v-table-cell-content.premium-grade {
  background-color: red;
}
.v-table-cell-content.high-grade {
  background-color: green;
}
.v-table-cell-content.medium-grade {
  background-color: blue;
}

addPrintable() method enables setting a custom presentation of the data within a column when exporting to an XLS file via the excel standard action or directly using the ExcelExporter class. The method accepts the column identifier and an implementation of the Table.Printable interface for the column. For example:

ordersTable.addPrintable("customer", new Table.Printable<Customer, String>() {
    @Override
    public String getValue(Customer customer) {
        return "Name: " + customer.getName;
    }
});

ordersTable.addGeneratedColumn("product", new Table.PrintableColumnGenerator<Order, String>() {
    @Override
    public Component generateCell(Order entity) {
        Label label = uiComponents.create(Label.NAME);
        Product product = order.getProduct();
        label.setValue(product.getName() + ", " + product.getCost());
        return label;
    }

    @Override
    public String getValue(Order entity) {
        Product product = order.getProduct();
        return product.getName() + ", " + product.getCost();
    }
});

The setItemClickAction() method allows you to define an action that will be performed when a table row is double-clicked. If such action is not defined, the table will attempt to find an appropriate one in the list of its actions in the following order:

The setEnterPressAction() allows you to define an action executed when Enter is pressed. If such action is not defined, the table will attempt to find an appropriate one in the list of its actions in the following order:

setEmptyStateLinkClickHandler allows you to provide a handler which will be invoked after clicking on the empty state link message:

@Subscribe
public void onInit(InitEvent event) {
    customersTable.setEmptyStateLinkClickHandler(emptyStateClickEvent ->
                screenBuilders.editor(emptyStateClickEvent.getSource())
                    .newEntity()
                    .show());
}

The setItemDescriptionProvider method sets the item description provider that is used for generating optional tooltip descriptions for items.

@Inject
private Table<Department> departmentsTable;

@Subscribe
public void onInit(InitEvent event) {
    departmentsTable.setItemDescriptionProvider(((department, property) -> {
        if (property == null) { (1)
            if (department.getParentDept() == null) {
                return "Parent Department";
            }
        } else if (property.equals("active")) { (2)
            return department.getActive()
                    ? "Active department"
                    : "Inactive department";
        }
        return null;
    }));
}