There are many ways to provide the component with the data it has to render, but here are the three major ones:

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

   The example below uses this method.

   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.

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

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

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.

Please see the example below as a demonstration of the use of the latter approach.

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"

This component also handles the saving of the state of the model using an ITableSessionStateManager to determine what part of the model is to be saved and an ITableSessionStoreManager to determine how to save it.

Upon the beginning of a new request cycle when the table model is first needed, the model is obtained using the following process:

• The persistent state of the table is loaded. If the tableSessionStoreManager binding has not been bound, the state is loaded from a persistent property within the component (it is null at the beginning). Otherwise the supplied ITableSessionStoreManager is used to load the persistent state.
• The table model is recreated using the ITableSessionStateManager that could be supplied using the tableSessionStateManager binding. This parameter has a default value and is therefore not required. The default implementation stores only the Table state (sorting column and direction, as well as current page) if the data is provided using the source and columns parameters, and stores the whole table model if it is provided using the tableModel parameter.
• If the ITableSessionStateManager returns null, then a table model is taken from the tableModel binding. Thus, if the NullTableSessionStateManager is used, the table model would be taken from the tableModel binding every time.
• If the tableModel parameter is not bound or returns null, the table model is generated from the contents of the source and columns parameters.

• The persistent state of the model is taken via the ITableSessionStateManager.
• If the tableSessionStoreManager binding has not been bound, the persistent state is saved as a persistent page property. Otherwise the supplied ITableSessionStoreManager is used to save the persistent state. Use of the ITableSessionStoreManager is usually necessary when tables with the same model have to be used across multiple pages, and hence the state has to be saved in the Visit, rather than in a persistent component property.

Body: removed
Informal parameters: allowed
Reserved parameters: none

This example is under construction.