Jakarta > Tapestry
Jakarta
 

FormTable

Warning
This component has been deprecated; The Table component in Tapestry 4.0 automatically performs the FormTable functions if contained by Form components.

A version of the Table component designed for use in a form. Like Table, this component allows you to present a sortable and pagable table simply and easily. It also stores the items it dispays in hidden fields in the form, so that they are identical during the rewind cycle when the form is submitted, and generates links that submit the form, so that any other form information is preserved.

The differences between FormTable and Table are the following:

The FormTable component allows you to manipulate its appearance by allowing you to define the 'class' attributes of its internal elements. If you want to change the structure of the table, however, you can instead build your own using the lower level components TableView, TablePages, TableFormPages, TableColumns, TableRows, TableFormRows, and TableValues.

The FormTable component delegates the handling of the table model and related activities to the TableView, and more detailed information about the process can be found in the documentation of that class.

Providing the data

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.

    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.

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:

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, TableView, 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.
convertor IPrimaryKeyConvertor in no   An interface defining how the items iterated upon by this component will be stored in the form as Hidden values. This interface allows only the primary key of the items to be stored, rather than the whole item.
row Object out no   The value object of the current row being rendered.
column ITableColumn out no   The object representing the current column being rendered.
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.
pagesDisplayed int in no 7 Determines the maximum number of pages to be displayed in the page list when the table has more than one page.
For example, if the table has 20 pages, and 10 is the current page, pages from 7 to 13 in the page list will be shown if this parameter has a value of 7.
arrowUpAsset IAsset in no   The image to use to describe a column sorted in an ascending order.
arrowDownAsset IAsset in no   The image to use to describe a column sorted in a descending order.
pagesClass String in no The CSS class of the table pages.
columnsClass String in no The CSS class of the table columns.
rowsClass String in no The CSS class of the table rows.
valuesClass String in no The CSS class of the table values.

Body: allowed

Informal parameters: allowed

Reserved parameters: none

Examples