com.arsdigita.toolbox.ui
Class DataTable

java.lang.Object
  extended bycom.arsdigita.bebop.Completable
      extended bycom.arsdigita.bebop.SimpleComponent
          extended bycom.arsdigita.bebop.TextStylable
              extended bycom.arsdigita.bebop.BlockStylable
                  extended bycom.arsdigita.bebop.Table
                      extended bycom.arsdigita.toolbox.ui.DataTable
All Implemented Interfaces:
BebopConstants, Cloneable, Component, Lockable, PaginationModelBuilder

public class DataTable
extends Table
implements PaginationModelBuilder

General

Wraps any DataQuery in a sortable Bebop Table. The DataQuery is supplied by the DataQueryBuilder class, which the user must implement. The DataQueryBuilder may dynamically construct the query during each request, or return the same named query for each request; the DataTable does not care where the query comes from.

This class may contain multiple QueryListeners. These listeners will be fired whenever the query is about to be performed, thus giving the user a chance to set additional filters on the query.

Columns may be added to the DataTable by calling the addColumn(java.lang.String, java.lang.String, boolean, com.arsdigita.bebop.table.TableCellRenderer) method. The user may choose to make the column sortable or non-sortable; sortable columns will appear as links on the Web page which, when clicked, will sort the table by the specified column. See the documentation on the various addColumn methods for more information.

Note that any DomainCollection can be used with DataTable, since the DomainCollection is merely a wrapper for a DataCollection, which extends DataQuery. The DomainService class may be used to retieve the DataCollection for any given DomainCollection.

This class sets the XSL "class" attribute to "dataTable"

Pagination

DataTable also implements PaginationModelBuilder. This means that it could serve as the model builder for any Paginator component. Pagination of the query occurs after all the sorting and query events have finished. Consider a query which returns the rows "A B C D E F". If the paginator displays 3 rows per page, page 1 will contain "A B C" and page 2 will contain "D E F". If the user then clicks on the header in the DataTable, causing the query to be sorted in reverse order, page 1 will contain "F E D" and page 2 will contain "C B A". In order for pagination to work properly, the following pattern must be used:
DataTable table = new DataTable(...);
 Paginator paginator = new Paginator(table, ...);
 table.setPaginator(paginator);
The setPaginator call is required due to a design flaw in the Paginator component.

Globalization

The DataTable will ordinarily interpret the labels of its column headers as plain text, and spit them out on the screen verbatim. However, if setResouceBundle is called, DataTable will instead interpret the column header labels as keys into the specified resource bundle, thus attempting to globalize the column headers at runtime.

Version:
$Id: //core-platform/dev/src/com/arsdigita/toolbox/ui/DataTable.java#13 $
Author:
Stanislav Freidin

Nested Class Summary
protected static class DataTable.DataBuilderAdapter
          Adapts a DataQueryBuilder into a TableModelBuilder.
protected static class DataTable.DataQueryTableModel
          A TableModel which gets its data from a DataQuery.
protected static class DataTable.DataTableColumnModel
          A special column model that maintains an alternate key for each column.
protected static class DataTable.GlobalizedHeaderCellRenderer
          Always renders the table header as a link.
static class DataTable.SortableTableColumn
          A TableColumn that could potentially be sorted
 
Nested classes inherited from class com.arsdigita.bebop.Table
Table.MatrixTableModelBuilder
 
Field Summary
static String ASCENDING
           
static String DESCENDING
           
static String DIRECTION
           
static String ORDER
           
static String versionId
           
 
Fields inherited from class com.arsdigita.bebop.Table
CELL_EVENT, EMPTY_MODEL, SEP
 
Fields inherited from class com.arsdigita.bebop.BlockStylable
ABSBOTTOM, ABSMIDDLE, BASELINE, BOTTOM, CENTER, FULL_WIDTH, INSERT, LEFT, MIDDLE, RIGHT, TEXTTOP, TOP
 
Fields inherited from class com.arsdigita.bebop.SimpleComponent
m_attr
 
Fields inherited from interface com.arsdigita.bebop.util.BebopConstants
BEBOP_BORDER, BEBOP_BOXPANEL, BEBOP_CELL, BEBOP_CHECKBOX, BEBOP_CHECKBOXGROUP, BEBOP_COLUMNPANEL, BEBOP_DATE, BEBOP_DATETIME, BEBOP_DHTMLEDITOR, BEBOP_FORMERRORS, BEBOP_FORMWIDGET, BEBOP_GRIDPANEL, BEBOP_LIST, BEBOP_MULTISELECT, BEBOP_OPTION, BEBOP_PAD, BEBOP_PADFRAME, BEBOP_PANELROW, BEBOP_PORTAL, BEBOP_PORTLET, BEBOP_RADIO, BEBOP_RADIOGROUP, BEBOP_SEG_BODY, BEBOP_SEG_HEADER, BEBOP_SEG_PANEL, BEBOP_SEGMENT, BEBOP_SELECT, BEBOP_TABLE, BEBOP_TABLEBODY, BEBOP_TABLEROW, BEBOP_TEXTAREA
 
Fields inherited from interface com.arsdigita.bebop.Component
BEBOP_XML_NS, CLASS, ID, ON_CLICK, STYLE
 
Constructor Summary
DataTable(DataQueryBuilder builder)
          Construct a new DataTable
DataTable(DataQueryBuilder builder, SingleSelectionModel orderModel)
          Construct a new DataTable.
DataTable(DataQueryBuilder builder, SingleSelectionModel orderModel, String resourceBundle)
          Construct a new DataTable.
 
Method Summary
 TableColumn addColumn(String label, String attribute)
          Add a column to this table.
 TableColumn addColumn(String label, String attribute, boolean isSortable)
          Add a column to this table.
 TableColumn addColumn(String label, String attribute, boolean isSortable, TableCellRenderer renderer)
          Add a column to this table.
 TableColumn addColumn(String label, String attribute, boolean isSortable, TableCellRenderer renderer, String orderAttribute)
          Add a column to this table.
 TableColumn addColumn(String label, TableCellRenderer renderer)
          Add a column to this table.
 void addQueryListener(QueryListener l)
          Add a QueryListener to this table.
protected  void fireQueryPending(PageState state, DataQuery query)
          Fire the query event listeners to indicate that a query is about to be performed
 void generateExtraXMLAttributes(PageState s, Element element)
          Adds type-specific XML attributes to the XML element representing this link.
 DataQuery getDataQuery(PageState s)
          Return the DataQuery that will be used during the current request
 DataQueryBuilder getDataQueryBuilder()
           
 String getDefaultOrder()
          Get the key of the default column which will be used to sort the entries
 String getOrder(PageState s)
           
 String getOrderDirection(PageState s)
           
 SingleSelectionModel getOrderSelectionModel()
           
 Paginator getPaginator()
          Return the paginator component used by this table, or null if the table is not paginated.
protected  RequestLocal getQuerySizeLocal()
          Return the RequestLocal used for storing the query size during the request
 String getResourceBundle()
          Return the resource bundle for globalization, or null if no bundle was specified
 int getTotalSize(Paginator paginator, PageState s)
          Paginate the query according to the paginator component.
 GlobalizedMessage globalize(String key)
          Globalizes the specified key.
 void lock()
          Lock this table
 void register(Page p)
          Register the ordering parameter
 void removeQueryListener(QueryListener l)
          Remove a QueryListener from this table.
 void setDataQueryBuilder(DataQueryBuilder builder)
           
 void setDefaultOrder(String attribute)
          Set the key of the default column which will be used to sort the entries
 void setOrder(PageState s, String attr)
          Set the column by which the table will be ordered
 void setOrderDirection(PageState s, String dir)
          Set the sort direction
 void setOrderSelectionModel(SingleSelectionModel orderModel)
          Set the SingleSelectionModel that will determine the order for the items in the tabke
 void setPaginator(Paginator p)
          Set the paginator component used by this table, or null if the table should not be paginated.
 void setResourceBundle(String bundle)
          Set the resource bundle for globalization, or null if no globalization is needed
 String toggleOrderDirection(PageState s)
          Toggle the sort direction between ascending and descending
 
Methods inherited from class com.arsdigita.bebop.Table
addTableActionListener, children, clearSelection, createTableActionListener, fireCellSelected, fireHeadSelected, generateXML, getBorder, getCellPadding, getCellSpacing, getColumn, getColumnModel, getColumnSelectionModel, getControler, getDefaultCellRenderer, getEmptyView, getHeader, getModelBuilder, getRowSelectionModel, getStriped, getTableModel, getWidth, isSelectedCell, isSelectedColumn, isSelectedRow, removeTableActionListener, respond, setBorder, setCellPadding, setCellSpacing, setColumn, setColumnModel, setColumnSelectionModel, setDefaultCellRenderer, setEmptyView, setHeader, setModelBuilder, setRowSelectionModel, setStriped, setWidth
 
Methods inherited from class com.arsdigita.bebop.BlockStylable
setBorder, setBorder, setBorderColor, setHorizontalAlignment, setMargin, setMargin, setPadding, setPadding, setVerticalAlignment
 
Methods inherited from class com.arsdigita.bebop.TextStylable
setBackgroundColor, setColor
 
Methods inherited from class com.arsdigita.bebop.SimpleComponent
clone, exportAttributes, getAttribute, getClassAttr, getIdAttr, getKey, getMetaDataAttribute, getStyleAttr, hasAttributes, isLocked, isVisible, register, setAttribute, setClassAttr, setIdAttr, setKey, setMetaDataAttribute, setStyleAttr, setVisible
 
Methods inherited from class com.arsdigita.bebop.Completable
addCompletionListener, fireCompletionEvent
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.arsdigita.bebop.PaginationModelBuilder
isVisible
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values

ORDER

public static final String ORDER
See Also:
Constant Field Values

DIRECTION

public static final String DIRECTION
See Also:
Constant Field Values

ASCENDING

public static final String ASCENDING
See Also:
Constant Field Values

DESCENDING

public static final String DESCENDING
See Also:
Constant Field Values
Constructor Detail

DataTable

public DataTable(DataQueryBuilder builder,
                 SingleSelectionModel orderModel,
                 String resourceBundle)
Construct a new DataTable.

Parameters:
builder - the DataQueryBuilder that will be used for this browser
orderModel - the SingleSelectionModel that will be used to determine the column to order by
resourceBundle - the name of the resource bundle that will be used to globalize the column labels. If null, column labels will be printed verbatim to the screen.

DataTable

public DataTable(DataQueryBuilder builder,
                 SingleSelectionModel orderModel)
Construct a new DataTable.

Parameters:
builder - the DataQueryBuilder that will be used for this browser
orderModel - the SingleSelectionModel that will be used to determine the column to order by

DataTable

public DataTable(DataQueryBuilder builder)
Construct a new DataTable

Parameters:
builder - the DataQueryBuilder that will be used for this browser
Method Detail

register

public void register(Page p)
Register the ordering parameter

Specified by:
register in interface Component
Overrides:
register in class Table
Parameters:
p - the page that contains this table

setDefaultOrder

public void setDefaultOrder(String attribute)
Set the key of the default column which will be used to sort the entries

Parameters:
attribute - the default attribute to sort by

getDefaultOrder

public String getDefaultOrder()
Get the key of the default column which will be used to sort the entries

Returns:
the default attribute to sort by, or null if no default has been set

addColumn

public TableColumn addColumn(String label,
                             String attribute,
                             boolean isSortable,
                             TableCellRenderer renderer)
Add a column to this table.

Parameters:
label - The user-readable label for the column
attribute - The name of the attribute in the DataQuery which will be used as the value for this column.
isSortable - true if it is possible to sort using this column, false otherwise
renderer - a TableCellRenderer that will be used to format the attribute as a string.
Returns:
the newly added column

addColumn

public TableColumn addColumn(String label,
                             String attribute,
                             boolean isSortable,
                             TableCellRenderer renderer,
                             String orderAttribute)
Add a column to this table.

Parameters:
label - The user-readable label for the column
attribute - The name of the attribute in the DataQuery which will be used as the value for this column.
isSortable - true if it is possible to sort using this column, false otherwise
renderer - a TableCellRenderer that will be used to format the attribute as a string.
orderAttribute - The name of the attribute which will be used as the column to order by. This key may be different from the attribute parameter.
Returns:
the newly added column

addColumn

public TableColumn addColumn(String label,
                             String attribute,
                             boolean isSortable)
Add a column to this table.

Parameters:
label - The user-readable label for the column
attribute - The name of the attribute in the DataQuery which will be used as the value for this column.
isSortable - true if it is possible to sort using this column, false otherwise
Returns:
the newly added column

addColumn

public TableColumn addColumn(String label,
                             String attribute)
Add a column to this table.

Parameters:
label - The user-readable label for the column
attribute - The name of the attribute in the DataQuery which will be used as the value for this column.
Returns:
the newly added column

addColumn

public TableColumn addColumn(String label,
                             TableCellRenderer renderer)
Add a column to this table. The value for the column will not be supplied by the query; instead, it is the user's responsibility to supply the value through a custom TableModel or render it directly in the TableCellRenderer. Typically, this method will be used to add ControlLinks to the table.

Parameters:
label - The user-readable label for the column
renderer - The cell renderer for the given column
Returns:
the newly added column

getDataQueryBuilder

public DataQueryBuilder getDataQueryBuilder()
Returns:
the DataQueryBuilder that creates a DataQuery for this table during each request

setDataQueryBuilder

public void setDataQueryBuilder(DataQueryBuilder builder)
Parameters:
builder - the new DataQueryBuilder for this table

setOrderSelectionModel

public void setOrderSelectionModel(SingleSelectionModel orderModel)
Set the SingleSelectionModel that will determine the order for the items in the tabke

Parameters:
orderModel - The new model

getOrderSelectionModel

public SingleSelectionModel getOrderSelectionModel()
Returns:
the SingleSelectionModel that will determine the order

addQueryListener

public void addQueryListener(QueryListener l)
Add a QueryListener to this table. The listener will be fired whenever the query is about to be performed.

Parameters:
l - the new query listener

removeQueryListener

public void removeQueryListener(QueryListener l)
Remove a QueryListener from this table.

Parameters:
l - the new query listener

fireQueryPending

protected void fireQueryPending(PageState state,
                                DataQuery query)
Fire the query event listeners to indicate that a query is about to be performed

Parameters:
state - The page state
query - The DataQuery

setOrder

public void setOrder(PageState s,
                     String attr)
Set the column by which the table will be ordered

Parameters:
s - the page state
attr - the attribute by which the table will be sorted

getOrder

public String getOrder(PageState s)
Parameters:
s - the page state
Returns:
the column by which the table will be ordered

getOrderDirection

public String getOrderDirection(PageState s)
Parameters:
s - the page state
Returns:
the order by which the currently selected column will be sorted; will be either ASCENDING or DESCENDING

setOrderDirection

public void setOrderDirection(PageState s,
                              String dir)
Set the sort direction

Parameters:
s - the page state
dir - the direction in which the current column should be sorted; either ASCENDING or DESCENDING

toggleOrderDirection

public String toggleOrderDirection(PageState s)
Toggle the sort direction between ascending and descending

Parameters:
s - the page state
Returns:
the new order direction; will be either ASCENDING or DESCENDING

getDataQuery

public DataQuery getDataQuery(PageState s)
Return the DataQuery that will be used during the current request

Parameters:
s - the page state for the current request
Returns:
the current DataQuery

getTotalSize

public int getTotalSize(Paginator paginator,
                        PageState s)
Paginate the query according to the paginator component. This method will be automatically called by the Paginator component to which this DataTable has been added as the model builder.

Specified by:
getTotalSize in interface PaginationModelBuilder
Parameters:
paginator - the parent Paginator
s - the current page state
Returns:
the total number of rows in the query

getPaginator

public final Paginator getPaginator()
Return the paginator component used by this table, or null if the table is not paginated.


setPaginator

public final void setPaginator(Paginator p)
Set the paginator component used by this table, or null if the table should not be paginated.


getQuerySizeLocal

protected final RequestLocal getQuerySizeLocal()
Return the RequestLocal used for storing the query size during the request


lock

public void lock()
Lock this table

Specified by:
lock in interface Lockable
Overrides:
lock in class Table
See Also:
Lockable.lock()

generateExtraXMLAttributes

public void generateExtraXMLAttributes(PageState s,
                                       Element element)
Description copied from class: Table
Adds type-specific XML attributes to the XML element representing this link. Subclasses should override this method if they introduce more attributes than the ones generateXML produces by default.

Overrides:
generateExtraXMLAttributes in class Table
Parameters:
s - represents the current request
element - the XML element representing this table

globalize

public GlobalizedMessage globalize(String key)
Globalizes the specified key.


getResourceBundle

public String getResourceBundle()
Return the resource bundle for globalization, or null if no bundle was specified


setResourceBundle

public void setResourceBundle(String bundle)
Set the resource bundle for globalization, or null if no globalization is needed



Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 21 2004:2337 UTC