Provides a HTML <table>
element. The Table component is a facade component in
the Table family. Table allows you to present a sortable and pagable table simply
and easily by using only this one component.
The Table 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 , TableRows , TableValues , TableColumns .
The Table 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:
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.
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.
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.
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:
Each column definition may be prefixed by the ! character, which identifies the column as non-sortable.
If defined, a Block with a name that 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.
ITableColumn
object defining the column.
Here is an example of the use of a description string to define columns:
columns="locale:toString(), =currencyColumn,
verbosity:Verbosity:currentRowVerbosity, !delete"
See also: TableView , TablePages , TableRows , TableValues , TableColumns
Name | Type | Required | Default | Description |
---|---|---|---|---|
source |
Object
[]
Collection Iterator IBasicTableModel |
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 ITableColumn[] List Iterator |
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 |
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.
|
||
keyExpression | String | no |
Only active in a form. An OGNL expression that returns the primary key of the iterated value.
The primary keys are stored in hidden fields during rendering and are loaded from the form
during a rewind to ensure that the iterations remain the same.
This is a simpler, but a less efficient alternative of the 'converter' parameter.
If needed, please use in conjuction with 'fullSource' to reference objects
not currently present in 'source'.
Also, use the 'defaultValue' parameter to define the object to be returned if a value corresponding to a particular primary key cannot be found. |
|
fullSource | Object/Collection | no | Only active in a form and in combination with the 'keyExpression' parameter. If an object corresponding to a primary key stored in the form cannot be found in the 'source' parameter, then the objects provided by this parameter are searched for a match next. | |
defaultValue | no | null | Only active in a form. The value to be used when no match for a given primary key is found. | |
converter | no | null | Only active in a form. Defines how the items iterated upon will be stored in the form as hidden values and how the stored information will be converted back to objects. This interface allows only the primary key of the items to be stored, rather than the whole item. | |
primaryKeys | no | Only active in a form. If provided, the parameter is automatically updated before a rewind with the list of primary keys stored in the form. The parameter is updated right before the iterations begin in a rewind and could be used to preload the relevant objects in a provided 'converter'. | ||
volatile | no | Only active in a form. Determines whether to avoid creating hidden fields within a form. Using this parameter may make the form structure different during render and rewind, and cause exceptions as a result. Please use with caution. | ||
persist | String | literal:session |
Defines how the table state (paging and sorting) will be persisted
if no tableSessionStoreManager is defined.
The possible values are session (the default),
client , client:page ,
and client:app .
|
|
tableSessionStateManager | ITableSessionStateManager |
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
|
tableSessionStoreManager | ITableSessionStoreManager |
no | 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. | |
columnSettingsContainer | IComponent |
no | container | The container used to look up Blocks and messages when the source/columns mode is being used. |
index | Object | no | If provided, the parameter is updated with the index of the loop on each iteration. | |
row | Object | no | The value object of the current row being rendered. | |
column | ITableColumn |
no | The object representing the current column being rendered. | |
pageSize | int |
no | 10 |
The number of records displayed per page.
This parameter is only used with the
|
pagesDisplayed | int | 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. |
initialPage | int |
no | 0 |
The initial page to be displayed.
This is the first page by default. |
initialSortColumn | String | 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
|
initialSortOrder | boolean |
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
|
arrowUpAsset | IAsset |
no | The image to use to describe a column sorted in an ascending order. | |
arrowDownAsset | IAsset |
no | The image to use to describe a column sorted in a descending order. | |
pagesClass | String | no | The CSS class of the table pages. | |
columnsClass | String | no | The CSS class of the table columns. | |
rowsClass | String | no | The CSS class of the table rows. | |
valuesClass | String | no | The CSS class of the table values. |
Body: removed
Informal parameters: allowed
Reserved parameters: none
You can find examples in the Tutorial as part of the Workbench application under the "Table" tab.
That page consists of two components -- the
LocaleList
component and the
LocaleSelection
component.
The
LocaleList
component allows you to view all Locales in a table (similar to the example
above), as well as to choose Locales from the table and add them to your
"selection".
The
LocaleSelection
component displays the selected Locales and provides additional information
about them. It also allows Locales to be removed from the selection.
Even though the two components utilizing the Table are placed on a single page, they can operate without any interference from each other with no effort at all on part of the developer -- each table can be sorted independently, for example. This is a good illustration of the power of Tapestry's component approach.
This example shows how you can use the individual components that the Table component wraps to provide more control over how the table is rendered.
<table jwcid="tableView@contrib:TableView" source="ognl:scores" columns="name:sampleName,score1:Score 1:getScoreDisplay(0),score2:Score 2:getScoreDisplay(1),score3:Score 3:getScoreDisplay(2)" > <tr> <span jwcid="@contrib:TableColumns" /> </tr> <tr jwcid="tableRows@contrib:TableRows" class="ognl:beans.evenOdd.next"> <td align="left"> <span jwcid="@Insert" value="ognl:components.tableRows.tableRow.sampleName" /> </td> <td align="right"> <span jwcid="@Insert" value="ognl:components.tableRows.tableRow.getScoreDisplay(0)" /> </td> <td align="right"> <span jwcid="@Insert" value="ognl:components.tableRows.tableRow.getScoreDisplay(1)" /> </td> <td align="right"> <span jwcid="@Insert" value="ognl:components.tableRows.tableRow.getScoreDisplay(2)" /> </td> </tr> <tr> <td colspan="4" class="tablePages"> <span jwcid="tablePages@contrib:TablePages"/> </td> </tr> </table>
As you can see from the example there really isn't very much you can't control on an individual basis.
Of particular note is the area doing table row rendering, the components.tableRows.tableRow.getFoo
reference shows how you can get access to each individual data item being iterated over.