The Grid component displays single-line text data in a tabular layout and enables editing of the persistent data and row selection.

The data is lazy-loaded, which prevents potential performance issues when the grid is loaded.

Unlike in Tables, the content of cells does not result in any further components, so if you plan on using complex content, such as images, charts, multiple items per cell etc. consider using Table.

Designing a Grid

To create a Grid with your content, do the following:

Insert the Grid component into your Form.
Define the data-source type and the expression that returns the data source object below:
- Type: shared Record
- Query: query call
- Collection: items of the Collection
  
  The Collection is calculated only when the form is initialized: the data source remains unchanged on refresh: To reload the data, use the setDataSource() method on the component.
  
  Note: When applying filtering and sorting on large collections, sorting and filtering actions might cause performance issues: consider using other data sources such as shared Type data sources or queries.
- Custom: custom data source which realizes the forms::DataSource interface.
  
  When creating a custom data source that realizes the DataSource interface, you will need to implement the following methods:
  - getCount returns the number of displayed entries; note that you need to take the filters applied on the data into account. The filters are passed as input arguments.
  - getData returns the data for the grid;
    
    Note that you will need to filter, sort, and page data. The ID of the filters in individual columns is set in the FilterConfig: c.setFilterConfig(new FilterConfig(filterId -> "nameColumnFilter"))
  - supportFilter called when the user enter the filter value;
  - supportsSort called when the user sorts the sort value;
Insert Grid Column components and define their properties ( ) into the Grid. You can insert grid columns dynamically with the addColumn() method.

Creating a Grid Column

To create a column in your Grid, do the following:

Insert the Grid Column component ( ) into the Grid.
Select the type of the value provider, which will prepare the data item (Identity will serve the unchanged data object).
Define the renderer (determines how the value from the value provider is rendered):
- None renders the value as returned by the toString() call.
- HTML renders a String value as HTML.
- Number renders the value in the format defined below.
  
  Define the format as a String following the DecimalFormat Java formatting rules, for example, "0000.00000"
- Date renders the value in the format defined below.
  
  Define the format as a String following the SimpleDateFormat Java formatting rules in the text area below, for example, "EEE, d MMM yyyy HH:mm:ss" results in formatting Wed, 7 Sep 2016 14:33:00
- Enumeration renders an Enumeration value as a String.
- Button renders the value as a Button.
  
  The click action is defined as a closure with the value-provider object as its input parameter below.
```
{ clickRowObject:String ->
    varString := "The user clicked: " + clickRowObject.toString();
    MyEditableGrid.refresh()}
```
- Link renders the value as a Link
  
  The click action is defined as a closure with the Value Provider object as its input parameter below.
```
{  clickRowObject:String ->
    varString := "The user clicked: " + clickRowObject.toString();
    MyEditableGrid.refresh()}
```
- Theme image considers the value to be the path to a Vaadin ThemeResource image and renders the image. The value provider must return a String with the path to the image. The path is relative to current Vaadin theme directory, for example, myapp-war/VAADIN/themes/lsps-blue", so the String path could be "favicon.png". The on-click action is defined as a closure with the Value Provider object as its input parameter below.
- External image considers the value to be the URL to an image and renders the image. The Value Provider must return a String with the URL to the image. For example, external image renderer could be used if for a Closure Value Provider set to {a:Applicant -> "www.acme.com/images/" + a.pictureName}.
- Custom uses a custom renderer that implements the forms::Renderer interface (For further instructions, refer to the developer documentation.

Theme image renderer

Creating a Grid Column Dynamically

To add a column dynamically on runtime, for example, when the user clicks a button, call the addColumn() method on the parent component.

{e -> Vocab.addColumn(
    new forms::TableColumn(
        data -> null,
        modelingId -> null,
        filtrable -> false,
        generator -> null,
        sortable -> false,
        valueProvider -> new PropertyPathValueProvider(Unit.svk))
    )
}

Hiding a Grid Column

You can hide columns of tabular components can be collapsed from the front-end by the user as well as programatically. You can also enable or disable the feature.

By default, Columns can be displayed:

To disable hiding of a Column, call the setHiddable(false) method on the Column.
To hide and show a Grid Column, call the setHidden() method on the Column.

Sorting a Grid

Sorting is defined per Grid Column. To enable it, do the following:

Open the column properties and select the Detail tab.
Select the sortable flag.

Important: When applying sorting on large collections (the Data Source is set to Collection), sorting actions might cause performance issues: consider using other data sources such as shared Type data sources.

Filterable and sortable Grid Column

Filtering a Grid

Important: Filters on Columns of Grids support only the Boolean, String, Integer, Decimal, Date, and Enumeration data types.

To enable filtering on a Grid column, do the following:

Make sure the Grid is filterable: the flag is set with the setFilteringEnabled(true) method and is enabled by default.
On the respective column, set the filtering properties:
1. On the Detail tab, select the Filterable flag.
2. Optionally specify the filter properties with the setFilterConfig() method.
  - OptionsFilterConfig: the user will be able to select one or multiple OptionsFilterConfig from an option set, which will be interpreted as the values and applied by the filter.
```
def SelectItem adv :=  new SelectItem(label -> "Advanced", value -> Level.ADVANCED);
def SelectItem int :=  new SelectItem(label -> "Intermediate", value -> Level.INTERMEDIATE);
def SelectItem beg :=  new SelectItem(label -> "Beginner", value -> Level.BEGINNER);
 
c.setFilterConfig(
   new OptionsFilterConfig(
      multiselect -> true,
      options -> [
          adv, int, beg
      ],
      selected -> [adv, int]
      )
)
```
  - NumericFilterConfig: the user will define a number range
```
// numeric filter with default values:
new NumericFilterConfig(equal ->50, moreThan -> 10, lessThan -> 90)
```
  - DateFilterConfig so the user can define a date range to use for filtering and the format of selected dates
```
new DateFilterConfig(
  resolution -> uicommon::DateTimeResolution.Month, formatPattern -> "YYYY MMMM"
)
```
  - RexExpFilterConfig to define the default regex pattern for filtering
  - SubStringFilterConfig to define the default substring pattern for filtering
  - BooleanFilterConfig to define properties of filter for Boolean values

Also if you are designing a filterable grid with a custom data source, the filter properties (its id) will allow you to identify the filters with set values using the filter id.

Important: When applying filtering on large Collections (the Data Source is set to Collection), sorting and filtering actions might cause performance issues: consider using other data sources such as shared Type data sources.

Filterable and sortable Grid Column

Enabling and Disabling Filtering on a Grid

To enable or disable filtering on Grid, use the setFilterable(Boolean) call on the component: The method hides or displays the filtering row.

Editing a Grid Column

Important: When enabling editing of Grid data, make sure to consider the following:

Since Collections are immutable, you can enable editing only on a Grid with shared Records and Grid Columns with the Value Provider set to Property path.

If the underlying associated shared Record Property returns null, the cell will remain empty and read-only.

To enable editing of shared Record Properties in a Grid, do the following:

Open the Properties view of the Grid component:
1. Select the Editor enabled flag.
2. To save the changes only when the user clicks the Save button in the edited row, select the Editor buffered flag. If the Editor buffered is not selected, the changes are applied to the underlying Record instantly (on every change).
Enable editing on the Grid Column:
1. Open the properties of your Grid Column.
2. Select the Editable flag.
3. In the Editor field, define which editor should be used on the Value Provider object:
  - leave empty for Strings
  - NumberEditor: the user will be able only to provide a number (Decimal or Integer)
  - DateEditor: the user will be able to insert only a date with the option to use a date picker
  - EnumerationEditor: the user will be able to select one of the Enumeration value from a drop-down box
    
    Editable Column with a date value

Enabling Row Selection in a Grid

To allow the user to select grid row and perform an action on row selection, do the following:

Make the Grid selectable using the setSelectable(true) call.
Set the selection mode with the setSelectionMode(SelectionMode) call:
- SelectionMode.NONE: selection disabled
- SelectionMode.SINGLE: single-row selection on click
- SelectionMode.MULTI: selection of multiple items using checkboxes in individual rows
  
  In the MULTI mode, the user can select multiple rows directly under each other by clicking the selection checkbox of the first row, holding the click, and dragging the mouse across the rows below.
To handle a selection, call the setSelectionChangeListener() method on the Grid component: its closure parameter defines how to handle the selection.
To select a Grid row, call the select() method.

//on the Init tab of Properties view:
//enable selection:
c.setSelectable(true);
//set selection mode:
c.setSelectionMode(SelectionMode.MULTI);
//select rows with first two items from the datasource:
c.select(c.getDataSource().getData(0, 2, null, null));
 
//you can also select a particular item in a Collection
//datasource (in SINGLE selection mode):
//c.select(mycollection[0]);
 
//display selected items in an output component:
c.setSelectionChangeListener(
  {
    v:forms::ValueChangeEvent ->
      //set the content of an output component to the selected row:
      labelComponent.setValue(
        c.getSelection().toString());
  }
);

Enabling Selection of Multiple Rows in a Grid

To enable the Select All option on a Grid, set the Grid as selectable in MULTI selection mode and display the Select All checkbox:

c.setSelectable(true);
c.setSelectionMode(SelectionMode.MULTI);
c.setSelectAllCheckBoxVisible(true);

Setting Grid Height

By default, the Grid defines a fixed minimum height. You can change the height using the setHeightByRows(), setHeightFull(), or setHeightWrap() method.

c.setHeightByRows(3)

If the grid displays more row objects, the Grid height follows the height setting and a scrollbar is added:

Grid with a scroll (the height is set to 3 rows and the data source returns 15 row objects

If you want to always adapt the height of the Grid to its content, query the data source its size and adapt the height accordingly, for example:

c.setHeightByRows(c.getDataSource().getCount([]))

Setting CSS Style on Grid Rows

To add a style to grid rows, call the setRowStyleGenerator() method on your grid: the method has a closure parameter with the row object as its input and the CSS class that is added to the row /

element.

c.setRowStyleGenerator({a:Applicant -> "v-label"});

To remove the previously added styles, set the closure to return null, for example, grid.setRowStyleGenerator({a:Applicant -> null});.

Defining Content Align on a Grid Column

To define horizontal alignment in Grid Columns, call the setAlignment() method on the column.