DataTable

Overview

The ace:dataTable renders an HTML table element. Rows are created from a List or DataModel object bound on the value property. The header and footer are rendered by Column component children; either by header/footer facets, or by the headerText / footerText properties. Optionally a child ColumnGroup component definition can override these properties of the Column children to allow for column and row spanning configurations.

The full list of features provided by the table and dependant components:

Cell Selection, Multiple and Single
Row Selection, Multiple and Single
Row Editing
Row Panel Expansion
Row Sub-row Expansion
Per-Row Feature Configuration
Filtering, Per-Column and Global
Sorting, Multiple and Single Column
Column Reordering
Column Resizing
Column Visibility
Column Stacking
Column Configuration Panel
Pagination
Scrolling (incl. Lazy Mode)
Lazy Loading Integration
Select, Edit and Filter Event Listeners
Column, Row Spanning Headers & Footers
Optional Application-bound State
- Rows (selection, expansion, etc.)
- Filtering
- Sorting
- Column Reordering
- Pagination

Getting Started

A relatively basic usage of ace:dataTable:

<ace:dataTable var="single"
               value="#{viewBean.objectList}"
               stateMap="${viewBean.rowStateMap}"
               paginator="true"
               rows="5"
               selectionMode="multiple">
    <ace:ajax event="select" execute="details @this" render="details @this"
              onSuccess="ice.ace.jq('#details').effect('highlight');" />

    <ace:column headerText="UPC">
        <h:outputText value="#{single.upc}"/>
    </ace:column>

    <ace:column headerText="Artist">
        <h:outputText value="#{single.artist}" />
    </ace:column>

    <ace:column headerText="Album">
        <h:outputText value="#{single.album}"/>
    </ace:column>

    <ace:column headerText="Name">
        <h:outputText value="#{single.name}"/>
    </ace:column>
</ace:dataTable>

Attributes

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component is available here. Also of interest is the related components section.

The var attribute specifies a request-scope attribute under which the model data for the current row will be exposed.

The value attribute specifies model data for this table. Expected type is a List or DataModel. Lazy loading requires an instance of the LazyDataModel object. Sub-row expansion requires a model of type List<Map.Entry<Object, List>> where the Entry object make up the nodes of a tree; with the key being the value, and the List as possible child nodes.

The stateMap attribute specifies a RowStateMap object. Instantiated by the user or the component, allows application layer manipulation of row properties like selection, visibility and expansion. Maps from table model objects to RowState objects that keep state for component features. See the RowStateMap API for full details.

The paginator attribute specifies a boolean indicating the use of pagination on this table. Default is false.

The rows attribute specifies the number of rows to display per page. Default is 0, to show all rows.

Component Documentation
This section covers complementary components used in the row selection / pagination sample above. For further reference on the component interaction features listed in the overview, see the related components section.

ace:ajax - Configures the component select event to use ajax communication, executing and rendering itself and another area ('details') of the page. Should this communication succeed, the provided javascript snippet is executed. Without this tag, the table would by default cache selections until a submit required by another feature or the tableis submitted as part of a larger request, rather then submitting selections immediately. For more info see Selection Modes, Passive vs. Active.

ace:column - Renders a td element (unless stacked) that represents a single column of data within a parent DataTable container.

Event Listeners

rowSelectListener	Used to define a server side FacesListener which will be notified each time a row is added to selection. The listener receives a single SelectEvent argument. The server event is fired the same lifecycle as 'select' client event.
rowUnselectListener	Used to define a server side FacesListener which will be notified each a row is removed from selection. The listener receives a single UnselectEvent argument. The server event is fired the same lifecycle as 'deselect' client event.
filterListener	Used to define a server side FacesListener which will be notified each lifecycle that filtering is about to take place. The listener is notified before the filtering actually takes place. The listener receives no argument. The server event is fired the same lifecycle as 'filter' client event.

Client Behaviours

select	Fired during the communication of selection of any row or cell, the component default if an ace:ajax tag doesn't declare an event.
page	Fired during the change to another page, by default, execute @this, render @all.
deselect	Fired during the deselection of any row or cell, by default, execute @this, render @all.
sort	Fired during the communication of sorting of any column, by default, execute @this, render @all.
filter	Fired during the communication of filtering of any column, by default, execute @this, render @all.
reorder	Fired during the communication of column reordering, by default, execute @this, render @all.
editStart	Fired during the display of row edit input fields, by default, execute @none, render @none.
editSubmit	Fired during the execute and hiding of row edit input fields, by default, execute @none, render @none. The execute and render of this event are controlled by the component to correctly submit the edit controls of this row without executing anything else.
editCancel	Fired during the hiding of row edit input fields, by default, execute @none, render @none. The execute and render of this event are controlled by the component to correctly reset the edit controls of this row without executing anything else.
expand	Fired by expansion of either row sub-panel or row sub-rows, by default, execute @this, render @all.
contract	Fired by contraction of either row sub-panel or row sub-rows, by default, execute @this, render @all.

Javascript API

The client side API has contains calls for performing feature specific requests and DOM manipulations, but currently there is no API approved for use by the developer.

Lazy Loading

Data Model Lifecycle

The following is a description of the creation of the DataModel from the object bound to the value property.

During table execution, getDataModel() is called. If setDataModel(null) hasn't been called or this is the first time getDataModel() has been run (this request), getValue() is called to return an object to back our DataModel.

The value returned from getValue() is optionally the value property of the table, as returned by a superclass implementation of getValue(), else it returns a filtered List of values. In all cases, the superclass return value has its hashCode calculated.

If the superclass hashCode has changed since getValue() has last been called, we're in a situation where we may need to handle the creation of a TreeDataModel (so we flag a later check in getDataModel()) and if we've applied any filters to the previous DataModel created from the old value, we flag that we ought to refilter the model (to create a new set of filtered values) prior to rendering.

If the superclass hashCode hasn't changed since getValue() has last been called, we return the filtered data set if one exists (avoiding the need to refilter) or return the superclass value. When returning to getDataModel() we skip the check in to handle TreeDataModel creation, and allow the getDataModel() superclass implementation to synthesize our model.

Selection Modes, Passive vs. Active

The table supports submitting selections and deselections passively, that is, storing them until submitted as part of an ajax request initiated by another feature of the table, or as part of communication initiated by another component in the view.

The alternative is active selection, which performs an ajax communication for every (de)selection. This was typically configured in 2.1 and prior with the 'update', 'rowSelectUpdate' and 'rowDeselectUpdate' properties which defined targets on the page to render during selection, and implied use of active selection. Our new handling, which checks to see if there are any non-disabled ace:ajax tags applied to the component for the "select" event, and if so, enables 'active' selection, using the configuration of the ajax tag, or "select" event defaults.

Keyboard Support

Keyboard navigable sub-controls include Sorting, Filtering, Row Expansions and Row Editing.

Keypress	Result
Enter/Space Key	Begin new sort in selected direction. Submit filter. (when configured) Expand/Contract selected expandable rows/panel. Execute selected Edit/Submit/Cancel row button.
Meta Key + Enter/Space Key	Add column to current sort in selected direction.