com.arsdigita.acs.html
Class Table

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

public class Table
extends Object

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


Field Summary
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
           
static int SORT_CUSTOM
           
static int SORT_DEFAULT
           
static int SORT_NO_SORT
           
 
Constructor Summary
Table()
          Default constructor to make it easier to create an anonymous subclass
Table(PageContext pc)
          Public constructor
 
Method Summary
 void addColumn(String columnId, String headerText, int sortInfo, int displayInfo)
          Adds a new column to the table.
 void formatCell(StringBuffer sb, String columnId, DataSource 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(StringBuffer sb, String columnId, String order)
          Called from the orderByFromSortSpec method for columns whose sortInfo parameter has been set to SORT_CUSTOM.
 String getHtml()
          Iterates through the DataSource to generate an html table.
static void main(String[] args)
           
 String newSortSpec(String columnId, String orderby)
          Makes a new orderby string, sorting by columnId.
 String orderByFromSortSpec()
          Translates the "orderby" URL parameter into a SQL ORDER BY clause that may be inserted into a query.
 void setAscOrderImg(String ascOrderImg)
          This string may contain an icon to display next to the table header which is currently sorted in ascending order.
 void setBandColors(String[] bandColors)
          Each row in the table will be displayed with alternating colors from this array.
 void setDataSource(DataSource ds)
          Sets the dataSource property used by the table to retrieve data.
 void setDescOrderImg(String descOrderImg)
          This string may contain an icon to display next to the table header which is currently sorted in descending order.
 void setHeaderRowExtra(String headerRowExtra)
          This string may contain any attributes to add to the <th> tag.
 void setMaxRows(Integer maxRows)
          Specifies the maximum number of rows to display in the table.
 void setMissingText(String missingText)
          Message to display when the DataSource is empty.
 void setOrderby(String orderby)
          This is the variable that specifies the last sort column that was clicked.
 void setOrderTargetUrl(String orderTargetUrl)
          The url linked by the table header tags, meant to sort the table on a different column.
 void setPageContext(PageContext pc)
          Sets the JSP Page Context for the current request.
 void setRowsPerBand(Integer rowsPerBand)
          How many rows to display within a single color band.
 void setRowsPerPage(Integer rowsPerPage)
          Breaks up the display into multiple <table> tags.
 void setTableBreakHtml(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(String tableExtraHtml)
          This string may contain any attributes to add to the <table> tag.
 String toString()
           
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

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()
Default constructor to make it easier to create an anonymous subclass

Table

public Table(PageContext pc)
      throws ACSException
Public constructor
Parameters:
pc - the pageContext for the current request
Method Detail

setPageContext

public void setPageContext(PageContext pc)
                    throws ACSException
Sets the JSP Page Context for the current request. The Table object requires this in order to get the orderby URL variable and the URL of the current page request.

addColumn

public final void addColumn(String columnId,
                            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(DataSource ds)
Sets the dataSource property used by the table to retrieve data.
Parameters:
ds - the data this table should display. Most commonly obtained via the <ad:db_query> custom tag. 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 String toString()
Overrides:
toString in class Object

getHtml

public final String getHtml()
                     throws ACSException,
                            DataSourceException
Iterates through the DataSource to generate an html table.

formatCell

public void formatCell(StringBuffer sb,
                       String columnId,
                       DataSource 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

newSortSpec

public String newSortSpec(String columnId,
                          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.

orderByFromSortSpec

public String orderByFromSortSpec()
                           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

formatSortClause

public void formatSortClause(StringBuffer sb,
                             String columnId,
                             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.

setOrderTargetUrl

public void setOrderTargetUrl(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(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(Integer rowsPerBand)
How many rows to display within a single color band. Set to 1 by default.

setOrderby

public void setOrderby(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(String tableExtraHtml)
This string may contain any attributes to add to the <table> tag.

setHeaderRowExtra

public void setHeaderRowExtra(String headerRowExtra)
This string may contain any attributes to add to the <th> tag.

setAscOrderImg

public void setAscOrderImg(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(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(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(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(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(String missingText)
Message to display when the DataSource is empty.

main

public static void main(String[] args)
                 throws Exception