Grid

    Grid is many things, and perhaps the most versatile and powerful component in Vaadin. Like Table, it allows presenting and editing tabular data, but escapes many of Table’s limitations. Efficient lazy loading of data while scrolling greatly improves performance. Grid is scalable, mobile friendly, and extensible.

    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.

    A Grid

    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 generated with a field factory, or set explicitly, and bound to data with a field group.

    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.

    Finally, Grid is designed to be extensible and used just as well for client-side development - its GWT API is nearly identical to the server-side API, including data binding.

    In addition to core features listed above, Grid has the following API-level and functional differences to Table:

    • Grid is not a Container itself, even though it can be bound to a container data source. Consequently, columns are defined differently, and so forth.

    • Rows can be added with addRow() shorthand (during initialization) instead of addItem().

    • Use setHeightByRows() and setHeightMode() instead of setPageLength() to set the height in number of rows.

    • Grid does not extend AbstractSelect and is not a field, but has its own selection API. addSelectionListener() is called to define a SelectionListener. The listener also receives a collection of deselected items.

    • Grid does not support having all cells in editable mode, it only supports row-based editing, with a row mini-editor that allows saving or discarding the changes.

    • Grid has no generated columns. Instead, the container data source can be wrapped around a GeneratedPropertyContainer.

    • No column icons; you can implement them in a column with an ImageRenderer.

    • Components can not be shown in Grid cells; instead the much more efficient renderers can be used for the most common cases, and row editor for editing values.

    • Limited support for drag and drop: the user can drag columns to reorder them.

    In addition, Grid has the following visual changes:

    • Multiple selection is indicated with check boxes in addition to highlighting.

    • Grid does not show the row loading indicator like Table does.

    Binding to Data

    Grid is normally used by binding it to a container data source, described in . The container must implement Container.Indexed interface. By default, it is bound to an IndexedContainer; Grid offers some shorthand methods to operate on the default container, as described later.

    You can set the container in the constructor or with setContainerDataSource().

    For example, if you have a collection of beans, you could wrap them in a Vaadin BeanContainer or BeanItemContainer, and bind to a Grid as follows

    Java

    Note that you need to override equals() and hashcode() for the bean (Person) class to make the BeanItemContainer work properly.

    Default Data Source and Shorthands

    Sometimes, when you have just a few fixed items that you want to display, you can define the grid columns and add data rows manually. Grid is by default bound to a IndexedContainer. You can define new columns (container properties) with addColumn() and then add rows (items) with addRow(). The types in the row data must match the defined column types.

    For example:

    Java

    2. Grid grid = new Grid();
    4. // Define some columns
    5. grid.addColumn("name", String.class);
    6. grid.addColumn("born", Integer.class);
    8. // Add some data rows
    9. grid.addRow("Nicolaus Copernicus", 1543);
    10. grid.addRow("Galileo Galilei", 1564);
    11. grid.addRow("Johannes Kepler", 1571);
    13. layout.addComponent(grid);

    Or, if you have the data in an array:

    Java

    1. // Have some data
    2. Object[][] people = { {"Nicolaus Copernicus", 1543},
    3.                       {"Galileo Galilei", 1564},
    4.                       {"Johannes Kepler", 1571}};
    5. for (Object[] person: people)
    6.     grid.addRow(person);

    Note that you can not use addRow() to add items if the container is read-only or has read-only columns, such as generated columns.

    Handling Selection Changes

    Selection in Grid is handled a bit differently from other selection components, as it is not an AbstractSelect. Grid supports both single and multiple selection, defined by the selection mode. Selection events can be handled with a SelectionListener.

    Selection Mode

    A Grid can be set to be in SINGLE (default), MULTI, or NONE selection mode, defined in the Grid.SelectionMode enum.

    Java

    1. // Use single-selection mode (default)
    2. grid.setSelectionMode(SelectionMode.SINGLE);

    Empty (null) selection is allowed by default, but can be disabled with setDeselectAllowed() in single-selection mode.

    The selection is handled with a different selection model object in each respective selection mode: SingleSelectionModel, MultiSelectionModel, and NoSelectionModel (in which selection is always empty).

    Java

    1. // Pre-select an item
    2. SingleSelectionModel selection =
    3.     (SingleSelectionModel) grid.getSelectionModel();
    4. selection.select( // Select 3rd item
    5.     grid.getContainerDataSource().getIdByIndex(2));

    Handling Selection

    Changes in the selection can be handled with a SelectionListener. You need to implement the select() method, which gets a SelectionEvent as parameter. In addition to selection, you can handle clicks on rows or cells with a ItemClickListener.

    You can get the new selection from the selection event with getSelected(), which returns a set of item IDs, or more simply from the grid or the selection model with getSelectedRow(), which returns the single selected item ID.

    For example:

    Java

    1. grid.addSelectionListener(selectionEvent -> { // Java 8
    2.     // Get selection from the selection model
    3.     Object selected = ((SingleSelectionModel)
    4.         grid.getSelectionModel()).getSelectedRow();
    6.     if (selected != null)
    7.         Notification.show("Selected " +
    8.             grid.getContainerDataSource().getItem(selected)
    9.                 .getItemProperty("name"));
    10.     else
    11.         Notification.show("Nothing selected");
    12. });

    The current selection can be obtained from the Grid object by getSelectedRow() or getSelectedRows(), which return one (in single-selection mode) or all (in multi-selection mode) selected items.

    Multiple Selection

    In the multiple selection mode, a user can select multiple items by clicking on the checkboxes in the leftmost column, or by using the Space to select/deselect the currently focused row. Space bar is the default key for toggling the selection, but it can be customized.

    grid selection multi

    Multiple Selection in Grid

    The selection is managed through the MultiSelectionMode class. The currently selected rows can be set with setSelected() by a collection of item IDs, or you can use select() to add items to the selection.

    Java

    1. // Grid in multi-selection mode
    2. Grid grid = new Grid(exampleDataSource());
    3. grid.setSelectionMode(SelectionMode.MULTI);
    5. // Pre-select some items
    6. MultiSelectionModel selection =
    7.     (MultiSelectionModel) grid.getSelectionModel();
    8. selection.setSelected( // Items 2-4
    9.     grid.getContainerDataSource().getItemIds(2, 3));

    The current selection can be read with getSelectedRows(); either in the MultiSelectionMode object or in the Grid.

    Java

    1. // Allow deleting the selected items
    2. Button delSelected = new Button("Delete Selected", e -> {
    3.     // Delete all selected data items
    4.     for (Object itemId: selection.getSelectedRows())
    5.         grid.getContainerDataSource().removeItem(itemId);
    7.     // Otherwise out of sync with container
    8.     grid.getSelectionModel().reset();
    10.     // Disable after deleting
    11.     e.getButton().setEnabled(false);
    12. });
    13. delSelected.setEnabled(grid.getSelectedRows().size() > 0);

    Changes in the selection can be handled with a SelectionListener. The selection event object provides getAdded() and getRemoved() to allow determining the differences in the selection change.

    Java

    1. // Handle selection changes
    2. grid.addSelectionListener(selection -> { // Java 8
    3.     Notification.show(selection.getAdded().size() +
    4.                       " items added, " +
    5.                       selection.getRemoved().size() +
    6.                       " removed.");
    8.     // Allow deleting only if there's any selected
    9.     deleteSelected.setEnabled(
    10.          grid.getSelectedRows().size() > 0);
    11. });

    Disallowing User Selection

    It is possible to prevent the user from changing the selection in grid for both single- and multi-selection models:

    Java

    1. HasUserSelectionAllowed model = (HasUserSelectionAllowed) grid.getSelectionModel();
    2. model.setUserSelectionAllowed(false);
    Note
    		Both SingleSelectionModel and MultiSelectModel implement HasUserSelectionAllowed so the cast is generally safe.

    Focus and Clicks

    In addition to selecting rows, you can focus individual cells. The focus can be moved with arrow keys and, if editing is enabled, pressing Enter opens the editor. Normally, pressing Tab or Shift+Tab moves the focus to another component, as usual.

    When editing or in unbuffered mode, Tab or 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.

    Java

    1. grid.addItemClickListener(event -> // Java 8
    2.     Notification.show("Value: " +
    3.         container.getContainerProperty(event.getItemId(),
    4.             event.getPropertyId()).getValue().toString()));

    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 doesn’t. You can enable row focus, as well as disable cell focus, in a custom theme. See .

    Configuring Columns

    Columns are normally defined in the container data source. The addColumn() method can be used to add columns to a container that supports it, such as the default IndexedContainer.

    Column configuration is defined in Grid.Column objects, which can be obtained from the grid with getColumn() by the column (property) ID.

    Java

    1. Grid.Column bornColumn = grid.getColumn("born");
    2. bornColumn.setHeaderCaption("Born");

    In the following, we describe the basic column configuration.

    Column Order

    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.

    Java

    1. grid.setColumnOrder("firstname", "lastname", "born",
    2.                     "birthplace", "died");

    Hiding Columns

    Columns can be hidden by removing them with removeColumn(). You can remove all columns with removeAllColumns(). The removed columns are only removed from the grid, not from the container data source.

    To restore a previously removed column, you can call addColumn() with the property ID. Instead of actually adding another column to the data source, it merely restores the previously removed one. However, column settings such as header or editor are not restored, but must be redone.

    You can also hide columns at container-level. At least GeneratedpropertyContainer allows doing so, as described in .

    Column captions are displayed in the grid header. The default captions are generated automatically from the property ID. You can set the header caption explicitly through the column object with setHeaderCaption().

    Java

    1. Grid.Column bornColumn = grid.getColumn("born");
    2. bornColumn.setHeaderCaption("Born");

    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.

    Column Widths

    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.

    Frozen Columns

    You can set the number of columns to be frozen with setFrozenColumnCount(), so that they are not scrolled off when scrolling horizontally.

    Java

    1. 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 or in some other way can be generated with a container or data model that generates the property values. The GeneratedPropertyContainer can be used for this purpose. It wraps around any indexed container to extend its properties with read-only generated properties. The generated properties can have same IDs as the original ones, thereby replacing them with formatted or converted values. See for a detailed description of using it.

    Generated columns are read-only, so you can not add grid rows with addRow(). In editable mode, editor fields are not generated for generated columns.

    Note that, while GeneratedPropertyContainer implements Container.Sortable, the wrapped container might not, and also sorting on the generated properties requires special handling. In such cases, generated properties or the entire container might not actually be sortable.

    Column Renderers

    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.

    Column renderers: image, date, HTML, and button

    Renderers implement the Renderer interface. You set the column renderer in the Grid.Column object as follows:

    Java

    Renderers require a specific data type for the column. To convert to a property type to a type required by a renderer, you can pass an optional Converter to setRenderer(), as described later in this section. A converter can also be used to (pre)format the property values. The converter is run on the server-side, before sending the values to the client-side to be rendered with the renderer.

    The following renderers are available, as defined in the server-side com.vaadin.ui.renderers package:

    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.

    Java

    1. BeanItemContainer<Person> people =
    2.     new BeanItemContainer<>(Person.class);
    4. people.addBean(new Person("Nicolaus Copernicus", 1473));
    5. people.addBean(new Person("Galileo Galilei", 1564));
    6. people.addBean(new Person("Johannes Kepler", 1571));
    8. // Generate button caption column
    9. GeneratedPropertyContainer gpc =
    10.     new GeneratedPropertyContainer(people);
    11. gpc.addGeneratedProperty("delete",
    12.     new PropertyValueGenerator<String>() {
    14.     @Override
    15.     public String getValue(Item item, Object itemId,
    16.                            Object propertyId) {
    17.     }
    19.     @Override
    20.     public Class<String> getType() {
    21.         return String.class;
    22.     }
    23. });
    25. // Create a grid
    26. Grid grid = new Grid(gpc);
    28. // Render a button that deletes the data row (item)
    29. grid.getColumn("delete")
    30.     .setRenderer(new ButtonRenderer(e -> // Java 8
    31.     grid.getContainerDataSource()
    32.         .removeItem(e.getItemId())));

    ImageRenderer

    Renders the cell as an image. The column type must be a Resource, as described in ; only ThemeResource and ExternalResource are currently supported for images in Grid.

    Java

    1. grid.addColumn("picture", Resource.class)
    2.     .setRenderer(new ImageRenderer());
    3. ...
    4. // Add some data rows
    5. grid.addRow(new ThemeResource("img/copernicus-128px.jpg"),
    6.             "Nicolaus Copernicus", 1543);
    7. grid.addRow(new ThemeResource("img/galileo-128px.jpg"),
    8.             "Galileo Galilei", 1564);

    Instead of creating the resource objects explicitly, as was done above, you could generate them dynamically from file name strings using a Converter for the column.

    Java

    1. // Define some columns
    2. grid.addColumn("picture", String.class); // Filename
    3. grid.addColumn("name", String.class);
    5. // Set the image renderer
    6. grid.getColumn("picture").setRenderer(new ImageRenderer(),
    7.     new Converter<Resource, String>() {
    8.         @Override
    9.         public String convertToModel(Resource value,
    11.             throws Converter.ConversionException {
    12.             return "not needed";
    13.         }
    15.         @Override
    16.         public Resource convertToPresentation(String value,
    17.             Class<? extends Resource> targetType, Locale l)
    18.             throws Converter.ConversionException {
    19.             return new ThemeResource("img/" + value);
    20.         }
    22.         @Override
    23.         public Class<String> getModelType() {
    24.             return String.class;
    25.         }
    27.         @Override
    28.         public Class<Resource> getPresentationType() {
    29.             return Resource.class;
    30.         }
    31. });
    33. // Add some data rows
    34. grid.addRow("copernicus-128px.jpg", "Nicolaus Copernicus");
    35. grid.addRow("galileo-128px.jpg", "Galileo Galilei");
    36. grid.addRow("kepler-128px.jpg", "Johannes Kepler");

    You also need to define the row heights so that the images fit there. You can set it in the theme for all data cells or for the column containing the images.

    For the latter way, first define a CSS style name for grid and the column:

    Java

    1. grid.setStyleName("gridwithpics128px");
    2. grid.setCellStyleGenerator(cell ->
    3.     "picture".equals(cell.getPropertyId())?
    4.         "imagecol" : null);

    Then, define the style in CSS (Sass):

    CSS

    1. .gridwithpics128px .imagecol {
    2.     height: 128px;
    3.     background: black;
    4.     text-align: center;
    5. }

    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”.

    Java

    1. Grid.Column bornColumn = grid.getColumn("born");
    2. bornColumn.setRenderer(
    3.     new DateRenderer("%1$tB %1$te, %1$tY",
    4.                      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 cell content, as well as using HTML features such as hyperlinks.

    First, set the renderer in the Grid.Column object:

    Java

    1. grid.addColumn("link", String.class)
    2.     .setRenderer(new HtmlRenderer());

    Then, in the grid data, give the cell content:

    Java

    1. grid.addRow("Nicolaus Copernicus", 1543,
    2.             "<a href='http://en.wikipedia.org/wiki/" +
    3.             "Nicolaus_Copernicus' target='_top'>info</a>");

    You could also use a PropertyFormatter or a generated column to generate the HTML for the links.

    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:

    Java

    1. // Define some columns
    2. grid.addColumn("name", String.class);
    3. grid.addColumn("born", Integer.class);
    4. grid.addColumn("sletters", Integer.class);
    5. grid.addColumn("rating", Double.class);
    7. // Use decimal format
    8. grid.getColumn("born").setRenderer(new NumberRenderer(
    9.     new DecimalFormat("in #### AD")));
    11. // Use textual formatting on numeric ranges
    12. grid.getColumn("sletters").setRenderer(new NumberRenderer(
    13.     new ChoiceFormat("0#none|1#one|2#multiple")));
    15. // Use String.format() formatting
    16. grid.getColumn("rating").setRenderer(new NumberRenderer(
    17.     "%02.4f", Locale.ENGLISH));
    19. // Add some data rows
    20. grid.addRow("Nicolaus Copernicus", 1473, 2, 0.4);
    21. grid.addRow("Galileo Galilei",     1564, 0, 4.2);
    22. grid.addRow("Johannes Kepler",     1571, 1, 2.3);

    ProgressBarRenderer

    Renders a progress bar in a column with a Double type. The value must be between 0.0 and 1.0.

    For example:

    Java

    1. // Define some columns
    2. grid.addColumn("name", String.class);
    3. grid.addColumn("rating", Double.class)
    4.     .setRenderer(new ProgressBarRenderer());
    6. // Add some data rows
    7. grid.addRow("Nicolaus Copernicus", 0.1);
    8. grid.addRow("Galileo Galilei",     0.42);
    9. grid.addRow("Johannes Kepler",     1.0);

    TextRenderer

    Displays plain text as is. Any HTML markup is quoted.

    Custom Renderers

    Renderers are component extensions that require a client-side counterpart. See for information on implementing custom renderers.

    Converting for Rendering

    Optionally, you can give a Converter in the setRenderer(), or define it for the column, to convert the data value to an intermediary representation that is rendered by the renderer. For example, when using an ImageRenderer, you could store the image file name in the data column, which the converter would convert to a resource, which would then be rendered by the renderer.

    In the following example, we use a converter and HTMLRenderer to display boolean values as FontAwesome icons

    Java

    1. // Have a column for hyperlink paths to Wikipedia
    2. grid.addColumn("truth", Boolean.class);
    3. Grid.Column truth = grid.getColumn("truth");
    4. truth.setRenderer(new HtmlRenderer(),
    5.     new StringToBooleanConverter(
    6.         FontAwesome.CHECK_CIRCLE_O.getHtml(),
    7.         FontAwesome.CIRCLE_O.getHtml()));
    8. ...

    In this example, we use a converter to format URL paths to complete HTML hyperlinks with HTMLRenderer:

    Java

    1. // Have a column for hyperlink paths to Wikipedia
    2. grid.addColumn("link", String.class);
    4. Grid.Column linkColumn = grid.getColumn("link");
    5. linkColumn.setRenderer(new HtmlRenderer(),
    6.                        new Converter<String,String>(){
    7.     @Override
    8.     public String convertToModel(String value,
    9.         Class<? extends String> targetType, Locale locale)
    10.         throws Converter.ConversionException {
    11.         return "not implemented";
    12.     }
    14.     @Override
    15.     public String convertToPresentation(String value,
    16.         Class<? extends String> targetType, Locale locale)
    17.         throws Converter.ConversionException {
    18.         return "<a href='http://en.wikipedia.org/wiki/" +
    19.                 value + "' target='_blank'>more info</a>";
    20.     }
    22.     @Override
    23.     public Class<String> getModelType() {
    24.         return String.class;
    25.     }
    27.     @Override
    28.     public Class<String> getPresentationType() {
    29.         return String.class;
    30.     }
    31. });
    33. // Data with a hyperlink path in the third column
    34. grid.addRow("Nicolaus Copernicus", 1473,
    35.             "Nicolaus_Copernicus");

    A GeneratedPropertyContainer could be used for much the same purpose.

    Header and Footer

    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.

    Adding and Removing Header and Footer Rows

    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.

    1. // Group headers by joining the cells
    2. HeaderRow groupingHeader = grid.prependHeaderRow();
    3. ...
    5. // Create a header row to hold column filters
    6. HeaderRow filterRow = grid.appendHeaderRow();
    7. ...

    Similarly, you can add footer rows with appendFooterRow(), prependFooterRow(), and addFooterRowAt().

    Joining Header and Footer Cells

    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.

    Java

    1. // Group headers by joining the cells
    2. HeaderRow groupingHeader = grid.prependHeaderRow();
    3. HeaderCell namesCell = groupingHeader.join(
    4.     groupingHeader.getCell("firstname"),
    5.     groupingHeader.getCell("lastname")).setText("Person");
    6. HeaderCell yearsCell = groupingHeader.join(
    7.     groupingHeader.getCell("born"),
    8.     groupingHeader.getCell("died"),
    9.     groupingHeader.getCell("lived")).setText("Dates of Life");

    Text and HTML Content

    You can set the header caption with setText(), in which case any HTML formatting characters are quoted to ensure security.

    Java

    To use raw HTML in the captions, you can use setHtml().

    Java

    1. namesCell.setHtml("<b>Names</b>");

    Components in Header or Footer

    You can set a component in a header or footer cell with setComponent(). Often, this feature is used to allow filtering, as described in Filtering, which also gives an example of the use.

    Filtering

    The ability to include components in the grid header can be used to create filters for the grid data. Filtering is done in the container data source, so the container must be of type that implements Container.Filterable.

    grid filtering

    Filtering Grid

    The filtering illustrated in Filtering Grid can be created as follows:

    Java

    1. // Have a filterable container
    2. IndexedContainer container = exampleDataSource();
    4. // Create a grid bound to it
    5. Grid grid = new Grid(container);
    6. grid.setSelectionMode(SelectionMode.NONE);
    7. grid.setWidth("500px");
    8. grid.setHeight("300px");
    10. // Create a header row to hold column filters
    11. HeaderRow filterRow = grid.appendHeaderRow();
    13. // Set up a filter for all columns
    14. for (Object pid: grid.getContainerDataSource()
    15.                      .getContainerPropertyIds()) {
    16.     HeaderCell cell = filterRow.getCell(pid);
    18.     // Have an input field to use for filter
    19.     TextField filterField = new TextField();
    20.     filterField.setColumns(8);
    22.     // Update filter When the filter input is changed
    23.     filterField.addTextChangeListener(change -> {
    24.         // Can't modify filters so need to replace
    25.         container.removeContainerFilters(pid);
    27.         // (Re)create the filter if necessary
    28.         if (! change.getText().isEmpty())
    29.             container.addContainerFilter(
    30.                 new SimpleStringFilter(pid,
    31.                     change.getText(), true, false));
    32.     });
    33.     cell.setComponent(filterField);
    34. }

    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.

    Sorting Grid on Multiple Columns

    Defining sort criteria programmatically can be done with the various alternatives of the sort() method. You can sort on a specific column with sort(Object propertyId), which defaults to ascending sorting order, or sort(Object propertyId, SortDirection direction), which allows specifying the sort direction.

    Java

    1. grid.sort("name", 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.

    Java

    1. // Sort first by city and then by name
    2. grid.sort(Sort.by("city", SortDirection.ASCENDING)
    3.               .then("name", SortDirection.DESCENDING));

    The container data source must support sorting. At least, it must implement Container.Sortable. Note that when using GeneratedPropertyContainer, as described in , even though the container implements the interface, the wrapped container must also support it. Also, the generated properties are not normally sortable, but require special handling to enable sorting.

    Editing

    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 Tab and Shift+Tab keys. If validation fails, an error is displayed and the user can correct the inputs.

    To enable editing, you need to call setEditorEnabled(true) for the grid.

    Java

    1. Grid grid = new Grid(GridExample.exampleDataSource());
    2. grid.setEditorEnabled(true);

    Grid supports two row editor modes - buffered and unbuffered. The default mode is buffered. The mode can be changed with setBuffered(false)

    The editor has a Save button that commits the data item to the container data source and closes the editor. The Cancel button discards the changes and exits the editor.

    A row under editing is illustrated in .

    grid editor basic

    Editing a Grid Row

    Unbuffered Mode

    The editor has no buttons and all changed data is committed directly to the container. If another row is clicked, the editor for the current row is closed and a row editor for the clicked row is opened.

    Editor Fields

    The editor fields are by default generated with a FieldFactory and bound to the container data source with a FieldGroup, which also handles tasks such as validation, as explained later.

    To disable editing in a particular column, you can call setEditable() in the Column object with false parameter.

    Customizing Editor Fields

    The editor fields are normally created by the field factory of the editor’s field group, which creates the fields according to the data types of their respective columns. To customize the editor fields of specific properties, such as to style them or to set up validation, you can provide them with setEditorField() in the respective columns.

    In the following example, we configure a field with validation and styling:

    Java

    1. TextField nameEditor = new TextField();
    3. // Custom CSS style
    4. nameEditor.addStyleName("nameeditor");
    6. // Custom validation
    7. nameEditor.addValidator(new RegexpValidator(
    8.     "^\\p{Alpha}+ \\p{Alpha}+$",
    9.     "Need first and last name"));
    11. grid.getColumn("name").setEditorField(nameEditor);

    Setting an editor field to null deletes the currently existing editor field, whether it was automatically generated or set explicitly with the setter. It will be regenerated with the factory the next time it is needed.

    Customizing Editor Buttons

    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:

    Java

    1. // Captions are stored in a resource bundle
    2. ResourceBundle bundle = ResourceBundle.getBundle(
    3.     MyAppCaptions.class.getName(),
    4.     Locale.forLanguageTag("fi")); // Finnish
    6. // Localize the editor button captions
    7. grid.setEditorSaveCaption(
    8.     bundle.getString(MyAppCaptions.SaveKey));
    9. grid.setEditorCancelCaption(
    10.     bundle.getString(MyAppCaptions.CancelKey));

    Binding to Data with a Field Group

    Data binding to the item under editing is handled with a FieldGroup, which you need to set with setEditorFieldGroup. This is mostly useful when using special-purpose field groups, such as BeanFieldGroup to enable bean validation.

    For example, assuming that we want to enable bean validation for a bean such as the following:

    Java

    1. public class Person implements Serializable {
    2.     @NotNull
    3.     @Size(min=2, max=10)
    4.     private String name;
    6.     @Min(1)
    7.     @Max(130)
    8.     private int age;
    9.     ...]

    We can now use a BeanFieldGroup in the Grid as follows:

    Java

    1. Grid grid = new Grid(exampleBeanDataSource());
    2. grid.setColumnOrder("name", "age");
    3. grid.setEditorEnabled(true);
    5. // Enable bean validation for the data
    6. grid.setEditorFieldGroup(
    7.     new BeanFieldGroup<Person>(Person.class));
    9. // Have some extra validation in a field
    10. TextField nameEditor = new TextField();
    11. nameEditor.addValidator(new RegexpValidator(
    12.     "^\\p{Alpha}+ \\p{Alpha}+$",
    13.     "Need first and last name"));
    14. grid.setEditorField("name", nameEditor);

    To use bean validation as in the example above, you need to include an implementation of the Bean Validation API in the classpath, as described in .

    Handling Validation Errors

    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.

    Editing a Grid Row

    You can modify the error handling by implementing a custom EditorErrorHandler or by extending the DefaultEditorErrorHandler.

    Editor Field Factory

    The fields are generated by the FieldFactory of the field group; you can also set it with setEditorFieldFactory(). Alternatively, you can create the editor fields explicitly with setEditorField().

    Programmatic Scrolling

    You can scroll to first item with scrollToStart(), to end with scrollToEnd(), or to a specific row with scrollTo().

    Generating Row or Cell Styles

    You can style entire rows with a RowStyleGenerator or individual cells with a CellStyleGenerator.

    Generating Row Styles

    You set a RowStyleGenerator to a grid with setRowStyleGenerator(). The getStyle() method gets a RowReference, which contains various information about the row 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 names to rows having certain values in one column, you can style them as follows:

    Java

    1. grid.setRowStyleGenerator(rowRef -> {// Java 8
    2.     if (! ((Boolean) rowRef.getItem()
    3.                            .getItemProperty("alive")
    4.                            .getValue()).booleanValue())
    5.         return "grayed";
    6.     else
    7.         return null;
    8. });

    You could then style the rows with CSS as follows:

    CSS

    1. .v-grid-row.grayed {
    2.     color: gray;
    3. }

    You set a CellStyleGenerator to a grid with setCellStyleGenerator(). 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 property ID of the column as follows:

    Java

    1. grid.setCellStyleGenerator(cellRef -> // Java 8
    2.     "born".equals(cellRef.getPropertyId())?
    3.         "rightalign" : null);

    You could then style the cells with a CSS rule as follows:

    CSS

    1. .v-grid-cell.rightalign {
    2.     text-align: right;
    3. }

    CSS

    1. .v-grid {
    2.   .v-grid-scroller, .v-grid-scroller-horizontal { }
    3.   .v-grid-tablewrapper {
    4.     .v-grid-header {
    5.       .v-grid-row {
    6.         .v-grid-cell, .frozen, .v-grid-cell-focused { }
    7.       }
    8.     }
    9.     .v-grid-body {
    10.       .v-grid-row,
    11.       .v-grid-row-stripe,
    12.       .v-grid-row-has-data {
    13.         .v-grid-cell, .frozen, .v-grid-cell-focused { }
    14.       }
    15.     }
    16.     .v-grid-footer {
    17.       .v-grid-row {
    18.         .v-grid-cell, .frozen, .v-grid-cell-focused { }
    19.       }
    20.     }
    21.   }
    22.   .v-grid-header-deco { }
    23.   .v-grid-footer-deco { }
    24.   .v-grid-horizontal-scrollbar-deco { }
    25.   .v-grid-editor {
    26.     .v-grid-editor-cells { }
    27.     .v-grid-editor-footer {
    28.       .v-grid-editor-message { }
    29.       .v-grid-editor-buttons {
    30.         .v-grid-editor-save { }
    31.         .v-grid-editor-cancel { }
    32.       }
    33.     }
    34. }

    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.