TableView
Providing the data
A low level Table component that wraps all other low level Table components. This component carries the ITableModel that is used by the other Table components. The information that will be displayed can be provided either via the source and columns parameters, or via the tableModel parameters.
There are many ways to provide the component with the data it has to render, but here are the three major ones:
- The data is passed to the source parameter in the form of an array,
a collection, or an iterator, and the table columns are defined
using the columns parameter (see further for details).
Both of these parameters will be evaluated at every request by default,
so changes in the data or the table columns will be displayed immediately.
This is the easiest and most straightforward approach. It has one performance limitation, however - if the table is sorting the data according to a given column, the sorting will be performed at every request. The next methods provide ways to resolve this possible performance issue. - The data is passed to the source parameter via an object that implements
the IBasicTableModel interface. Through that interface you are given
the sorting column (if any) and the numbers of the items that will be
displayed on the current page. You then need to provide the component
with the corresponding data.
This method allows you to perform the sorting in the database and load only the data that will be displayed on the current page (e.g. by using the ORDER BY, LIMIT, and OFFSET clauses in SQL) and hence it could be far more efficient. - All of the information (data, columns, state) is packaged in an
ITableModel
and is passed to the tableModel parameter.
This approach allows greatest flexibility, but is recommended only for advanced users of the Table components.
Defining the columns
If you define the table columns using the columns parameter, you can either provide a list of ITableColumn objects, each defining a column in the table, or you can define the columns using a string that describes each column.
The string describing the columns must be formatted in the following way:
- The column definitions in the string are separated by commas
- Each column definition must be of one of the following types:
- id
- id:expression
- id:description:expression
Here the id defines the identification of the column, the expression is an OGNL expression that extracts the column value from the row object, and description is the title of the column if it is not defined otherwise.
Each column definition may be prefixed by the ! character, which identifies the column as non-sortable.
If defined, a Block with a name that is starts with the column id and ends with ColumnValue will be used to render the column values. Similarly, a Block with a name that starts with the column id and ends with ColumnHeader will be used to render the column headers.
Finally, the title of the column will be taken from translation strings of the component by using the column id as a key.
Please see the LocaleSelection component for examples.
- A column definition may also be of the type
- =expression
in which case it identifies an OGNL expression that returns an ITableColumn object defining the column.
- The full description string may be prefixed by the * character, which means that the table is to be rendered within a form, and the column headers must submit the form if they are clickable (i.e. if the column is sortable).
Here is an example of the use of a description string to define columns: columns="locale:toString(), =currencyColumn, verbosity:Verbosity:currentRowVerbosity, !delete"
See also: Table, TablePages, TableColumns, TableRows, TableValues
Parameters
Name | Type | Direction | Required | Default | Description |
---|---|---|---|---|---|
source | Object[]
Collection Iterator IBasicTableModel |
in | You must provide either both source and columns parameters or the tableModel parameter | The data to be displayed by the component. This parameter must be used in combination with the columns parameter. The parameter must be an array of values, a collection, an iterator, or an object implementing the IBasicTableModel interface. | |
columns | String
ITableColumnModel ITableColumnModel List Iterator |
in | The table columns to be displayed. The parameter must be an array, a list, or an Iterator of ITableColumn objects, an ITableColumnModel, or a String describing the columns (see documentation). | ||
tableModel | ITableModel | in | The ITableModel to be used to render the table. The model contains all of the information needed to render the table and gives greatest flexibility, but it may be harder to implement than simply using the source and columns parameters. | ||
tableSessionStateManager | ITableSessionStateManager | in | no | A custom session state manager that reloads the data at each request if it is provided via the source and columns parameters or stores all of it in the session if it is provided via the tableModel parameter | This is the session state manager that will control what part of the table model
will be saved in the session state. It is then used to recreate the table model
by using what was saved in the session.
You can use one of the stock implementations of ITableSessionStateManager to determine the session state behaviour, or you can define your own. |
tableSessionStoreManager | ITableSessionStoreManager | in | no | null | Determines how the session state (returned by the session state manager) will be saved in the session. If this parameter is null, then the state will be saved as a persistent property. If it is not null, then the methods of the interface will be used to save and load the state. |
pageSize | int | in | no | 10 | The number of records displayed per page.
This parameter is only used with the source and columns parameters. |
initialSortColumn | String | in | no | null | The id of the column to initially sort the table by.
A value of null indicates no sorting.
This parameter is only used with the source and columns parameters. |
initialSortOrder | boolean | in | no | false | The order of the initial sorting.
Set this parameter to false to sort in an ascending order
and to true to sort in a descending one.
This parameter is only used with the source and columns parameters. |
element | String | in | no | table | The tag that will be used to wrap the inner components. If no binding is given, the tag that will be generated is 'table'. If you would like to place the bounds of the table elsewhere, you can make the element 'span' or another neutral tag and manually define the table. |
Body: removed
Informal parameters: allowed
Reserved parameters: none