| <!-- |
| 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"> </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> </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> </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> </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> |