| title | order | layout |
|---|---|---|
Grid |
24 |
page |
Grid is for displaying and editing tabular data laid out in rows and columns. At the top, a header can be shown, and a footer at the bottom. In addition to plain text, the header and footer can contain HTML and components. Having components in the header allows implementing filtering easily. The grid data can be sorted by clicking on a column header; shift-clicking a column header enables secondary sorting criteria.
The data area can be scrolled both vertically and horizontally. The leftmost columns can be frozen, so that they are never scrolled out of the view. The data is loaded lazily from the server, so that only the visible data is loaded. The smart lazy loading functionality gives excellent user experience even with low bandwidth, such as mobile devices.
The grid data can be edited with a row-based editor after double-clicking a row. The fields are set explicitly, and bound to data.
Grid is fully themeable with CSS and style names can be set for all grid elements. For data rows and cells, the styles can be generated with a row or cell style generator.
Grid is normally used by binding it to a , described in "Showing Many Items in a Listing". By default, it is bound to List of items. You can set the items with the setItems() method.
For example, if you have a list of beans, you show them in a Grid as follows
// Have some data
List<Person> people = Lists.newArrayList(
new Person("Nicolaus Copernicus", 1543),
new Person("Galileo Galilei", 1564),
new Person("Johannes Kepler", 1571));
// Create a grid bound to the list
Grid<Person> grid = new Grid<>();
grid.setItems(people);
grid.addColumn(Person::getName).setCaption("Name");
grid.addColumn(Person::getBirthYear).setCaption("Year of birth");
layout.addComponent(grid);Selection in Grid is handled a bit differently from other selection components, as it is not a HasValue. Grid supports single, multiple, or no-selection, each defined by a specific selection model. Each selection model has a specific API depending on the type of the selection.
For basic usage, switching between the built-in selection models is possible by using the setSelectionMode(SelectionMode). Possible options are SINGLE (default), MULTI, or NONE.
Listening to selection changes in any selection model is possible with a SelectionListener, which provides a generic SelectionEvent which for getting the selected value or values. Note that the listener is actually attached to the selection model and not the grid, and will stop getting any events if the selection mode is changed.
Grid<Person> grid = new Grid<>();
// switch to multiselect mode
grid.setSelectionMode(SelectionMode.MULTI);
grid.addSelectionListener(event -> {
Set<Person> selected = event.getAllSelectedItems();
Notification.show(selected.size() + " items selected");
}Programmatically selecting the value is possible via select(T). In multiselect mode, this will add the given item to the selection.
// in single-select, only one item is selected
grid.select(defaultPerson);
// switch to multi select, clears selection
grid.setSelectionMode(SelectionMode.MULTI);
// Select items 2-4
people.subList(2,3).forEach(grid::select);The current selection can be obtained from the Grid by getSelectedItems(), and the returned Set contains either only one item (in single-selection mode) or several items (in multi-selection mode).
|
Warning
|
If you change selection mode for a grid, it will clear the selection and fire a selection event. To keep the previous selection you must reset the selection afterwards using the select() method. |
|
Warning
|
If you change the grid’s items with setItems() or the used DataProvider, it will clear the selection and fire a selection event. To keep the previous selection you must reset the selection afterwards using the select() method. |
For more control over the selection, you can access the used selection model with getSelectionModel(). The return type is GridSelectionModel which has generic selection model API, but you can cast that to the specific selection model type, typically either SingleSelectionModel or MultiSelectionModel.
The selection model is also returned by the setSelectionMode(SelectionMode) method.
// the default selection model
SingleSelectionModel<Person> defaultModel =
(SingleSelectionModel<Person>) grid.getSelectionModel();
// Use multi-selection mode
MultiSelectionModel<Person> selectionModel =
(MultiSelectionModel<Person>) grid.setSelectionMode(SelectionMode.MULTI);By obtaining a reference to the SingleSelectionModel, you can access more fine grained API for the single-select case.
The addSingleSelect(SingleSelectionListener) method provides access to SingleSelectionEvent, which has some extra API for more convenience.
In single-select mode, it is possible to control whether the empty (null) selection is allowed. By default it is enabled, but can be disabled with setDeselectAllowed().
// preselect value
grid.select(defaultItem);
SingleSelectionModel<Person> singleSelect =
(SingleSelectionModel<Person>) grid.getSelectionModel();
// disallow empty selection
singleSelect.setDeselectAllowed(false);In the multi-selection mode, a user can select multiple items by clicking on the checkboxes in the leftmost column, or by using the kbd:[Space] to select/deselect the currently focused row. Space bar is the default key for toggling the selection, but it can be customized.
By obtaining a reference to the MultiSelectionModel, you can access more fine grained API for the multi-select case.
The MultiSelectionModel provides addMultiSelectionListener(MultiSelectionListener) access to MultiSelectionEvent, which allows to easily access differences in the selection change.
// Grid in multi-selection mode
Grid<Person> grid = Grid<>()
grid.setItems(people);
MultiSelectionModel<Person> selectionModel
= (MultiSelectionModel<Person>) grid.setSelectionMode(SelectionMode.MULTI);
selectionModel.selectAll();
selectionModel.addMultiSelectionListener(event -> {
Notification.show(selection.getAddedSelection().size()
+ " items added, "
+ selection.getRemovedSelection().size()
+ " removed.");
// Allow deleting only if there's any selected
deleteSelected.setEnabled(
event.getNewSelection().size() > 0);
};In addition to selecting rows, you can focus individual cells. The focus can be moved with arrow keys and, if editing is enabled, pressing kbd:[Enter] opens the editor. Normally, pressing kbd:[Tab] or kbd:[Shift+Tab] moves the focus to another component, as usual.
When editing or in unbuffered mode, kbd:[Tab] or kbd:[Shift+Tab] moves the focus to the next or previous cell. The focus moves from the last cell of a row forward to the beginning of the next row, and likewise, from the first cell backward to the end of the previous row. Note that you can extend DefaultEditorEventHandler to change this behavior.
With the mouse, you can focus a cell by clicking on it. The clicks can be handled with an ItemClickListener. The ItemClickEvent object contains various information, most importantly the ID of the clicked row and column.
grid.addCellClickListener(event ->
Notification.show("Value: " + event.getItem());The clicked grid cell is also automatically focused.
The focus indication is themed so that the focused cell has a visible focus indicator style by default, while the row does not. You can enable row focus, as well as disable cell focus, in a custom theme. See Styling with CSS.
Columns are normally defined in the container data source. The addColumn() method can be used to add columns to Grid.
Column configuration is defined in Grid.Column objects, which can be obtained from the grid with getColumns().
The setter methods in Column have fluent API, so you can easily chain the configuration calls for columns if you want to.
grid.addColumn(Person:getBirthDate, new DateRenderer())
.setCaption("Birth Date")
.setWidth("100px")
.setResizable(false);In the following, we describe the basic column configuration.
You can set the order of columns with setColumnOrder() for the grid. Columns that are not given for the method are placed after the specified columns in their natural order.
grid.setColumnOrder(firstnameColumn, lastnameColumn,
bornColumn, birthplaceColumn,
diedColumn);Note that the method can not be used to hide columns. You can hide columns with the removeColumn(), as described later.
Columns can be hidden by calling setHidden() in Column. Furthermore, you can set the columns user hideable using method setHideable().
Columns can be removed with removeColumn() and removeAllColumns(). To restore a previously removed column, you can call addColumn().
Column captions are displayed in the grid header. You can set the header caption explicitly through the column object with setCaption().
Column<Date> bornColumn = grid.addColumn(Person:getBirthDate);
bornColumn.setCaption("Born date");This is equivalent to setting it with setText() for the header cell; the HeaderCell also allows setting the caption in HTML or as a component, as well as styling it, as described later in Header and Footer.
Columns have by default undefined width, which causes automatic sizing based on the widths of the displayed data. You can set column widths explicitly by pixel value with setWidth(), or relatively using expand ratios with setExpandRatio().
When using expand ratios, the columns with a non-zero expand ratio use the extra space remaining from other columns, in proportion to the defined ratios.
You can specify minimum and maximum widths for the expanding columns with setMinimumWidth() and setMaximumWidth(), respectively.
The user can resize columns by dragging their separators with the mouse. When resized manually, all the columns widths are set to explicit pixel values, even if they had relative values before.
You can set the number of columns to be frozen with setFrozenColumnCount(), so that they are not scrolled off when scrolling horizontally.
grid.setFrozenColumnCount(2);Setting the count to 0 disables frozen data columns; setting it to -1 also disables the selection column in multi-selection mode.
Columns with values computed from other columns can be simply added by using lambdas:
// Add generated full name column
Column<String> fullNameColumn = grid.addColumn(person ->
person.getFirstName() + " " + person.getLastName());
fullNameColumn.setCaption("Full name");A renderer is a feature that draws the client-side representation of a data value. This allows having images, HTML, and buttons in grid cells.
Renderers implement the Renderer interface. Renderers require a specific data type for the column. You set the column renderer in the Grid.Column object as follows:
// the type of birthYear is a number
Column<Integer> bornColumn = grid.addColumn(Person:getBirthYear,
new NumberRenderer("born in %d AD"));The following renderers are available, as defined in the server-side com.vaadin.ui.renderers package:
- TextRenderer
-
The default renderer, displays plain text as is. Any HTML markup is quoted.
- ButtonRenderer
-
Renders the data value as the caption of a button. A RendererClickListener can be given to handle the button clicks.
Typically, a button renderer is used to display buttons for operating on a data item, such as edit, view, delete, etc. It is not meaningful to store the button captions in the data source, rather you want to generate them, and they are usually all identical.
List<Person> people = new ArrayList<>(); people.add(new Person("Nicolaus Copernicus", 1473)); people.add(new Person("Galileo Galilei", 1564)); people.add(new Person("Johannes Kepler", 1571)); // Create a grid Grid<Person> grid = new Grid<>(people); // Render a button that deletes the data row (item) grid.addColumn(person -> "Delete", new ButtonRenderer(clickEvent -> { people.remove(clickEvent.getValue()); grid.setItems(people); });
- ImageRenderer
-
Renders the cell as an image. The column type must be a Resource, as described in "Images and Other Resources"; only ThemeResource and ExternalResource are currently supported for images in Grid.
Column<ThemeResource> imageColumn = grid.addColumn( p -> new ThemeResource("img/"+p.getLastname()+".jpg"), new ImageRenderer());
- DateRenderer
-
Formats a column with a Date type using string formatter. The format string is same as for String.format() in Java API. The date is passed in the parameter index 1, which can be omitted if there is only one format specifier, such as "%tF".
Grid.Column<Date> bornColumn = grid.addColumn(person:getBirthDate, new DateRenderer("%1$tB %1$te, %1$tY", Locale.ENGLISH));
Optionally, a locale can be given. Otherwise, the default locale (in the component tree) is used.
- HTMLRenderer
-
Renders the cell as HTML. This allows formatting the cell content, as well as using HTML features such as hyperlinks.
Set the renderer in the Grid.Column object:
Column<String> htmlColumn grid.addColumn(person -> "<a href='" + person.getDetailsUrl() + "' target='_top'>info</a>", new HtmlRenderer());
- NumberRenderer
-
Formats column values with a numeric type extending Number: Integer, Double, etc. The format can be specified either by the subclasses of java.text.NumberFormat, namely DecimalFormat and ChoiceFormat, or by String.format().
For example:
// Use decimal format Column<Integer> birthYear = grid.addColumn(Person::getBirthYear, new NumberRenderer(new DecimalFormat("in #### AD")));
- ProgressBarRenderer
-
Renders a progress bar in a column with a Double type. The value must be between 0.0 and 1.0.
Renderers are component extensions that require a client-side counterpart. See "Renderers" for information on implementing custom renderers.
A grid by default has a header, which displays column names, and can have a footer. Both can have multiple rows and neighbouring header row cells can be joined to feature column groups.
A new header row is added with prependHeaderRow(), which adds it at the top of the header, appendHeaderRow(), which adds it at the bottom of the header, or with addHeaderRowAt(), which inserts it at the specified 0-base index. All of the methods return a HeaderRow object, which you can use to work on the header further.
// Group headers by joining the cells
HeaderRow groupingHeader = grid.prependHeaderRow();
...
// Create a header row to hold column filters
HeaderRow filterRow = grid.appendHeaderRow();
...Similarly, you can add footer rows with appendFooterRow(), prependFooterRow(), and addFooterRowAt().
You can join two or more header or footer cells with the join() method. For header cells, the intention is usually to create column grouping, while for footer cells, you typically calculate sums or averages.
// Group headers by joining the cells
HeaderRow groupingHeader = grid.prependHeaderRow();
HeaderCell namesCell = groupingHeader.join(
groupingHeader.getCell("firstname"),
groupingHeader.getCell("lastname")).setText("Person");
HeaderCell yearsCell = groupingHeader.join(
groupingHeader.getCell("born"),
groupingHeader.getCell("died"),
groupingHeader.getCell("lived")).setText("Dates of Life");You can set the header caption with setText(), in which case any HTML formatting characters are quoted to ensure security.
HeaderRow mainHeader = grid.getDefaultHeaderRow();
mainHeader.getCell("firstname").setText("First Name");
mainHeader.getCell("lastname").setText("Last Name");
mainHeader.getCell("born").setText("Born In");
mainHeader.getCell("died").setText("Died In");
mainHeader.getCell("lived").setText("Lived For");To use raw HTML in the captions, you can use setHtml().
namesCell.setHtml("<b>Names</b>");
yearsCell.setHtml("<b>Years</b>");A user can sort the data in a grid on a column by clicking the column header. Clicking another time on the current sort column reverses the sort direction. Clicking on other column headers while keeping the Shift key pressed adds a secondary or more sort criteria.
Defining sort criteria programmatically can be done with the various alternatives of the sort() method. You can sort on a specific column with sort(Column column), which defaults to ascending sorting order, or sort(Column column, SortDirection direction), which allows specifying the sort direction.
grid.sort(nameColumn, SortDirection.DESCENDING);To sort on multiple columns, you need to use the fluid sort API with sort(Sort), which allows chaining sorting rules. Sorting rules are created with the static by() method, which defines the primary sort column, and then(), which can be used to specify any secondary sort columns. They default to ascending sort order, but the sort direction can be given with an optional parameter.
// Sort first by city and then by name
grid.sort(Sort.by(cityColumn, SortDirection.ASCENDING)
.then(nameColumn, SortDirection.DESCENDING));Grid supports line-based editing, where double-clicking a row opens the row editor. In the editor, the input fields can be edited, as well as navigated with kbd:[Tab] and kbd:[Shift+Tab] keys. If validation fails, an error is displayed and the user can correct the inputs.
The Editor is accessible via getEditor(), and to enable editing, you need to call [methodname]#setEnabled(true) on it.
The editor is based on Binder which is used to bind the data to the editor. See "Binding Beans to Forms" for more information on setting up field components and validation by using Binder. The [classname]#Binder needs to be set with setBinder in Editor.
List<Todo> items = Arrays.asList(new Todo("Done task", true),
new Todo("Not done", false));
Grid<Todo> grid = new Grid<>();
TextField taskField = new TextField();
CheckBox doneField = new CheckBox();
Binder<Todo> binder = new Binder<>();
binder.bind(taskField, Todo::getTask, Todo::setTask);
binder.bind(doneField, Todo::isDone, Todo::setDone);
grid.getEditor().setBinder(binder);
grid.getEditor().setEnabled(true);
Column<Todo, String> column = grid
.addColumn(todo -> String.valueOf(todo.isDone()));
column.setWidth(75);
column.setEditorComponent(doneField);
grid.addColumn(Todo::getTask).setEditorComponent(taskField);It is possible to customize the used editor component for each column and row, by using setEditorComponentGenerator(EditorComponentGenerator) in Column.
Grid supports two editor modes - buffered and unbuffered. The default mode is buffered. The mode can be changed with setBuffered(false).
In the buffered mode, editor has two buttons visible: a Save button that commits the modifications to the bean and closes the editor and a Cancel button discards the changes and exits the editor.
Editor in buffered mode is illustrated in Editing a Grid Row.
In the unbuffered mode, the editor has no buttons and all changed data is committed directly to the data provider. If another row is clicked, the editor for the current row is closed and a row editor for the clicked row is opened.
In the buffered mode, the editor has two buttons: Save and Cancel. You can set their captions with setEditorSaveCaption() and setEditorCancelCaption(), respectively.
In the following example, we demonstrate one way to translate the captions:
// Localize the editor button captions
grid.getEditor().setSaveCaption("Tallenna");
grid.getEditor().setCancelCaption("Peruuta"));The input fields are validated when the value is updated. The default error handler displays error indicators in the invalid fields, as well as the first error in the editor.
You can modify the error message by implementing a custom EditorErrorGenerator with for the Editor.
You can style entire rows or individual cells with a StyleGenerator, typically used through Java lambdas.
You set a StyleGenerator to a grid with setStyleGenerator(). The getStyle() method gets a date item, and should return a style name or null if no style is generated.
For example, to add a style names to rows having certain values in one property of an item, you can style them as follows:
grid.setStyleGenerator(person -> {
// Style based on alive status
person.isAlive() ? null : "dead";
});You could then style the rows with CSS as follows:
.v-grid-row.dead {
color: gray;
}You set a StyleGenerator to a grid with setStyleGenerator(). The getStyle() method gets a CellReference, which contains various information about the cell and a reference to the grid, and should return a style name or null if no style is generated.
For example, to add a style name to a specific column, you can match on the column as follows:
// Static style based on column
bornColumn.setStyleGenerator(person -> "rightalign");You could then style the cells with a CSS rule as follows:
.v-grid-cell.rightalign {
text-align: right;
}.v-grid {
.v-grid-scroller, .v-grid-scroller-horizontal { }
.v-grid-tablewrapper {
.v-grid-header {
.v-grid-row {
.v-grid-cell, .frozen, .v-grid-cell-focused { }
}
}
.v-grid-body {
.v-grid-row,
.v-grid-row-stripe,
.v-grid-row-has-data {
.v-grid-cell, .frozen, .v-grid-cell-focused { }
}
}
.v-grid-footer {
.v-grid-row {
.v-grid-cell, .frozen, .v-grid-cell-focused { }
}
}
}
.v-grid-header-deco { }
.v-grid-footer-deco { }
.v-grid-horizontal-scrollbar-deco { }
.v-grid-editor {
.v-grid-editor-cells { }
.v-grid-editor-footer {
.v-grid-editor-message { }
.v-grid-editor-buttons {
.v-grid-editor-save { }
.v-grid-editor-cancel { }
}
}
}
}A Grid has an overall v-grid style. The actual grid has three parts: a header, a body, and a footer. The scrollbar is a custom element with v-grid-scroller style. In addition, there are some decoration elements.
Grid cells, whether thay are in the header, body, or footer, have a basic v-grid-cell style. Cells in a frozen column additionally have a frozen style. Rows have v-grid-row style, and every other row has additionally a v-grid-row-stripe style.
The focused row has additionally v-grid-row-focused style and focused cell v-grid-cell-focused. By default, cell focus is visible, with the border stylable with $v-grid-cell-focused-border parameter in Sass. Row focus has no visible styling, but can be made visible with the $v-grid-row-focused-background-color parameter or with a custom style rule.
In editing mode, a v-grid-editor overlay is placed on the row under editing. In addition to the editor field cells, it has an error message element, as well as the buttons.