dataGrid elements

dataGrid attributes

Methods of the DataGrid interface

Usage of description providers

Usage of the DetailsGenerator interface

Usage of DataGrid inline editor

Usage of the ColumnGenerator interface

Usage of renderers

Header and Footer

DataGrid styles

columns - an element that defines the DataGrid columns set. 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:

<column id="date" property="date">
    <formatter class="com.haulmont.cuba.gui.components.formatters.DateFormatter"
               format="yyyy-MM-dd HH:mm:ss"
               useUserTimezone="true"/>
</column>

actions - optional element to define actions for DataGrid. Besides custom actions, the standard actions from the ListActionType enumeration are also supported: create, edit, remove, refresh, add, exclude.

buttonsPanel - creates a ButtonsPanel container with action buttons above the DataGrid component.

rowsCount - optional element that creates a RowsCount component for the DataGrid. RowsCount enables pagination of data, the page size is set by limitation of records in the data loader with the help of CollectionLoader.setMaxResults() method from the screen controller. Another way to do this is to use a universal Filter component bound with the same data container as the DataGrid.

<rowsCount autoLoad="true"/>

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

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

<dataGrid id="ordersDataGrid"
          dataContainer="ordersDc"
          aggregationPosition="BOTTOM"
          aggregatable="true">
    <columns>
        <column id="customerGrade" property="customer.grade">
            <aggregation strategyClass="com.company.sample.CustomerGradeAggregation"
                         valueDescription="msg://customerGradeAggregationDesc"/>
        </column>
        <column id="amount" property="amount">
            <aggregation type="SUM">
                <formatter class="com.company.sample.MyFormatter"/>
            </aggregation>
        </column>
        ...
    </columns>
    ...
</dataGrid>

The aggregationPosition attribute allows you to specify the location of the aggregation row: TOP or BOTTOM. TOP is used by default.

columnResizeMode - sets the mode of columns resizing by user. Two modes are supported:

columnsCollapsingAllowed - defines whether a user can hide columns in the sidebar menu. Displayed columns are checked in the menu. There are additional menu items:

contextMenuEnabled - enables turning on and off the context menu. Default value is true.

editorBuffered - sets the buffered editor mode. The default mode is buffered (true).

editorCancelCaption - sets the caption on the cancel button in the DataGrid editor.

editorCrossFieldValidate - enables cross field validation in the inline editor. Default value is true.

editorEnabled - enables the item inline editor UI. Default value is false. If dataGrid is bound to KeyValueCollectionContainer, it is supposed to be read-only, and editorEnabled attribute becomes nonsense.

editorSaveCaption - sets the caption on the save button in the DataGrid inline editor.

frozenColumnCount - sets the number of fixed DataGrid columns. The 0 value means that no columns will be fixed except the predefined column with checkboxes for multiple choice if the multiselect mode is used. The -1 value makes even multiselect column not fixed.

headerVisible - defines if the DataGrid header is visible. The default value is true.

htmlSanitizerEnabled - enables or disables HTML sanitization. The DataGrid component has some providers that can render HTML:

reorderingAllowed - defines whether a user can change the columns order by dragging them with a mouse. The default value is true.

selectionMode - sets the rows selection mode. There are 4 predefined selection modes:

sortable - enables or disables the DataGrid sorting. The default value is true. When the sorting is enabled, the click on the column name will display the sorting icon to the right of the column caption. Sorting of any specific column can be disabled by this column’s sortable attribute.

textSelectionEnabled - enables or disables text selection in the DataGrid cells. The default value is false.

getColumns() - returns the current set of DataGrid columns in their current display order.

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 SelectionMode.SINGLE is set, it is more convenient to use getSingleSelected() method returning one selected entity or null, if nothing is selected.

getVisibleColumns() - returns the current set of visible DataGrid columns in their current display order.

scrollTo() - method allows you to scroll the DataGrid to the specified row. It takes an entity instance identifying the row as a parameter. Besides the entity instance, an overloaded method can take a ScrollDestination parameter with the following possible values:

scrollToStart() and scrollToEnd() - scroll the DataGrid to the top and to the end respectively.

addCellStyleProvider() - adds style provider for the DataGrid cells.

addRowStyleProvider() - adds style provider for the DataGrid rows.

setEnterPressAction() - method 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:

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:

sort() - sorts the data for the specified column in the sort direction chosen from 2 values of the SortDirection enum:

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

setDescriptionProvider() method is used to generate optional descriptions (tooltips) for the cells of individual DataGrid columns. The description may contain HTML markup.

@Inject
private DataGrid<Customer> customersDataGrid;

@Subscribe
protected void onInit(InitEvent event) {
    customersDataGrid.getColumnNN("age").setDescriptionProvider(customer ->
                    getPropertyCaption(customer, "age") +
                            customer.getAge(),
            ContentMode.HTML);

    customersDataGrid.getColumnNN("active").setDescriptionProvider(customer ->
                    getPropertyCaption(customer, "active") +
                            getMessage(customer.getActive() ? "trueString" : "falseString"),
            ContentMode.HTML);

    customersDataGrid.getColumnNN("grade").setDescriptionProvider(customer ->
                    getPropertyCaption(customer, "grade") +
                            messages.getMessage(customer.getGrade()),
            ContentMode.HTML);
}

setRowDescriptionProvider() method is used to generate optional descriptions (tooltips) for DataGrid rows. If a column description provider is also set, the row description generated by provider is used for cells for which the cell description provider returns null.

customersDataGrid.setRowDescriptionProvider(Instance::getInstanceName);

getEditedItem() - returns the item that is currently being edited.

isEditorActive() - returns whether an item is currently being edited in the editor.

editItem(Object itemId) (Deprecated) - opens the editor interface for the provided item id. Scrolls the Grid to bring the item to view if it is not already visible.

edit(Entity item) - opens the editor interface for the provided item. Scrolls the Grid to bring the item to view if it is not already visible.

setEditorCrossFieldValidate(boolean validate) - enables or disables the cross field validation in the inline editor. The default value is true.

isEditorCrossFieldValidate() - return true if the inline editor validates cross field rules.

addEditorOpenListener(), removeEditorOpenListener() - DataGrid editor open listener.

customersTable.addEditorOpenListener(editorOpenEvent -> {
    Map<String, Field> fieldMap = editorOpenEvent.getFields();
    Field active = fieldMap.get("active");
    Field grade = fieldMap.get("grade");

    ValueChangeListener listener = e ->
            active.setValue(true);
    grade.addValueChangeListener(listener);
});

addEditorCloseListener(), removeEditorCloseListener() - DataGrid editor close listener.

addEditorPreCommitListener(), removeEditorPreCommitListener() - DataGrid editor pre commit listener.

addEditorPostCommitListener(), removeEditorPostCommitListener() - DataGrid editor post commit listener.

Declaratively using the @Install annotation in the screen controller:

@Inject
private UiComponents uiComponents;

@Install(to = "dataGrid.fullName", subject = "columnGenerator")
protected Component fullNameColumnGenerator(DataGrid.ColumnGeneratorEvent<Customer> e) {
    Label<String> label = uiComponents.create(Label.TYPE_STRING);
    label.setValue(e.getItem().getFirstName() + " " + e.getItem().getLastName());
    return label;
}

Programmatically with the help of the methods:

• addGeneratedColumn(String columnId, ColumnGenerator generator)

• addGeneratedColumn(String columnId, ColumnGenerator generator, int index)

ColumnGenerator is a special interface that defines the generated, or calculated, column:

• value of each column’s row,

• the type of value - common for the whole column.

Below is an example of generating a column that displays users' login in the upper case:

@Subscribe
protected void onInit(InitEvent event) {
    DataGrid.Column column = usersGrid.addGeneratedColumn("loginUpperCase", new DataGrid.ColumnGenerator<User, String>(){
        @Override
        public String getValue(DataGrid.ColumnGeneratorEvent<User> event){
            return event.getItem().getLogin().toUpperCase();
        }

        @Override
        public Class<String> getType(){
            return String.class;
        }
    }, 1);
    column.setCaption("Login Upper Case");
}

The result:

By default, the generated column is added to the end of the table. There are two possible ways to manage the column’s position: either using an index in the code or adding a column in advance in the XML descriptor and pass its id to the addGeneratedColumn method.

ButtonRenderer – displays string values as a button caption.

@Inject
private DataGrid<Customer> customersDataGrid;

@Inject
private Notifications notifications;

@Subscribe
public void onInit(InitEvent event) {
    DataGrid.ButtonRenderer<Customer> customersDataGridNameRenderer =
                customersDataGrid.createRenderer(DataGrid.ButtonRenderer.class);
    customersDataGridNameRenderer.setRendererClickListener(clickableButtonRendererClickEvent ->
        {
            notifications.create()
                .withType(Notifications.NotificationType.TRAY)
                .withCaption("ButtonRenderer")
                .withDescription("Column id: " + clickableButtonRendererClickEvent.getColumnId())
                .show();
        });
    customersDataGrid.getColumn("name").setRenderer(customersDataGridNameRenderer);
}

CheckBoxRenderer – displays boolean values as a checkbox icon.

<column property="checkBoxRenderer" id="checkBoxRendererColumn">
    <checkBoxRenderer/>
</column>

ClickableTextRenderer – displays simple plain-text string values as a link with call back handler.

@Inject
private DataGrid<Customer> customersDataGrid;

@Inject
private Notifications notifications;

@Subscribe
public void onInit(InitEvent event) {
    DataGrid.ClickableTextRenderer<Customer> customersDataGridNameRenderer =
                customersDataGrid.createRenderer(DataGrid.ClickableTextRenderer.class);
    customersDataGridNameRenderer.setRendererClickListener(clickableTextRendererClickEvent -> {
        notifications.create()
                .withType(Notifications.NotificationType.TRAY)
                .withCaption("ClickableTextRenderer")
                .withDescription("Column id: " + clickableTextRendererClickEvent.getColumnId())
                .show();
    });
    customersDataGrid.getColumn("name").setRenderer(customersDataGridNameRenderer);
}

ComponentRenderer – a renderer for UI components.

<column property="componentRenderer" id="componentRendererColumn">
    <componentRenderer/>
</column>

DateRenderer – displays dates in the defined format.

<column property="dateRenderer" id="dateRendererColumn">
    <dateRenderer nullRepresentation="null" format="yyyy-MM-dd HH:mm:ss"/>
</column>

IconRenderer – a renderer that represents CubaIcon.

<column id="iconOS" property="iconOS">
    <iconRenderer/>
</column>

@Install(to = "devicesTable.iconOS", subject = "columnGenerator")
private Icons.Icon devicesTableIconOSColumnGenerator(DataGrid.ColumnGeneratorEvent<Device> event) {
    return CubaIcon.valueOf(event.getItem().getIconOS());
}

ImageRenderer – uses the path to an image to display the image.

@Inject
private DataGrid<TestEntity> testEntitiesDataGrid;
@Inject
private Notifications notifications;

@Subscribe
public void onInit(InitEvent event) {
    DataGrid.ImageRenderer<TestEntity> imageRenderer =
            testEntitiesDataGrid.createRenderer(DataGrid.ImageRenderer.class);
    imageRenderer.setRendererClickListener(imageRendererClickEvent -> notifications.create()
            .withType(Notifications.NotificationType.TRAY)
            .withCaption("ImageRenderer")
            .withDescription("Column id: " + imageRendererClickEvent.getColumnId())
            .show());
    testEntitiesDataGrid.getColumn("imageRendererColumn").setRenderer(imageRenderer);
}

HtmlRenderer – displays HTML layout.

<column property="htmlRenderer" id="htmlRendererColumn">
    <htmlRenderer nullRepresentation="null"/>
</column>

LocalDateRenderer – displays dates as LocalDate values.

<column property="localDateRenderer" id="localDateRendererColumn">
    <localDateRenderer nullRepresentation="null" format="dd/MM/YYYY"/>
</column>

LocalDateTimeRenderer – displays dates as LocalDateTime values.

<column property="localDateTimeRenderer" id="localDateTimeRendererColumn">
    <localDateTimeRenderer nullRepresentation="null" format="dd/MM/YYYY HH:mm:ss"/>
</column>

NumberRenderer – displays numbers in the defined format.

<column property="numberRenderer" id="numberRendererColumn">
    <numberRenderer nullRepresentation="null" format="%f"/>
</column>

ProgressBarRenderer – displays double values between 0 and 1 as a ProgressBar component.

<column property="progressBar" id="progressBarColumn">
    <progressBarRenderer/>
</column>

TextRenderer – displays plain text.

<column property="textRenderer" id="textRendererColumn">
    <textRenderer nullRepresentation="null"/>
</column>

declaratively using the special elements of the column element of DataGrid.

passing a renderer interface to the fabric method of the DataGrid interface. Suits for GUI and Web modules.

directly creating a renderer implementation for the corresponding module:

appendHeaderRow(), appendFooterRow() - adds a new row at the bottom of the header/footer section.

prependHeaderRow(), prependFooterRow() - adds a new row at the top of the header/footer section.

addHeaderRowAt(), addFooterRowAt() - inserts a new row at the given position to the header/footer section. Shifts the row currently at that position and any subsequent rows down incrementing their indices.

removeHeaderRow(), removeFooterRow() - removes the given row from the header/footer section.

getHeaderRowCount(), getFooterRowCount() - gets the row count for the header/footer section.

setDefaultHeaderRow() - sets the default row of the header. The default row is a special header row providing a user interface for sorting columns.

setStyleName() - sets a custom style name for this cell.

getCellType() - returns the type of content stored in this cell. There are 3 types of DataGridStaticCellType enumeration available:

getComponent(), getHtml(), getText() - returns the content displayed in this cell depending on its type.

borderless - removes the outer border of the DataGrid.

no-horizontal-lines - removes the horizontal divider lines between the DataGrid rows.

no-vertical-lines - removes the vertical divider lines between the DataGrid columns.

no-stripes - removes the alternating row colors.