blob: 8acbad2ae85d2290b24d04eb6330e81f10149c88 [file] [log] [blame]
<!--
Tbis HTML document provides a base template for Component Reference pages.
* All ??? text should be replaced.
* Examples should illustrate near real world use of the component, see other
existing component page examples for formatting and style guidelines.
* Use Tapestry 2.2 Beta 1+ "expression" binding syntax instead of
"property-path" syntax.
* Include links to Tapestry Javadoc API where appropriate.
* Include Tapestry Developers Guide multi-page version where appropriate.
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- $Id$ -->
<html>
<head>
<title>contrib:TableView</title>
<link rel="stylesheet" type="text/css" href="Tapestry.css" title="style">
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<!-- Previous component in alphabetical order. -->
<td align="left"><a href="contrib.TableValues.html"><img alt="contrib:TableValues" src="common-images/prev.png"></a></td>
<td align="middle"><a href="index.html"><img alt="Component Index" src="common-images/home.png" ></a></td>
<!-- Next component in alphabetical order. -->
<td align="right"><a href="contrib.When.html"><img alt="contrib:When" src="common-images/next.png"></a></td>
<tr>
<tr>
<td colspan="3"><hr></td>
</tr>
<tr>
<td colspan="3">
<table border="0" cellpadding="4" cellspacing="4" width="100%">
<tr valign="top">
<td>
<table>
<tr>
<td><font size="+2"><b>contrib:TableView</b></font></td>
</tr>
<tr>
<td>
<A href="../api/org/apache/tapestry/contrib/table/components/TableView.html">org.apache.tapestry.contrib.table.components.TableView</a>
</td>
</tr>
</table>
</td>
<td>
<table align="right" valign="middle" bgcolor="#c0c0c0" cellpadding="8">
<tr>
<td>Non Visual Component</td>
</tr>
</table>
</td>
</tr>
<tr valign="center">
<td colspan="2">&nbsp;</td>
</tr>
<tr>
<td colspan="2">
<b>Description</b>
<br>
A low level Table component that wraps all other low level Table components.
This component carries the <A HREF="../api/org/apache/tapestry/contrib/table/model/ITableModel.html"><CODE>ITableModel</CODE></A>
that is used by the other Table components.
The information that will be displayed can be provided either via
the <code>source</code> and <code>columns</code> parameters,
or via the <code>tableModel</code> parameters.
<p></p>
</td>
</tr>
<tr>
<td colspan="2">
<b>Providing the data</b>
<p>
There are many ways to provide the component with the data it has to render,
but here are the three major ones:
<ol>
<li> The data is passed to the <code>source</code> parameter in the form of an array,
a collection, or an iterator, and the table columns are defined using the
<code>columns</code> 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.
<p>
The example below uses this method.
<p>
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.
<p></p>
<li> The data is passed to the <code>source</code> parameter via an object that
implements the <A HREF="../api/org/apache/tapestry/contrib/table/model/IBasicTableModel.html"><CODE>IBasicTableModel</CODE></A>
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.
<p>
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.
<p></p>
<li> All of the information (data, columns, state) is packaged in an
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableModel.html"><CODE>ITableModel</CODE></A>
and is passed to the <code>tableModel</code> parameter.
<p>
This approach allows greatest flexibility, but is recommended only for advanced users of the Table components.
</ol>
<p></p>
</td>
</tr>
<tr>
<td colspan="2">
<b>Defining the columns</b>
<p>
If you define the table columns using the <code>columns</code> parameter, you can either
provide a list of <A HREF="../api/org/apache/tapestry/contrib/table/model/ITableColumn.html"><code>ITableColumn</code></A>
objects, each defining a column in the table, or you can define the columns using
a string that describes each column.
<p>
Please see the example below as a demonstration of the use of the latter approach.
<p>
The string describing the columns must be formatted in the following way:
<ul>
<li>The column definitions in the string are separated by commas
<p>
<li>Each column definition must be of one of the following types:<p>
<dl>
<dd>id</dd>
<dd>id:expression</dd>
<dd>id:description:expression</dd>
</dl>
<br>
Here the <b>id</b> defines the identification of the column, the <b>expression</b> is an
OGNL expression that extracts the column value from the row object, and <b>description</b>
is the title of the column if it is not defined otherwise.
<p>
Each column definition may be prefixed by the <b>!</b> character,
which identifies the column as non-sortable.
<p>
If defined, a Block with a name that is starts with the column id and
ends with <i>ColumnValue</i> will be used to render the column values.
Similarly, a Block with a name that starts with the column id and
ends with <i>ColumnHeader</i> will be used to render the column headers.
<p>
Finally, the title of the column will be taken from translation strings of the component
by using the column id as a key.
<p>
Please see the <SPAN class=code>LocaleSelection</SPAN> component for examples.
<p>
<li>A column definition may also be of the type
<p>
<dl>
<dd>=expression</dd>
</dl>
<br>
in which case it identifies an OGNL expression that returns an
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableColumn.html"><code>ITableColumn</code></A>
object defining the column.
<p>
<li>The full description string may be prefixed by the <b>*</b> 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).
</ul>
<p>
Here is an example of the use of a description string to define columns:
<pre>
columns="locale:toString(), =currencyColumn, verbosity:Verbosity:currentRowVerbosity, !delete"
</pre>
<p></p>
</td>
</tr>
<tr>
<td colspan="2">
<b>Saving the state in the session</b>
<p>
This component also handles the saving of the state of the model using an
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStateManager.html"><CODE>ITableSessionStateManager</CODE></A>
to determine what part of the model is to be saved and an
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStoreManager.html"><CODE>ITableSessionStoreManager</CODE></A>
to determine how to save it.
<p>
Upon the beginning of a new request cycle when the table model is first needed,
the model is obtained using the following process:
<ul>
<li>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
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStoreManager.html"><CODE>ITableSessionStoreManager</CODE></A> is used
to load the persistent state.
<li>The table model is recreated using the
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStateManager.html"><CODE>ITableSessionStateManager</CODE></A> 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.
<li>If the <A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStateManager.html"><CODE>ITableSessionStateManager</CODE></A>
returns null, then a table model is taken from the tableModel binding. Thus, if
the <A HREF="../api/org/apache/tapestry/contrib/table/model/common/NullTableSessionStateManager.html"><CODE>NullTableSessionStateManager</CODE></A>
is used, the table model would be taken from the tableModel binding every time.
<li>If the tableModel parameter is not bound or returns null, the table model is generated
from the contents of the source and columns parameters.
</ul>
At the end of the rewind phase the persistent state of the model is saved in
the session. This process occurs in reverse:
<ul>
<li>The persistent state of the model is taken via the
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStateManager.html"><CODE>ITableSessionStateManager</CODE></A>.
<li>If the tableSessionStoreManager binding has not been bound, the persistent
state is saved as a persistent page property. Otherwise the supplied
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStoreManager.html"><CODE>ITableSessionStoreManager</CODE></A> is used
to save the persistent state. Use of the
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStoreManager.html"><CODE>ITableSessionStoreManager</CODE></A>
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.
</ul>
</td>
</tr>
<tr>
<td colspan="2">
<b>See Also</b>
<br>
<A href="contrib.Table.html">Table</a>,
<A href="contrib.TableColumns.html">TableColumns</a>,
<A href="contrib.TablePages.html">TablePages</a>,
<A href="contrib.TableRows.html">TableRows</a>,
<A href="contrib.TableValues.html">TableValues</a>
</td>
</tr>
<tr>
<td colspan="2">
<b>Parameters</b>
<br>
<table border="1" cellpadding="4" cellspacing="4" class="parameters">
<tr>
<th>Name</th>
<th>Type</th>
<th>Direction</th>
<th>Required</th>
<th>Default</th>
<th>Description</th>
</tr>
<tr>
<td>source</td>
<td><code><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Object.html">Object</A>[]</code><br>
<code><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Collection.html">Collection</A></code><br>
<code><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Iterator.html">Iterator</A></code><br>
<A HREF="../api/org/apache/tapestry/contrib/table/model/IBasicTableModel.html"><CODE>IBasicTableModel</CODE></A>
</td>
<td>in</td>
<td rowspan="3">You must provide either both <code>source</code> and <code>columns</code> parameters
or the <code>tableModel</code> parameter</td>
<td>&nbsp;</td>
<td align="left">
The data to be displayed by the component. This parameter must be used
in combination with the <code>columns</code> parameter.
The parameter must be an array of values, a collection, an iterator,
or an object implementing the IBasicTableModel interface.
</td>
</tr>
<tr>
<td>columns</td>
<td>
<code><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/String.html">String</A></code><br>
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableColumnModel.html"><code>ITableColumnModel</code></A><br>
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableColumn.html"><code>ITableColumn[]</code></A><br>
<code><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/List.html">List</A></code><br>
<code><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/util/Iterator.html">Iterator</A></code>
</td>
<td>in</td>
<td>&nbsp;</td>
<td align="left">
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).
</td>
</tr>
<tr>
<td>tableModel</td>
<td><A HREF="../api/org/apache/tapestry/contrib/table/model/ITableModel.html"><CODE>ITableModel</CODE></A></td>
<td>in</td>
<td>&nbsp;</td>
<td align="left">The <A HREF="../api/org/apache/tapestry/contrib/table/model/ITableModel.html"><CODE>ITableModel</CODE></A> 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 <code>source</code> and <code>columns</code> parameters.
</td>
</tr>
<tr>
<td>tableSessionStateManager</td>
<td><A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStateManager.html"><CODE>ITableSessionStateManager</CODE></A></td>
<td>in</td>
<td>no</td>
<td>A custom session state manager that reloads the data at each request if it is provided
via the <code>source</code> and <code>columns</code> parameters or stores all
of it in the session if it is provided via the <code>tableModel</code> parameter</td>
<td align="left">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.
<p> You can use one of the stock implementations of
<A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStateManager.html"><CODE>ITableSessionStateManager</CODE></A>
to determine the session state behaviour, or you can define your own.
</td>
</tr>
<tr>
<td>tableSessionStoreManager</td>
<td><A HREF="../api/org/apache/tapestry/contrib/table/model/ITableSessionStoreManager.html"><CODE>ITableSessionStoreManager</CODE></A></td>
<td>in</td>
<td>no</td>
<td>null</td>
<td align="left">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.
</td>
</tr>
<tr>
<td>columnSettingsContainer</td>
<td><A HREF="../api/org/apache/tapestry/IComponent.html"><CODE>IComponent</CODE></A></td>
<td>in</td>
<td>no</td>
<td>container</td>
<td align="left">
This parameter is used only if the table columns are defined as a string in the <code>columns</code> parameter,
The provided component may define Blocks with particular names that will be used
as the header and value renderers of the corresponding columns (see documentation above),
and define the display names of the columns in its translation file(s).
</td>
</tr>
<tr>
<td>pageSize</td>
<td>
<code>int</code>
</td>
<td>in</td>
<td>no</td>
<td>10</td>
<td align="left">
The number of records displayed per page.
<p>
This parameter is only used with the <code>source</code> and <code>columns</code> parameters.
</td>
</tr>
<tr>
<td>initialSortColumn</td>
<td>
<code><A HREF="http://java.sun.com/j2se/1.4.2/docs/api/java/lang/String.html">String</A></code>
</td>
<td>in</td>
<td>no</td>
<td>null</td>
<td align="left">
The id of the column to initially sort the table by.
A value of <code>null</code> indicates no sorting.
<p>
This parameter is only used with the <code>source</code> and <code>columns</code> parameters.
</td>
</tr>
<tr>
<td>initialSortOrder</td>
<td>
<code>boolean</code>
</td>
<td>in</td>
<td>no</td>
<td>false</td>
<td align="left">
The order of the initial sorting.
Set this parameter to <code>false</code> to sort in an ascending order
and to <code>true</code> to sort in a descending one.
<p>
This parameter is only used with the <code>source</code> and <code>columns</code> parameters.
</td>
</tr>
<tr>
<td>element</td>
<td>String</td>
<td>in</td>
<td>no</td>
<td>"table"</td>
<td align="left">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.
</td>
</tr>
</table>
<p>
Body: <strong>removed</strong><br>
Informal parameters: <strong>allowed</strong><br>
<!-- component-specification "reserved-parameter" -->
Reserved parameters: none
</p>
</td>
</tr>
<tr>
<td colspan="2">
<b>Examples</b>
<p>
This example is under construction.
</p>
</td></tr></table>
</td></tr>
<tr>
<td colspan="3"><hr></td>
</tr>
<tr>
<!-- Previous component in alphabetical order. -->
<td align="left"><a href="contrib.TableValues.html"><img alt="contrib:TableValues" src="common-images/prev.png"></a></td>
<td align="middle"><a href="index.html"><img alt="Component Index" src="common-images/home.png" ></a></td>
<!-- Next component in alphabetical order. -->
<td align="right"><a href="contrib.When.html"><img alt="contrib:When" src="common-images/next.png"></a></td>
</tr>
</table>
</body>
</html>