public class TableInfo extends GenericService
It represents one or more table columns and the sort direction associated with each column, which may be "ascending", "descending", or "none".
In addition to values of "ascending", "descending", or "none", callers can apply the values "toggle" (which switches between ascending and descending for a given property), "cycle_up" (which switches between none, ascending, and descending, in that order), and "cycle_down" (which switches between none, descending, and ascending, in that order).
Three additional values allow fine tuning the bahavior of sortable tables: "toggle_if_primary" toggles the sort direction if the property in question is currently the primary sort key, otherwise it sets the direction to the default value (normally "ascending") and makes it the primary sort key. The value "cycle_up_if_primary" behaves similarly, cycling the sort direction upward if the property is the primary sort key or setting it to the default value otherwise, while "cycle_down_if_primary" does the same thing cycling downward.
This makes it easy to build tables that have the common behavior where clicking on a column heading once makes that column the primary sort key with an ascending sort, clicking a second time reverses the order and sorts by descending values, and clicking a third time removes that column from the sort criteria.
Finally, this class includes convenience methods that generate strings suitable for use with the sortProperties parameter of droplets such as ForEach.
Defining Table Columns
You define the list of column names and the corresponding sort properties
for a table by specifying a value for the TableInfo's columns
property. The value of columns
is a Properties
object where each key is a column name, and the corresponding value is
a property expression to use when displaying and sorting on that column
in a ForEach-style droplet.
For example, a table displaying user information might configure the TableColumns by saying:
columns=\ First Name=firstName,\ Last Name=lastName,\ Login=login,\ City=mailingAddress.city
Note that subproperty expressions can be used in the table info. TableColumns does not make any attempt to interpret these property names, but simply uses them to construct sortProperties strings that may be passed to droplets like ForEach that implement sorting.
Separating the Display and Sort Properties
In most cases the property you wish to display in a table column is the same as the property on which you wish to sort that column, but in exceptional cases this may not be true.
In cases where the display property and the sort property are different you can list both property names, separated by a ; character, on the right hand side of a column specifier. For example, if the display property for a column is named "displayName" but you prefer to sort that column on a property named "sortableValue", you could specify the column settings as:
columns=\ Widget=displayName ; sortableValue,\ Price=listPrice
You can include optional whitespace before and after the ; to improve the readability of properties files.
Internationalization
Applications that support multiple locales will generally want to
localize the column headings displayed in their tables. The
optional columnHeadings
property allows you to map
column names to locale-specific display headings.
columnHeadings
is a dictionary whose keys are
locale-specific variants of a column name, and whose values are
the column headers to use for the corresponding locale.
TableInfo computes the headings for each column as follows:
If columnHeadings
has not been set, the column's
heading is the same as its name. This would typically be the
case in single-locale applications.
Otherwise, TableInfo first tries to determine the current locale using the following rules:
userLocale
property has been set, that
locale is selected.
ServletUtil.getCurrentRequest
is used
to identify the Dynamo servlet request being processed in the
current thread, and that request's locale is selected.
Once a locale is selected, TableInfo examines the keys in the
columnHeadings
dictionary looking for a locale-specific
variant of the column name. It applies the same logic as
java.util.ResourceBundle
when looking for
resource bundles. For example, if the column's name is "price"
and the locale is "fr_FR", TableInfo will search columnHeadings
for keys named price_fr_FR, price_fr, and price, in that
order. The value corresponding to the first matching key
becomes the column's heading. If no matching key is found,
the column's name is used as its heading.
Example:
This example demonstrates how to localize column headings of a two-column table for the English and French languages:
# Define the basic table layout, using symbolic names for each column columns=\ name=book.displayName,\ price=book.listPrice # Now create localized column headings for each column columnHeadings=\ name=Title,\ name_fr=Titre,\ price=List Price,\ price_fr=Prix Courant
(The example ignores the country and variant parts of the French locale, but country- and variant-specific column headings can be included by using entries like "name_fr_FR=Prix", etc.)
To support additional locales, all you need to do is add their
column headings to the columnHeadings
list.
Of course, you can also localize column headings without
using the columnHeadings
property, simply by defining
and configuring multiple instances of TableInfo, one for each
locale. Your JHTML or JSP pages can then refer explicitly to
the appropriate instance, based on the language of the page or
the user's locale. For example, an English-language page might
say
<importbean bean="/myapp/tables/en/ItemTable">
<importbean bean="/myapp/tables/de/ItemTable">
bean:ItemTable
, but each page would
use its own locale-specific version of the component.
Using the single-component approach and setting
columnHeadings
allows Dynamo to automatically
search for the best available match to the user's preferred
language and locale, but some people may find it easier to
manage a component per language and to forego automatic
selection of the column headings. Which approach you take
it largely a matter of personal preference.
Modifier and Type | Class and Description |
---|---|
class |
TableInfo.Column
Inner class that represents all the information about a table
column -- its name, column heading, the corresponding sort
property, the current sort direction, and the position of
this column's property relative to others when doing multi-column
sorting.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
ASCENDING |
static java.lang.String |
CLASS_VERSION |
static java.lang.String |
CYCLE_DOWN |
static java.lang.String |
CYCLE_DOWN_IF_PRIMARY |
static java.lang.String |
CYCLE_UP |
static java.lang.String |
CYCLE_UP_IF_PRIMARY |
static java.lang.String |
DESCENDING |
protected TableInfo.Column[] |
mColumns
mColumns is a list of Column objects in the order they were defined by tableInfo
|
protected java.lang.String |
mPrimarySortString |
protected java.util.LinkedList |
mSortColumns
mSortColumns is list that contains the same Column objects as
mColumns, but listed in the order in which the columns are sorted.
|
protected java.lang.String |
mSortString |
static java.lang.String |
NONE |
static java.lang.String |
TOGGLE |
static java.lang.String |
TOGGLE_IF_PRIMARY |
SERVICE_INFO_KEY
DEFAULT_LOG_TRACE_STATUS
DEFAULT_LOG_DEBUG_STATUS, DEFAULT_LOG_ERROR_STATUS, DEFAULT_LOG_INFO_STATUS, DEFAULT_LOG_WARNING_STATUS
Constructor and Description |
---|
TableInfo()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
protected void |
applyDirection(TableInfo.Column pColumn,
java.lang.String pDirectionType)
Set the sort direction for a property in the list of sort criteria.
|
protected void |
clearSortStrings()
Clear the cached sort strings returned by getPrimarySortString and
getSortString.
|
protected java.lang.String |
columnHeading(java.lang.String pName,
java.util.Locale pLocale)
Get the column heading to use for a column with the specified
name, to be displayed in the specified locale.
|
protected int |
cycleDown(int pDirection)
Return the direction code that results from cycling pDirection
from none -> descending -> ascending -> none.
|
protected int |
cycleUp(int pDirection)
Return the direction code that results from cycling pDirection
from none -> ascending -> descending -> none.
|
void |
doStartService()
Build the table column descriptors from the current table information
and column headings.
|
java.util.Properties |
getColumnHeadings()
Get the mapping from column names in the
columns
dictionary to localized display names for each column. |
java.lang.String |
getDefaultDirection()
Set the default sort direction for items when a sort direction is not
specified explicitly.
|
java.lang.String |
getDefaultPrimarySortString()
Get the default primary sort string for this table.
|
java.lang.String |
getDefaultSortString()
Get the default sort string for this table.
|
protected java.util.Locale |
getMessageLocale()
Get the locale to use when looking up display names for each column.
|
protected int |
getNextSortDirection(TableInfo.Column pColumn,
java.lang.String pDirectionType)
Return the direction that results from applying the requested
directionType transformation (ascending, descending, none, toggle,
cycle_up, cycle_down) to the specified Column.
|
TableInfo.Column |
getPrimarySortColumn()
Return the primary sort column for the table, or null if no
columns are being sorted.
|
java.lang.String |
getPrimarySortString()
Get a string suitable for use with the sortProperties parameter of
droplets like ForEach, representing the sort direction and property
name for the first entry in the list of sort criteria.
|
java.util.LinkedList |
getSortColumns()
Return the list of columns that are being sorted.
|
java.lang.String |
getSortString()
Get a string suitable for use with the sortProperties parameter of
droplets like ForEach, representing the sort direction and property
name for all entries in the list of sort criteria.
|
TableInfo.Column[] |
getTableColumns()
Return the array of objects that represent the columns in the table.
|
java.lang.String |
getUserLocale()
Get the locale used to retreive user-visible error messages, if
one has been set explicitly.
|
boolean |
isPrimarySortColumn(TableInfo.Column pColumn)
Return true if the specified Column is currently the primary
sort column.
|
protected java.lang.String |
makePrimarySortString()
Create a string suitable for use with the sortProperties parameter of
droplets like ForEach, representing the sort direction and property
name for the first entry in the list of sort criteria.
|
protected java.lang.String |
makeSortString()
Create a string suitable for use with the sortProperties parameter of
droplets like ForEach, representing the sort direction and property
name for all entries in the list of sort criteria.
|
void |
reset()
Clear the entire list of sort criteria.
|
void |
setColumnHeadings(java.util.Properties pColumnHeadings)
Define a mapping from column names in the
columns
dictionary to localized display names for each column. |
void |
setColumns(atg.core.util.OrderedProperties pTableInfo)
Set the list of column names and the corresponding sort properties
for a table.
|
void |
setDefaultDirection(java.lang.String pDefaultDirection)
Set the default sort direction for items when a sort direction is not
specified explicitly.
|
void |
setDefaultSortString(java.lang.String pDefaultSortString)
Set a default sort string for this table.
|
void |
setPrimarySortColumn(TableInfo.Column pColumn)
Make the specified column become the primary sort column.
|
void |
setReset(java.lang.String pIgnored)
Allow reset to be called from JHTML using
<setvalue bean="TableColumns.reset"> |
void |
setUserLocale(java.lang.String pUserLocale)
Set the locale used to retreive user-visible error messages.
|
protected int |
toggle(int pDirection)
Return the direction code that results from toggling pDirection.
|
protected boolean |
updatesPrimarySortColumn(java.lang.String pDirectionType)
Return true if the specified direction type is one of the
transition types that may update the primary sort column
(i.e., is one of toggle_if_primary, cycle_up_if_primary,
or cycle_down_if_primary)
|
addLogListener, createAdminServlet, doStopService, getAbsoluteName, getAdminServlet, getAdminServletOutputStreamEncoding, getLoggingForVlogging, getLogListenerCount, getLogListeners, getName, getNameContext, getNucleus, getRoot, getServiceConfiguration, getServiceInfo, isAdminServletUseServletOutputStream, isLoggingDebug, isLoggingError, isLoggingInfo, isLoggingTrace, isLoggingWarning, isRunning, logDebug, logDebug, logDebug, logError, logError, logError, logInfo, logInfo, logInfo, logTrace, logTrace, logTrace, logWarning, logWarning, logWarning, nameContextElementBound, nameContextElementUnbound, removeLogListener, reResolveThis, resolveName, resolveName, resolveName, resolveName, sendLogEvent, setAdminServletOutputStreamEncoding, setAdminServletUseServletOutputStream, setLoggingDebug, setLoggingError, setLoggingInfo, setLoggingTrace, setLoggingWarning, setNucleus, setServiceInfo, startService, stopService
vlogDebug, vlogDebug, vlogDebug, vlogDebug, vlogDebugTrace, vlogError, vlogError, vlogError, vlogError, vlogInfo, vlogInfo, vlogInfo, vlogInfo, vlogTrace, vlogTrace, vlogTrace, vlogTrace, vlogWarning, vlogWarning, vlogWarning, vlogWarning
public static java.lang.String CLASS_VERSION
protected TableInfo.Column[] mColumns
protected java.util.LinkedList mSortColumns
public static final java.lang.String ASCENDING
public static final java.lang.String DESCENDING
public static final java.lang.String NONE
public static final java.lang.String CYCLE_UP
public static final java.lang.String CYCLE_DOWN
public static final java.lang.String TOGGLE
public static final java.lang.String CYCLE_UP_IF_PRIMARY
public static final java.lang.String CYCLE_DOWN_IF_PRIMARY
public static final java.lang.String TOGGLE_IF_PRIMARY
protected java.lang.String mPrimarySortString
protected java.lang.String mSortString
public void setColumns(atg.core.util.OrderedProperties pTableInfo)
public void setColumnHeadings(java.util.Properties pColumnHeadings)
columns
dictionary to localized display names for each column. This feature is
used when creating TableInfo objects that support multiple locales.public java.util.Properties getColumnHeadings()
columns
dictionary to localized display names for each column.public void doStartService() throws ServiceException
doStartService
in class GenericService
ServiceException
- if the Service had a problem starting uppublic TableInfo.Column[] getTableColumns()
The columns are returned in the same order they were defined in
tableInfo
.
public java.util.LinkedList getSortColumns()
public void setDefaultDirection(java.lang.String pDefaultDirection) throws java.lang.IllegalArgumentException
java.lang.IllegalArgumentException
- if pDefaultDirection is not either "ascending" or "descending"public java.lang.String getDefaultDirection()
public void setDefaultSortString(java.lang.String pDefaultSortString)
getSortString
will return
defaultSortString
and calling
getPrimarySortString
will return the first comma-separated token from
defaultSortString
.
Examples:
If defaultSortString
is set to the string "+name",
calling getSortString will return "+name", as will calling
getPrimarySortString.
If defaultSortString
is set to the string
"+name,-price", calling getSortString will return "+name,-price",
but calling getPrimarySortString will return only "+name".
The value of defaultSortString
does not affect either the
sortColumns
property or the sort direction of any column.
In the absence of explicit sort directions, calling
getSortColumns()
will return an empty list, and asking for
the sort direction of any column will return none
, even if
that column appears in the default sort string.
public java.lang.String getDefaultSortString()
setDefaultSortString
public java.lang.String getDefaultPrimarySortString()
defaultSortString
is null or the empty
string, or consists of a single token, then the default primary
sort string will be the same as the default sort string. If
the default sort string consists of multiple comma-separated
tokens, the default primary sort string will be the first token
in the list.setDefaultSortString
public java.lang.String getPrimarySortString()
protected java.lang.String makePrimarySortString()
public java.lang.String getSortString()
protected java.lang.String makeSortString()
protected void clearSortStrings()
public void reset()
public void setReset(java.lang.String pIgnored)
<setvalue bean="TableColumns.reset">
protected void applyDirection(TableInfo.Column pColumn, java.lang.String pDirectionType)
pDirectionType
is
one of the transition types ("toggle_if_primary", "cycle_up_if_primary",
or "cycle_down_if_primary"), and will also recompute the relative
indices for all column.pColumn
- The column entry being modifiedpDirectionType
- The desired modification to the sort type, which may be any of the
following strings: ascending, descending, none, toggle, cycle_up,
cycle_down, toggle_if_primary, cycle_up_if_primary, or
cycle_down_if_primary.protected int getNextSortDirection(TableInfo.Column pColumn, java.lang.String pDirectionType)
protected int toggle(int pDirection)
protected int cycleUp(int pDirection)
protected int cycleDown(int pDirection)
protected boolean updatesPrimarySortColumn(java.lang.String pDirectionType)
public void setPrimarySortColumn(TableInfo.Column pColumn)
public TableInfo.Column getPrimarySortColumn()
public boolean isPrimarySortColumn(TableInfo.Column pColumn)
public void setUserLocale(java.lang.String pUserLocale)
public java.lang.String getUserLocale()
protected java.util.Locale getMessageLocale()
userLocale
property if
set, otherwise returns the request locale from the current Dynamo
servlet request if a request exists and its locale has been set,
otherwise returns the default server locale.
Subclasses may override this method to change the strategy for choosing a locale.
protected java.lang.String columnHeading(java.lang.String pName, java.util.Locale pLocale)