com.arsdigita.bebop
Class Table

java.lang.Object
  com.arsdigita.bebop.Completable
      com.arsdigita.bebop.SimpleComponent
          com.arsdigita.bebop.TextStylable
              com.arsdigita.bebop.BlockStylable
                  com.arsdigita.bebop.Table

All Implemented Interfaces:

BebopConstants, Cloneable, Component, Lockable

Direct Known Subclasses:

AbstractCollectionTable, CategoryTable, DataTable, DomainTable, Grid, PropertySheet

public class Table

extends BlockStylable

implements BebopConstants

Displays statically or dynamically generated data in tabular form. The data is retrieved from a TableModel.

This class is similar to the List class, but it has two dimensions. The table consists of a Table.MatrixTableModelBuilder, a TableColumnModel, a TableHeader and a TableCellRenderer for each column.

A table that represents a static matrix can be created fairly quickly:

 String[][] data = {
   {"Stas", "Freidin"},
   {"David", "Lutterkort"}
 };

 String[] headers = {"First Name", "Last Name"};

 Table myTable = new Table(data, headers);

However, tables are most often used to represent database queries, not static data. For these tables, the Table.MatrixTableModelBuilder class should be used to supply the Table class with data. The Table.MatrixTableModelBuilder class will execute the database query and return a TableModel, which wraps the query.

The content in the cells is rendered by the TableCellRenderer that is set for the TableColumn to which the cell belongs. If the TableCellRenderer has not been set, the TableCellRenderer for the Table is used. By default, the Table class uses an inactive instance of the DefaultTableCellRenderer (cell content is displayed as Labels). However, if an active DefaultTableCellRenderer is used, the cells in the table appear as links. When the user clicks a link, the Table's action listeners will be fired.

The currently selected cell is represented by two SingleSelectionModels - one model for the row and one model for the column. Typically, the selected row is identified by a string key and the selected column is identified by an integer.

Version:

$Id: //core-platform/dev/src/com/arsdigita/bebop/Table.java#12 $

Author:

David Lutterkort

See Also:

TableModel, TableColumnModel

Nested Class Summary

static class

Table.MatrixTableModelBuilder An internal class that creates a table model around a set of data given as a Object[][].

Field Summary

protected static String	CELL_EVENT The control event when the user selects one table cell.
static TableModel	EMPTY_MODEL A TableModel that has no rows.
protected static char	SEP
static String	versionId

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

Table()
Constructs a new, empty table.

Table(Object[][] data, Object[] headers)
Constructs a static table with the specified column headers, and pre-fills it with data.

Table(TableModelBuilder b, Object[] headers)
Constructs a table using a Table.MatrixTableModelBuilder.

Table(TableModelBuilder b, TableColumnModel c)
Constructs a table using a Table.MatrixTableModelBuilder.

Method Summary

void	addTableActionListener(TableActionListener l) Adds a TableActionListener to the table.
Iterator	children() Returns an iterator over the header and all the columns.
void	clearSelection(PageState s) Clears the row and column selection models that the table holds.
protected TableActionListener	createTableActionListener() Instantiates a new TableActionListener for this table.
protected void	fireCellSelected(PageState state, Object rowKey, Integer column) Fires event listeners to indicate that a new cell has been selected in the table.
protected void	fireHeadSelected(PageState state, Object rowKey, Integer column) Fires event listeners to indicate that a new header cell has been selected in the table.
protected void	generateExtraXMLAttributes(PageState state, Element element) Adds type-specific XML attributes to the XML element representing this link.
void	generateXML(PageState s, Element p) Generates the XML representing the table.
String	getBorder()
String	getCellPadding()
String	getCellSpacing()
TableColumn	getColumn(int i)
TableColumnModel	getColumnModel()
SingleSelectionModel	getColumnSelectionModel()
protected Component	getControler()
TableCellRenderer	getDefaultCellRenderer()
Component	getEmptyView()
TableHeader	getHeader()
TableModelBuilder	getModelBuilder()
SingleSelectionModel	getRowSelectionModel()
boolean	getStriped()
TableModel	getTableModel(PageState s) Returns the table model in effect for the request represented by the page state.
String	getWidth()
boolean	isSelectedCell(PageState s, Object rowKey, Object column) Determines whether the cell addressed by the specified row key and column number is selected in the request represented by the page state.
boolean	isSelectedColumn(PageState s, Object column) Determines whether a column is selected.
boolean	isSelectedRow(PageState s, Object rowKey) Determines whether a row is seleted.
void	lock() Locks the table against further modifications.
void	register(Page p) Registers the table with the containing page.
void	removeTableActionListener(TableActionListener l) Removes a TableActionListener from the table.
void	respond(PageState s) Processes the events for this table.
void	setBorder(String v)
void	setCellPadding(String v)
void	setCellSpacing(String v)
void	setColumn(int i, TableColumn v) Maps the colulumn at a new numerical index.
void	setColumnModel(TableColumnModel v) Sets a new TableColumnModel for the table.
void	setColumnSelectionModel(SingleSelectionModel v) Specifies the SingleSelectionModel that will be responsible for selecting the current column.
void	setDefaultCellRenderer(TableCellRenderer v) Specifies the default cell renderer.
void	setEmptyView(Component v) Sets the empty view.
void	setHeader(TableHeader v) Sets a new header for this table.
void	setModelBuilder(TableModelBuilder v) Sets a new Table.MatrixTableModelBuilder for the table.
void	setRowSelectionModel(SingleSelectionModel v) Specifies the SingleSelectionModel that will be responsible for selecting the current row.
void	setStriped(boolean striped)
void	setWidth(String v)

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

Field Detail

versionId

public static final String versionId

See Also:

Constant Field Values

CELL_EVENT

protected static final String CELL_EVENT

The control event when the user selects one table cell. This control event will only be used when

See Also:

Constant Field Values

SEP

protected static final char SEP

See Also:

Constant Field Values

EMPTY_MODEL

public static final TableModel EMPTY_MODEL

A TableModel that has no rows.

Constructor Detail

Table

public Table()

Constructs a new, empty table.

Table

public Table(Object[][] data,
             Object[] headers)

Constructs a static table with the specified column headers, and pre-fills it with data.

Parameters:

data - a matrix of objects that will serve as static data for the table cells

headers - an array of string labels for the table headers

Table

public Table(TableModelBuilder b,
             Object[] headers)

Constructs a table using a Table.MatrixTableModelBuilder. The table data will be generated dynamically during each request.

Parameters:

b - the Table.MatrixTableModelBuilder that is responsible for instantiating a TableModel during each request

headers - an array of string labels for the table headers

Table

public Table(TableModelBuilder b,
             TableColumnModel c)

Constructs a table using a Table.MatrixTableModelBuilder. The table data will be generated dynamically during each request. The table's columns and headers will be provided by a TableColumnModel.

Parameters:

b - the Table.MatrixTableModelBuilder that is responsible for instantiating a TableModel during each request

c - the TableColumnModel that will maintain the columns and headers for this table

Method Detail

addTableActionListener

public void addTableActionListener(TableActionListener l)

Adds a TableActionListener to the table. The listener is fired whenever a table cell is clicked.

Parameters:

l - the TableActionListener to be added

removeTableActionListener

public void removeTableActionListener(TableActionListener l)

Removes a TableActionListener from the table.

Parameters:

l - the TableActionListener to be removed

fireCellSelected

protected void fireCellSelected(PageState state,
                                Object rowKey,
                                Integer column)

Fires event listeners to indicate that a new cell has been selected in the table.

Parameters:

state - the page state

rowKey - the key that identifies the selected row

column - the integer index of the selected column

fireHeadSelected

protected void fireHeadSelected(PageState state,
                                Object rowKey,
                                Integer column)

Fires event listeners to indicate that a new header cell has been selected in the table.

Parameters:

state - the page state

rowKey - the key that identifies the selected row

column - the integer index of the selected column

createTableActionListener

protected TableActionListener createTableActionListener()

Instantiates a new TableActionListener for this table.

Returns:

a new TableActionListener that should be used only for this table.

getColumnModel

public final TableColumnModel getColumnModel()

Returns:

the TableColumnModel for this table.

setColumnModel

public void setColumnModel(TableColumnModel v)

Sets a new TableColumnModel for the table.

Parameters:

v - the new TableColumnModel

getModelBuilder

public final TableModelBuilder getModelBuilder()

Returns:

the Table.MatrixTableModelBuilder for this table.

setModelBuilder

public void setModelBuilder(TableModelBuilder v)

Sets a new Table.MatrixTableModelBuilder for the table.

Parameters:

v - the new Table.MatrixTableModelBuilder

getHeader

public final TableHeader getHeader()

Returns:

the TableHeader for this table. Could return null if the header is hidden.

setHeader

public void setHeader(TableHeader v)

Sets a new header for this table.

Parameters:

v - the new header for this table. If null, the header will be hidden.

getColumn

public TableColumn getColumn(int i)

Parameters:

i - the numerical index of the column

Returns:

the TableColumn whose index is i.

setColumn

public void setColumn(int i,
                      TableColumn v)

Maps the colulumn at a new numerical index. This method is normally used to rearrange the order of the columns in the table.

Parameters:

i - the numerical index of the column

v - the column that is to be mapped at i

getRowSelectionModel

public final SingleSelectionModel getRowSelectionModel()

Returns:

the SingleSelectionModel that is responsible for selecting the current row.

setRowSelectionModel

public void setRowSelectionModel(SingleSelectionModel v)

Specifies the SingleSelectionModel that will be responsible for selecting the current row.

Parameters:

v - a SingleSelectionModel

getColumnSelectionModel

public SingleSelectionModel getColumnSelectionModel()

Returns:

the SingleSelectionModel that is responsible for selecting the current column.

setColumnSelectionModel

public void setColumnSelectionModel(SingleSelectionModel v)

Specifies the SingleSelectionModel that will be responsible for selecting the current column.

Parameters:

v - a SingleSelectionModel

clearSelection

public void clearSelection(PageState s)

Clears the row and column selection models that the table holds.

Parameters:

s - represents the state of the current request

getDefaultCellRenderer

public final TableCellRenderer getDefaultCellRenderer()

Returns:

the default TableCellRenderer.

setDefaultCellRenderer

public final void setDefaultCellRenderer(TableCellRenderer v)

Specifies the default cell renderer. This renderer will be used to render columns that do not specify their own TableCellRenderer.

Parameters:

v - the default TableCellRenderer

getEmptyView

public final Component getEmptyView()

Returns:

the component that will be shown if the table is empty.

setEmptyView

public final void setEmptyView(Component v)

Sets the empty view. The empty view is the component that is shown if the table is empty. Usually, the component will be a simple label, such as new Label("The table is empty").

Parameters:

v - a Bebop component

getWidth

public String getWidth()

Returns:

the HTML width of the table.

setWidth

public void setWidth(String v)

Parameters:

v - the HTML width of the table

getBorder

public String getBorder()

Returns:

the HTML border of the table.

setBorder

public void setBorder(String v)

Parameters:

v - the HTML border of the table

getCellSpacing

public String getCellSpacing()

setCellSpacing

public void setCellSpacing(String v)

Parameters:

v - the HTML width of the table

getCellPadding

public String getCellPadding()

Returns:

the HTML cell spacing of the table.

setCellPadding

public void setCellPadding(String v)

Parameters:

v - the HTML cell padding of the table

respond

public void respond(PageState s)
             throws javax.servlet.ServletException

Processes the events for this table. This method will automatically handle all user input to the table.

Specified by:

respond in interface Component

Overrides:

respond in class SimpleComponent

Parameters:

s - the page state

Throws:

javax.servlet.ServletException

register

public void register(Page p)

Registers the table with the containing page. The table will add the state parameters of the row and column selection models, if they use them, thus making the selection persist between requests.

Specified by:

register in interface Component

Overrides:

register in class SimpleComponent

Parameters:

p - the page that contains this table

children

public Iterator children()

Returns an iterator over the header and all the columns. If the table has no header, the iterator lists only the columns.

Specified by:

children in interface Component

Overrides:

children in class SimpleComponent

Returns:

an iterator over Bebop components.

isSelectedRow

public boolean isSelectedRow(PageState s,
                             Object rowKey)

Determines whether a row is seleted.

Parameters:

s - the page state

rowKey - the key that identifies the row

Returns:

true if the row is currently selected; false otherwise.

isSelectedColumn

public boolean isSelectedColumn(PageState s,
                                Object column)

Determines whether a column is selected.

Parameters:

s - the page state

column - a key that identifes the column. Should be consistent with the type used by the column selection model.

Returns:

true if the column is selected; false otherwise.

isSelectedCell

public boolean isSelectedCell(PageState s,
                              Object rowKey,
                              Object column)

Determines whether the cell addressed by the specified row key and column number is selected in the request represented by the page state.

Parameters:

s - represents the state of the page in the current request

rowKey - the row key of the cell. The concrete type should agree with the type used by the row selection model.

column - the column of the cell. The concrete type should agree with the type used by the column selection model.

Returns:

true if the cell is selected; false otherwise.

setStriped

public void setStriped(boolean striped)

getStriped

public boolean getStriped()

generateExtraXMLAttributes

protected void generateExtraXMLAttributes(PageState state,
                                          Element element)

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.

Parameters:

state - represents the current request

element - the XML element representing this table

generateXML

public void generateXML(PageState s,
                        Element p)

Generates the XML representing the table. Gets a new TableModel from the Table.MatrixTableModelBuilder and iterates over the model's rows. The value in each table cell is rendered with the help of the column's table cell renderer.

Generates an XML fragment:

 <bebop:table>
   <bebop:thead>
     <bebpp:cell>...</cell> ...
   </bebop:thead>
   <bebop:tbody>
     <bebop:trow>
       <bebpp:cell>...</cell> ...
     </bebop:trow>
       ...
   </bebop:tbody>
 </bebop:table>


Specified by:
generateXML in interface Component
Overrides:
generateXML in class SimpleComponent


Parameters:
s - the page state
p - the parent Element

getControler

protected Component getControler()

getTableModel

public TableModel getTableModel(PageState s)

Returns the table model in effect for the request represented by the page state.

Parameters:

s - represents the state of the page in the current request

Returns:

the table model used for outputting the table.

lock

public void lock()

Locks the table against further modifications. This also locks all the associated objects: the model builder, the column model, and the header components.

Specified by:

lock in interface Lockable

Overrides:

lock in class SimpleComponent

See Also:

Lockable.lock()