Using the Apache Trinidad Component

• Introduction
• The Table Model
• Columns
  • Headers
  • Data
  • Formatting
• Selection
• Sorting
  • SortEvent
• Grid Lines and Banding

Introduction

The Apache Trinidad component is used to display a list of structured data. For example, if we have a data structure called Person that has two properties - firstname and lastname, we could use a Table with two columns - one for firstname, and the other for lastname - to display a list of Person objects.

The Table component is similar to the standard UIData component in JSF, but includes a number of extra features, including support for identifying rows by key (instead of by index), built-in support for paging through large models, sorting the model, and selecting single or multiple items in the model.

The Table Model

The Apache Trinidad component uses a model to access the data in the underlying list. The specific model class is org.apache.myfaces.trinidad.model.CollectionModel. You may also use other model instances, e.g., java.util.List, array, and javax.faces.model.DataModel. The Table will automatically convert the instance into a CollectionModel.

To access a particular row in the list, first make that row current, and then call the getRowData() method on the Table. To make a row current, call the setRowIndex(...) method (on the Table) with the appropriate index into the list. Alternatively, call the setRowKey(...) method with the appropriate rowKey.

To obtain the total number of rows in the list, call the getRowCount() method on the Table. In the case where the model does not yet know the total number of rows that are available, getRowCount() will return -1.

The Table has an isRowAvailable() method that returns true if the current row ( see setRowIndex(...) ) is available. This method is especially useful when the total number of rows is unknown.

Columns

The immediate children of a Table component must all be <tr:column> components. Each visible ADF Column component creates a separate column in the Table.

<tr:table>
  <tr:column>
    <f:facet name="header">
      <tr:outputText value="Firstname"/>
    </f:facet>
    ...
  </tr:column>
  <tr:column headerText="Lastname">
    ...
  </tr:column>
</tr:table>
        

<tr:table var="row" value="#{myBean.allEmployees}">
  <tr:column>
    <tr:outputText value="#{row.firstname}"/>
  </tr:column>
  <tr:column>
    tr:outputText value="#{row.lastname}"/>
  </tr:column>
</tr:table>
        

  <tr:table var="row" value="#{myBean.employees}">
    <tr:column headerText="Name">
      <tr:column headerText="First">
        <tr:outputText value="#{row.firstname}"/>
      </tr:column>
      <tr:column headerText="Last">
        tr:outputText value="#{row.lastname}"/>
      </tr:column>
    </tr:column>
  </tr:table>
          

Range Navigation

When the list being displayed by a Table is huge, you can enable the Table to break up the list into ranges and display a single range at a time. Range controls are provided on the Table to let the user scroll to the next range, or to go back to the previous range. If the total size of the list is known, a control to let the user jump directly to a particular part of the list is also provided on the Table. Use the Table attributes "rows" and "first" to control the range navigation feature.

The maximum number of rows to display in a single range is controlled by the "rows" attribute, which defaults to a reasonable size (e.g., 25). To disable range navigation (and display all the rows on one page) set this attribute to 0. In the following example, the maximum number of rows to display per range is set to 10:

<tr:table rows="10" ...>

The current range to display is controlled by the "first" attribute. This attribute is an index (based at zero) of a row in the list. Each range starts with the row identified by "first", and only contains as many rows as indicated by the "rows" attribute. Initially, the "first" attribute defaults to zero, which displays the range with the first row at the top.

Displaying Details

You can configure the Table to display or hide additional details of a particular row in response to a user gesture. When the details feature is enabled, a new column containing a toggle (per row) will render in the Table. When a toggle is activated, the details for that row are displayed. When a toggle is deactivated, the details for the row are hidden. The user can also display or hide the details for all rows at the same time (the controls for this feature are enabled by setting the "allDetailsEnabled" property to true.)

To enable the details feature set the "detailStamp" facet on the Table. Place the components that are used to show the details (of a row), inside this facet. In the following example, the Person's age is displayed in the details section:

<tr:table var="row" value="#{myBean.allEmployees}">
  <f:facet name="detailStamp">
    <tr:outputText value="#{row.age}"/>
  </f:facet>
</tr:table>
        

Usually, the default behavior of the Table (with respect to displaying and hiding details) is sufficient. In some cases, however, it might be desirable to programmatically display or hide the details for a particular row. This can be done via the RowKeySet object obtained from the Table by calling the getDisclosureState() method. First, make the relevant row current by calling setRowIndex(...) or setRowKey(...) on the Table, and then call add() or remove() on the RowKeySet object. Adding the row to the set displays the details of the row. Removing the row hides them.

Selection

The selection feature of a Table lets the user select one or more rows in the list. The user can then perform some operation on the selected rows by activating an appropriate ActionSource component (e.g., by clicking on an ADF CommandButton). Use the "rowSelection" attribute on the Table to enable the selection feature (see the examples below).

There are two types of selection - single and multiple. The type of selection is determined by the value of the "selection" attribute. Use the value "single" to enable single selection, and "multiple" to enable multiple selection.

The current selection of rows on the Table can be programmatically inspected and modified via the RowKeySet object obtained by calling getSelectedRowKeys() on the Table. To programmatically change a selection, add or remove rowKeys from this Set. Alternatively, the appropriate row can be made current by calling setRowIndex(...) or setRowKey(...) on the Table, and then the selection of that row may be changed by calling add() or remove() on the RowKeySet.

<tr:table binding="#{mybean.table}" rowSelection="multiple" ...>
  <f:facet name="footer">
      <tr:commandButton text="Delete" actionListener="#{mybean.performDelete}"/>
  </f:facet>
  ...
</tr:table>
        

public void performDelete(ActionEvent action)
{
  UIXTable table = getTable();
  Iterator selection = table.getSelectedRowKeys().iterator();
  Object oldKey = table.getRowKey();
  while(selection.hasNext())
  {
    Object rowKey = selection.next();
    table.setRowKey(rowKey);
    MyRowImpl row = (MyRowImpl) table.getRowData();
    row.markForDeletion();
  }
  // restore the old key:
  table.setRowKey(oldKey);
}

// Binding methods for access to the table.
public void setTable(UIXTable table) { _table = table; }
public UIXTable getTable() { return _table; }
private UIXTable _table;
        

Sorting

The Table component supports sorting columns in ascending or descending order. A special UI indicator on a column header lets the user know that the column is sortable. When the user clicks on a column header to sort a previously unsorted column, the Table sorts the column data in ascending order. Subsequent clicks on the same header sort the data in the reverse order.

There are three requirements to enable sorting: the underlying table model must support sorting, the "sortProperty" and "sortable" attributes must be set on the column to enable the sort capability for that column.

To support sorting, the CollectionModel instance must implement the following methods:

public boolean isSortable(String propertyName)
public List getSortCriteria()
public void setSortCriteria(List criteria)
        

If the underlying model is not a CollectionModel, the Table automatically examines the actual data to determine which properties are sortable. Any column that has data that implements java.lang.Comparable are sortable. This automatic support cannot be nearly as efficient as coding sorting directly into a CollectionModel (for instance, by translating the sort into an "ORDER BY" SQL clause), but is sufficient for small data sets.

To associate a column with a particular property-name to be used for sorting purposes, use the "sortProperty" attribute on the column. To enable the UI for sorting a particular column, set the "sortable" property to true.

In the following example, both columns are sortable. Sorting the first column sorts by the "firstname" property; sorting the second column sorts by the "lastname" property.

<tr:table ...>
  <tr:column sortProperty="firstname" sortable="true">
    <f:facet name="header">
      <tr:outputText value="Firstname" />
    </f:facet>
    ...
  </tr:column>
  <tr:column>
    <f:facet name="header" sortProperty="lastname" sortable="true">
      <tr:outputText value="Lastname" />
    </f:facet>
    ...
  </tr:column>
</tr:table>
      

Grid Lines and Banding

By default, the table draws both horizontal and vertical grid lines. These may be independently turned off by setting the "horizontalGridVisible" and/or "verticalGridVisible" attributes to "false".

Banding is a technique where groups of rows (or columns) are displayed with alternating background colors. This helps to differentiate between adjacent groups of rows (or columns).

The "rowBandingInterval" attribute on the Table controls how many consecutive rows form a row group (for the purposes of banding). If this is "0" all rows will have the same background color. If this is a positive number then adjacent row groups will have different background colors.

The "columnBandingInterval" attribute on the Table controls how many columns form a column group (for the purposes of banding). If this is "0" all columns will have the same background color. If this is a positive number then adjacent column groups will have different background colors.

In the following example, the row banding pattern is to have two rows with a light background, followed by two rows with a dark background. The pattern is repeated across all rows. Similarly the column banding pattern is to have alternating light/dark columns.

<tr:table rowBandingInterval="2" columnBandingInterval="1" ...>
  ...
</tr:table>