com.arsdigita.acs.html
Class Table

java.lang.Object
  |
  +--com.arsdigita.acs.html.Table

public class Table

extends java.lang.Object

Displays database query results in an html table, with automatic sorting functionality.

Field Summary

protected java.lang.String	ascOrderImg
protected java.lang.String[]	bandColors
protected java.util.Vector	columns
protected java.lang.String	descOrderImg
static int	DISPLAY_CENTER
static int	DISPLAY_CUSTOM
static int	DISPLAY_DEFAULT
static int	DISPLAY_LEFT
static int	DISPLAY_RIGHT
static int	DISPLAY_TRUE_OR_FALSE
static int	DISPLAY_ZERO_OR_ONE
protected MultiDataSource	ds
protected java.lang.String	extraRowsHtml
protected java.lang.String	headerRowExtra
protected int	maxRows
protected java.lang.String	missingText
protected java.lang.String	orderby
protected java.lang.String	orderTargetUrl
protected org.apache.oro.text.perl.Perl5Util	re
protected int	rowsPerBand
protected int	rowsPerPage
static int	SORT_CUSTOM
static int	SORT_DEFAULT
static int	SORT_NO_SORT
protected java.lang.String	tableBreakHtml
protected java.lang.String	tableExtraHtml

Constructor Summary

Table()
Public constructor.

Table(java.lang.String orderby)
Public constructor

Method Summary

void	addColumn(java.lang.String columnId, java.lang.String headerText, int sortInfo, int displayInfo) Adds a new column to the table.
void	formatCell(java.lang.StringBuffer sb, java.lang.String columnId, MultiDataSource ds) For columns whose displayInfo parameter is set to CUSTOM, this method is called so that subclasses can generate a display different from what is possible with the default displays.
void	formatSortClause(java.lang.StringBuffer sb, java.lang.String columnId, java.lang.String order) Called from the orderByFromSortSpec method for columns whose sortInfo parameter has been set to SORT_CUSTOM.
java.lang.String	getHtml() Iterates through the DataSource to generate an html table.
com.arsdigita.db.SqlFragment	getOrderByFromSortSpec() Translates the "orderby" URL parameter into a SQL ORDER BY clause that may be inserted into a query.
void	setAscOrderImg(java.lang.String ascOrderImg) This string may contain an icon to display next to the table header which is currently sorted in ascending order.
void	setBandColors(java.lang.String[] bandColors) Each row in the table will be displayed with alternating colors from this array.
void	setDataSource(MultiDataSource ds) Sets the dataSource property used by the table to retrieve data.
void	setDescOrderImg(java.lang.String descOrderImg) This string may contain an icon to display next to the table header which is currently sorted in descending order.
void	setExtraRowsHtml(java.lang.String extraRowsHtml) This string may contain any attributes to add after the last row, before the table is closed.
void	setHeaderRowExtra(java.lang.String headerRowExtra) This string may contain any attributes to add to the <th> tag.
void	setMaxRows(java.lang.Integer maxRows) Specifies the maximum number of rows to display in the table.
void	setMissingText(java.lang.String missingText) Message to display when the DataSource is empty.
java.lang.String	setNewSortSpec(java.lang.String columnId, java.lang.String orderby) Makes a new orderby string, sorting by columnId.
void	setOrderby(java.lang.String orderby) This is the variable that specifies the last sort column that was clicked.
void	setOrderTargetUrl(java.lang.String orderTargetUrl) The url linked by the table header tags, meant to sort the table on a different column.
void	setRowsPerBand(java.lang.Integer rowsPerBand) How many rows to display within a single color band.
void	setRowsPerPage(java.lang.Integer rowsPerPage) Breaks up the display into multiple <table> tags.
void	setTableBreakHtml(java.lang.String tableBreakHtml) Specifies the html to use between </table> and the next <table>, when breaking the display into multiple tables using the rowsPerPage property.
void	setTableExtraHtml(java.lang.String tableExtraHtml) This string may contain any attributes to add to the <table> tag.
java.lang.String	toString() Converts this table to an HTML fragment.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ds

protected MultiDataSource ds

columns

protected java.util.Vector columns

re

protected org.apache.oro.text.perl.Perl5Util re

orderTargetUrl

protected java.lang.String orderTargetUrl

orderby

protected java.lang.String orderby

bandColors

protected java.lang.String[] bandColors

rowsPerBand

protected int rowsPerBand

tableExtraHtml

protected java.lang.String tableExtraHtml

headerRowExtra

protected java.lang.String headerRowExtra

extraRowsHtml

protected java.lang.String extraRowsHtml

ascOrderImg

protected java.lang.String ascOrderImg

descOrderImg

protected java.lang.String descOrderImg

maxRows

protected int maxRows

rowsPerPage

protected int rowsPerPage

tableBreakHtml

protected java.lang.String tableBreakHtml

missingText

protected java.lang.String missingText

DISPLAY_DEFAULT

public static final int DISPLAY_DEFAULT

DISPLAY_LEFT

public static final int DISPLAY_LEFT

DISPLAY_RIGHT

public static final int DISPLAY_RIGHT

DISPLAY_CENTER

public static final int DISPLAY_CENTER

DISPLAY_TRUE_OR_FALSE

public static final int DISPLAY_TRUE_OR_FALSE

DISPLAY_ZERO_OR_ONE

public static final int DISPLAY_ZERO_OR_ONE

DISPLAY_CUSTOM

public static final int DISPLAY_CUSTOM

SORT_DEFAULT

public static final int SORT_DEFAULT

SORT_NO_SORT

public static final int SORT_NO_SORT

SORT_CUSTOM

public static final int SORT_CUSTOM

Constructor Detail

Table

public Table()

Public constructor. orderby is pulled from the form, if it is available.

Table

public Table(java.lang.String orderby)

Public constructor

Method Detail

formatSortClause

public void formatSortClause(java.lang.StringBuffer sb,
                             java.lang.String columnId,
                             java.lang.String order)

Called from the orderByFromSortSpec method for columns whose sortInfo parameter has been set to SORT_CUSTOM.

Parameters:

sb - Contains the ORDER BY clause that orderByFromSortSpec is generating. You should append your custom sort expression to this StringBuffer.

columnId - The column for which to provide custom sort information.

order - Either "desc" or "asc", according to the current state of the orderby URL parameter.

formatCell

public void formatCell(java.lang.StringBuffer sb,
                       java.lang.String columnId,
                       MultiDataSource ds)
                throws DataSourceException

For columns whose displayInfo parameter is set to CUSTOM, this method is called so that subclasses can generate a display different from what is possible with the default displays.

Parameters:

sb - Generate output by calling append on this StringBuffer.

columnId - the column in the DataSource we want to display

ds - the DataSource we are in the process of displaying

addColumn

public final void addColumn(java.lang.String columnId,
                            java.lang.String headerText,
                            int sortInfo,
                            int displayInfo)
                     throws ACSException

Adds a new column to the table.

Parameters:

columnId - The column name to get from the DataSource. Also used to set orderby for sorting.

headerText - The text to be wrapped in <th> and </th> tags.

sortInfo - Specifies the way sorting works for this column. Choose from one of the SORT_* constants defined in this class. If CUSTOM is specified, the formatOrderByClause method will be called to allow customization.

displayInfo - Specifies the way column values are to be displayed. Choose from one of the DISPLAY_* constants defined in this class. If CUSTOM is specified, the formatCell method will be called to display values in this column. See the docs for the formatCell method for further information.

Throws:

ACSException - if the dataSource property has already been set.

setDataSource

public void setDataSource(MultiDataSource ds)

Sets the dataSource property used by the table to retrieve data.

Parameters:

ds - the data this table should display. You should create the table and set up its column definitions before specifying the query, so that the table's orderByFromSortSpec method can be used to limit the query.

toString

public java.lang.String toString()

Converts this table to an HTML fragment.

Overrides:

toString in class java.lang.Object

getHtml

public java.lang.String getHtml()
                         throws ACSException,
                                DataSourceException

Iterates through the DataSource to generate an html table.

setNewSortSpec

public java.lang.String setNewSortSpec(java.lang.String columnId,
                                       java.lang.String orderby)

Makes a new orderby string, sorting by columnId. If the key is followed by "*", that indicates the ordering should be reversed from the default ordering for that key. Old sort keys are retained, so the sort appears to be a little more stable. That is, suppose two things are sorted into an order, and their values for a different column are the same. If that different column is used as the primary sort key to reorder, the things which have the same value for the newly-sorted column will remain in the same relative order.

getOrderByFromSortSpec

public com.arsdigita.db.SqlFragment getOrderByFromSortSpec()
                                                    throws ACSException

Translates the "orderby" URL parameter into a SQL ORDER BY clause that may be inserted into a query. If a column has SORT_CUSTOM specified for its sortInfo parameter, the formatSortClause method will be called to generate the custom sort clause.

Throws:

ACSException - if pageContext has not been set

setOrderTargetUrl

public void setOrderTargetUrl(java.lang.String orderTargetUrl)

The url linked by the table header tags, meant to sort the table on a different column. Defaults to the current request's URL.

setBandColors

public void setBandColors(java.lang.String[] bandColors)

Each row in the table will be displayed with alternating colors from this array. If a String in the array is empty, no bgcolor attribute will be given for the row, so it will be displayed with the page's background color. By default we band with the background color (typically white) and gray. If you wish to disable banding entirely, set bandColors to null.

setRowsPerBand

public void setRowsPerBand(java.lang.Integer rowsPerBand)

How many rows to display within a single color band. Set to 1 by default.

setOrderby

public void setOrderby(java.lang.String orderby)

This is the variable that specifies the last sort column that was clicked. By default, we look for a form variable named "orderby".

setTableExtraHtml

public void setTableExtraHtml(java.lang.String tableExtraHtml)

This string may contain any attributes to add to the <table> tag.

setExtraRowsHtml

public void setExtraRowsHtml(java.lang.String extraRowsHtml)

This string may contain any attributes to add after the last row, before the table is closed. The string should include <tr> and </tr> tags as needed.

setHeaderRowExtra

public void setHeaderRowExtra(java.lang.String headerRowExtra)

This string may contain any attributes to add to the <th> tag.

setAscOrderImg

public void setAscOrderImg(java.lang.String ascOrderImg)

This string may contain an icon to display next to the table header which is currently sorted in ascending order. By default we use the string "v".

setDescOrderImg

public void setDescOrderImg(java.lang.String descOrderImg)

This string may contain an icon to display next to the table header which is currently sorted in descending order. By default we use the string "^".

setMaxRows

public void setMaxRows(java.lang.Integer maxRows)

Specifies the maximum number of rows to display in the table. Set to 0 by default, which means "display everything".

setRowsPerPage

public void setRowsPerPage(java.lang.Integer rowsPerPage)

Breaks up the display into multiple <table> tags. Useful if displaying a large amount of data because the browser can render the first page without waiting for the rest to download. Set to 0 by default, which disables the table breaking mechanism.

setTableBreakHtml

public void setTableBreakHtml(java.lang.String tableBreakHtml)

Specifies the html to use between </table> and the next <table>, when breaking the display into multiple tables using the rowsPerPage property. Set to <p> by default.

setMissingText

public void setMissingText(java.lang.String missingText)

Message to display when the DataSource is empty.