The Table ( ) component displays the data of the data source in a Table with every data item in a single row.

Note that Table columns can contain other components: while this option provides a high level of flexibility, Tables with many components in their columns might perform poorly. If you are displaying a lot of data in a Table, consider using Grid.

Tables support sorting and filtering out-of-the-box.

Designing a Table

To design a Table, do the following:

Insert Table into your Form.
Define the data-source type and the expression that returns it 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 table; note that you will need to filter, sort, and page data;
  The ID of the filters in individual columns is set in the FilterConfig: new FilterConfig(filterId -> "nameColumnFilter")
  - supportFilter called when the user enter the filter value;
  - supportsSort called when the user sorts the sort value;
Insert the Table Column component ( ) into Table and define its properties:
1. Select the type of the value provider and its value: it returns the content of the cell based on the object of the row (Identity will serve the unchanged data object).
2. Set the iterator type to the type of the value provider:
  
  The iterator type must be always identical with the type of the Value Provider object: the user needs to set the iterator type explicitly since it is not always possible to infer the type of Value Provider object (for example, if the Value Provider is defined by a closure).
3. Insert the form components into Table Column and define their properties.
4. Insert components into the column: they will use the table iterator (it by default) to work with the iterated object).
Insert further columns and define their properties.

Creating a Table Column

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

Insert the Table Column component ( ) into Table.
Select the type of the value provider, which will prepare the data item (Identity will serve the unchanged data object).
Set the iterator type to the type of the value provider:

The iterator type must be always identical with the type of the Value Provider object: the user needs to set the iterator type explicitly since it is not always possible to infer the type of Value Provider object (for example, if the Value Provider is defined by a closure).
Insert the form components into Table Column and define their properties.
Insert components into the column: they will use the table iterator (it by default) to work with the iterated object).

Alternatively, you can add a column programatically with the addColumn() method of Table. This allows you to add columns dynamically on runtime, for example, on button click.

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

Collapsing a Table Column

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 collapsed:

To disable collapsibility of a Column, call the setCollapsible(false) method on the Column.
To collapse or uncollapse a collapsible Column, call the setCollapsed(Boolean) method on the Column.

Reordering Table Columns

To allow drag-and-drop of table columns, use the setColumnReorderingAllowed(true) table call.

Sorting a Table

Sorting is defined per Table Column: the data is sorted depending on which column the user calls the sorting. To enable it, do the following:

Open the column properties and select the Sorting tab.
Select the sortable flag on the Sorting tab.
If you do not want to use the column provider for sorting, define the sorting value provider below.

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.

Filtering a Table

Table filtering is defined per Table Column: the data is filtered depending on which column the user enters the filter. Note that only filtering of Boolean, String, Integer, Decimal, Date, or Enumeration values is supported by the table filter.

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

To enable filtering on a Table Column, do the following in the Properties view of Table Column:

On the Detail tab, define the iterator data type at the bottom of the Properties view to the type returned by the value provider.
On the Filtering tab, define the following:
1. Select the Filterable option.
2. Define Filter value provider so it returns the data for the filter:
  - None: the column value provider is used
    
    Make sure that the provider expression on the Detail tab is set to return the same data type as the iterator data type.
    
    Setting of column value provider for None Filter value provider
  - Property path: the property path to the property of the table object, for example, Patient.diagnosis.code.
  - Closure: a closure that returns the value the filter receives, for example, { p:Patient -> p.reports.size()} will add an integer filter for the number of reports of the Patients in the table.
  - Identity: the identity passed from the row
    
    Make sure to enter the type of the identity below, such as, String, Integer, Decimal, Date, etc.
    
    Identity filter setting
  - Custom: custom implementation of ValueProvider
3. Optionally define the filter configuration: The configuration allows you to further specify the filter properties: You can set it also with the setFilterConfig() method. Also if you are designing a table with a custom Data Source, it will allow you to identify the filters with set values using the filter id.
  - 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.
```
new OptionsFilterConfig(multiselect -> true, options -> [
  new SelectItem(label -> "label of 1", value -> 1),
  new SelectItem(label -> "label of 2", value -> 2)
])
```
  - 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
Make sure the table is filterable: the flag is set with the setFilteringEnabled(true) method and is enabled by default.

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.

Enabling and Disabling Filtering on Tables

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

Selecting Table Rows

To enable row selection on a Table, Grid, or Tree Table, set the table as selectable: MyTable.isSelectable() or MyTable.setSelectable(true). You can then use the setSelectionChangeListener() to listen for user Selection and acquire the selected row with use the getSelection() method.

c.setSelectable(true);
c.setSelectionChangeListener({ e -> selected := c.getSelection().toString(); SelectedLabel.refresh()})

You can use the select() method to select a row programatically.

Example table-row select that selects the user who was created first in the table

myUserTable.select(
    myUserTable.getDataSource().getData(
       startIndex -> 0,
       count -> 0, 
       filters -> null, 
       sortSpecs -> {new Sort(User.created, false)}).getFirst()
);

Setting Batch Load Size of Table Data

To define the size of the data batch of a table, use the setPageLength() method: the data is loaded in these batches as you scroll down the table.

c.setPageLength(3)

If Table height is not set or is set to wrap, it adopt the page length height.

If you want to always adapt the height of Table to its content, you can query the data source of Table for its size, for example:

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

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

Setting No-Data Message

To set the message that is displayed in Table when it is empty, call the setNoDataMessage(<String>) method.

Setting CSS Style on Table Rows

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

element as its return value.

Note that the css class is automatically prefixed with v-table-row- unlike in grid where the class name is passed as is.

//"label" will become "v-table-row-":
c.setRowStyleGenerator({a:Applicant -> "label"});

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

Defining Content Align on a Table Column

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