net.sf.click.control
Class Column

java.lang.Object
  net.sf.click.control.Column

All Implemented Interfaces:

Serializable

public class Column

extends Object

implements Serializable

Provides the Column table data <td> and table header <th> renderer.

Id	Name	Category	Action
834501	Alison Smart	Residential Property	View
238454	Angus Robins	Bonds	View
784191	Ann Melan	Residential Property	View

The Column object provide column definitions for the Table object.

Column Options

The Column class supports a number of rendering options which include:

• autolink - the option to automatically render href links for email and URL column values
• attributes - the CSS style attributes for the table data cell
• dataClass - the CSS class for the table data cell
• dataStyles - the CSS styles for the table data cell
• decorator - the custom column value renderer
• format - the MessageFormat pattern rendering the column value
• headerClass - the CSS class for the table header cell
• headerStyles - the CSS styles for the table header cell
• headerTitle - the table header cell value to render
• sortable - the table column sortable property
• width - the table cell width property

Format Pattern

The format property which specifies MessageFormat pattern a is very useful for formatting column values. For example to render formatted number and date values you simply specify:

 Table table = new Table("table");
 table.setClass("isi");

 Column idColumn = new Column("purchaseId", "ID");
 idColumn.setFormat("{0,number,#,###}");
 table.addColumn(idColumn);

 Column priceColumn = new Column("purchasePrice", "Price");
 priceColumn.setFormat("{0,number,currency}");
 priceColumn.setTextAlign("right");
 table.addColumn(priceColumn);

 Column dateColumn = new Column("purchaseDate", "Date");
 dateColumn.setFormat("{0,date,dd MMM yyyy}");
 table.addColumn(dateColumn);

 Column orderIdColumn = new Column("order.id", "Order ID");
 table.addColumn(orderIdColumn);  

Column Decorators

The support custom column value rendering you can specify a Decorator class on columns. The decorator render method is passed the table row object and the page request Context. Using the table row you can access all the column values enabling you to render a compound value composed of multiple column values. For example:

 Column column = new Column("email");

 column.setDecorator(new Decorator() {
     public String render(Object row, Context context) {
         Person person = (Person) row;
         String email = person.getEmail();
         String fullName = person.getFullName();
         return "<a href='mailto:" + email + "'>" + fullName + "</a>";
     }
 });

 table.addColumn(column); 

The Context parameter of the decorator render() method enables you to render controls to provide additional functionality. For example:

 public class CustomerList extends BorderedPage {

     private Table table = new Table("table");
     private ActionLink viewLink = new ActionLink("view");

     public CustomerList() {

         viewLink.setListener(this, "onViewClick");
         viewLink.setLabel("View");
         viewLink.setAttribute("title", "View customer details");
         table.addControl(viewLink);

         table.addColumn(new Column("id"));
         table.addColumn(new Column("name"));
         table.addColumn(new Column("category"));

         Column column = new Column("Action");
         column.setDecorator(new Decorator() {
             public String render(Object row, Context context) {
                 Customer customer = (Customer) row;
                 viewLink.setValue("" + customer.getId());

                 return viewLink.toString();
             }
          });
         table.addColumn(column);

         addControl(table);
     }

     public boolean onViewClick() {
         String path = getContext().getPagePath(Logout.class);
         setRedirect(path + "?id=" + viewLink.getValue());
         return true;
     }
 } 

Internationalization

Column header titles can be localized using the controls parent messages. If the column header title value is null, the column will attempt to find a localized message in the parent messages using the key:

getName() + ".headerTitle"

If not found then the message will be looked up in the /click-control.properties file using the same key. If a value still cannot be found then the Column name will be converted into a header title using the method: ClickUtils.toLabel(String).

Author:

Malcolm Edgar

See Also:

Decorator, Table, Serialized Form

Field Summary

protected Map	attributes The Column attributes Map.
protected boolean	autolink The automatically hyperlink column URL and email address values flag, default value is false.
protected String	dataClass The column table data <td> CSS class attribute.
protected Map	dataStyles The Map of column table data <td> CSS style attributes.
protected Decorator	decorator The column row decorator.
protected boolean	escapeHtml The escape HTML characters flag.
protected String	format The column message format pattern.
protected String	headerClass The CSS class attribute of the column header.
protected Map	headerStyles The Map of column table header <th> CSS style attributes.
protected String	headerTitle The title of the column header.
protected int	maxLength The maximum column length.
protected MessageFormat	messageFormat The optional MessageFormat used to render the column table cell value.
protected Map	methodCache The method cached for rendering column values.
protected String	name The property name of the row object to render.
protected Boolean	renderId The column render id attribute status.
protected Boolean	sortable The column sortable status.
protected Table	table The parent Table.
protected String	titleProperty The property name used to populate the <td> "title" attribute.
protected String	width The column HTML <td> width attribute.

Constructor Summary

Column()
Create a Column with no name defined.

Column(String name)
Create a table column with the given property name.

Column(String name, String title)
Create a table column with the given property name and header title.

Method Summary

String	getAttribute(String name) Return the Column HTML attribute with the given name, or null if the attribute does not exist.
Map	getAttributes() Return the Column attributes Map.
boolean	getAutolink() Return the flag to automatically render HTML hyperlinks for column URL and email addresses values.
Comparator	getComparator() Return the column comparator object, which is used to sort column row values.
String	getDataClass() Return the table data <td> CSS class.
String	getDataStyle(String name) Return the table data <td> CSS style.
Map	getDataStyles() Return the Map of table data <td> CSS styles.
Decorator	getDecorator() Return the row column <td> decorator.
boolean	getEscapeHtml() Return true if the HTML characters will be escaped when rendering the column data.
String	getFormat() Return the row column message format pattern.
String	getHeaderClass() Return the table header <th> CSS class.
String	getHeaderStyle(String name) Return the table header <th> CSS style.
Map	getHeaderStyles() Return the Map of table header <th> CSS styles.
String	getHeaderTitle() Return the table header <th> title.
String	getId() Return the Table and Column id appended: "table-column" Use the field the "id" attribute value if defined, or the name otherwise.
int	getMaxLength() The maximum column length.
MessageFormat	getMessageFormat() Return the MessageFormat instance used to format the table cell value.
String	getName() Return the property name.
Object	getProperty(Object row) Return the column name property value from the given row object.
Object	getProperty(String name, Object row) Return the column property value from the given row object and property name.
boolean	getRenderId() Returns the column render id attribute status.
boolean	getSortable() Return the column sortable status.
Table	getTable() Return the parent Table containing the Column.
String	getTitleProperty() Return the property name used to populate the <td> "title" attribute.
String	getWidth() Return the column HTML <td> width attribute.
boolean	hasAttributes() Return true if the Column has attributes or false otherwise.
boolean	hasDataStyles() Return true if table data <td> CSS styles are defined.
boolean	hasHeaderStyles() Return true if table header <th> CSS styles are defined.
protected boolean	renderLink(Object value, HtmlStringBuffer buffer) Render the given table cell value to the buffer as a mailto: or http: hyperlink, or as an ordinary string if the value is determined not be linkable.
void	renderTableData(Object row, HtmlStringBuffer buffer, Context context, int rowIndex) Render the column table data <td> element to the given buffer using the passed row object.
protected void	renderTableDataContent(Object row, HtmlStringBuffer buffer, Context context, int rowIndex) Render the content within the column table data <td> element.
void	renderTableHeader(HtmlStringBuffer buffer, Context context) Render the column table header <tr> element to the given buffer.
void	setAttribute(String name, String value) Set the Column with the given HTML attribute name and value.
void	setAutolink(boolean autolink) Set the flag to automatically render HTML hyperlinks for column URL and email addresses values.
void	setComparator(Comparator comparator) Set the column comparator object, which is used to sort column row values.
void	setDataClass(String dataClass) Set the table data <td> CSS class.
void	setDataStyle(String name, String value) Set the table data <td> CSS style name and value pair.
void	setDecorator(Decorator decorator) Set the row column <td> decorator.
void	setEscapeHtml(boolean escape) Set the escape HTML characters when rendering column data flag.
void	setFormat(String pattern) Set the row column message format pattern.
void	setHeaderClass(String headerClass) Set the table header <th> CSS class.
void	setHeaderStyle(String name, String value) Set the table header <th> CSS style name and value pair.
void	setHeaderTitle(String title) Set the table header <th> title.
void	setMaxLength(int value) Set the maximum column length.
void	setMessageFormat(MessageFormat messageFormat) Set the MessageFormat instance used to format the table cell value.
void	setName(String name) Set the property name.
void	setRenderId(boolean value) Set the column render id attribute status.
void	setSortable(boolean value) Set the column sortable status.
void	setTable(Table table) Set the Column's the parent Table.
void	setTextAlign(String align) Set the column CSS "text-align" style for the header <th> and data <td> elements.
void	setTitleProperty(String property) Set the property name used to populate the <td> "title" attribute.
void	setVerticalAlign(String align) Set the column CSS "vertical-align" style for the header <th> and data <td> elements.
void	setWidth(String value) Set the column HTML <td> width attribute.

Methods inherited from class java.lang.Object

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

Field Detail

attributes

protected Map attributes

The Column attributes Map.

autolink

protected boolean autolink

The automatically hyperlink column URL and email address values flag, default value is false.

dataClass

protected String dataClass

The column table data <td> CSS class attribute.

dataStyles

protected Map dataStyles

The Map of column table data <td> CSS style attributes.

decorator

protected Decorator decorator

The column row decorator.

escapeHtml

protected boolean escapeHtml

The escape HTML characters flag. The default value is true.

format

protected String format

The column message format pattern.

headerClass

protected String headerClass

The CSS class attribute of the column header.

headerStyles

protected Map headerStyles

The Map of column table header <th> CSS style attributes.

headerTitle

protected String headerTitle

The title of the column header.

maxLength

protected int maxLength

The maximum column length. If maxLength is greater than 0 and the column data string length is greater than maxLength, the rendered value will be truncated with an eclipse(...).

Autolinked email or URL values will not be constrained.

The default value is 0.

messageFormat

protected MessageFormat messageFormat

The optional MessageFormat used to render the column table cell value.

name

protected String name

The property name of the row object to render.

renderId

protected Boolean renderId

The column render id attribute status. The default value is false.

methodCache

protected transient Map methodCache

The method cached for rendering column values.

sortable

protected Boolean sortable

The column sortable status. The default value is false.

table

protected Table table

The parent Table.

titleProperty

protected String titleProperty

The property name used to populate the <td> "title" attribute. The default value is null.

width

protected String width

The column HTML <td> width attribute.

Constructor Detail

Column

public Column(String name)

Create a table column with the given property name. The table header title will be set as the capitalized property name.

Parameters:

name - the name of the property to render

Column

public Column(String name,
              String title)

Create a table column with the given property name and header title.

Parameters:

name - the name of the property to render

title - the column header title to render

Column

public Column()

Create a Column with no name defined.

Please note the control's name must be defined before it is valid.

Method Detail

getAttribute

public String getAttribute(String name)

Return the Column HTML attribute with the given name, or null if the attribute does not exist.

Parameters:

name - the name of column HTML attribute

Returns:

the Column HTML attribute

setAttribute

public void setAttribute(String name,
                         String value)

Set the Column with the given HTML attribute name and value. These attributes will be rendered as HTML attributes, for example:

If there is an existing named attribute in the Column it will be replaced with the new value. If the given attribute value is null, any existing attribute will be removed.

Parameters:

name - the name of the column HTML attribute

value - the value of the column HTML attribute

Throws:

IllegalArgumentException - if attribute name is null

getAttributes

public Map getAttributes()

Return the Column attributes Map.

Returns:

the column attributes Map.

hasAttributes

public boolean hasAttributes()

Return true if the Column has attributes or false otherwise.

Returns:

true if the column has attributes on false otherwise

getAutolink

public boolean getAutolink()

Return the flag to automatically render HTML hyperlinks for column URL and email addresses values.

Returns:

automatically hyperlink column URL and email addresses flag

setAutolink

public void setAutolink(boolean autolink)

Set the flag to automatically render HTML hyperlinks for column URL and email addresses values.

Parameters:

autolink - the flag to automatically hyperlink column URL and email addresses flag

getComparator

public Comparator getComparator()

Return the column comparator object, which is used to sort column row values.

Returns:

the column row data sorting comparator object.

setComparator

public void setComparator(Comparator comparator)

Set the column comparator object, which is used to sort column row values.

Parameters:

comparator - the column row data sorting comparator object

getDataClass

public String getDataClass()

Return the table data <td> CSS class.

Returns:

the table data CSS class

setDataClass

public void setDataClass(String dataClass)

Set the table data <td> CSS class.

Parameters:

dataClass - the table data CSS class

getDataStyle

public String getDataStyle(String name)

Return the table data <td> CSS style.

Parameters:

name - the CSS style name

Returns:

the table data CSS style for the given name

setDataStyle

public void setDataStyle(String name,
                         String value)

Set the table data <td> CSS style name and value pair.

Parameters:

name - the CSS style name

value - the CSS style value

hasDataStyles

public boolean hasDataStyles()

Return true if table data <td> CSS styles are defined.

Returns:

true if table data <td> CSS styles are defined

getDataStyles

public Map getDataStyles()

Return the Map of table data <td> CSS styles.

Returns:

the Map of table data <td> CSS styles

getDecorator

public Decorator getDecorator()

Return the row column <td> decorator.

Returns:

the row column <td> decorator

setDecorator

public void setDecorator(Decorator decorator)

Set the row column <td> decorator.

Parameters:

decorator - the row column <td> decorator

getEscapeHtml

public boolean getEscapeHtml()

Return true if the HTML characters will be escaped when rendering the column data. By default this method returns true.

Returns:

true if the HTML characters will be escaped when rendered

setEscapeHtml

public void setEscapeHtml(boolean escape)

Set the escape HTML characters when rendering column data flag.

Parameters:

escape - the flag to escape HTML characters

getFormat

public String getFormat()

Return the row column message format pattern.

Returns:

the message row column message format pattern

setFormat

public void setFormat(String pattern)

Set the row column message format pattern. For example:

 Column idColumn = new Column("purchaseId", "ID");
 idColumn.setFormat("{0,number,#,###}");

 Column priceColumn = new Column("purchasePrice", "Price");
 priceColumn.setFormat("{0,number,currency}");

 Column dateColumn = new Column("purchaseDate", "Date");
 dateColumn.setFormat("{0,date,dd MMM yyyy}"); 

MesssageFormat Patterns

Format Type	Format Style	Subformat Created
number	(none)	NumberFormat.getInstance(getLocale())
	integer	NumberFormat.getIntegerInstance(getLocale())
	currency	NumberFormat.getCurrencyInstance(getLocale())
	percent	NumberFormat.getPercentInstance(getLocale())
	SubformatPattern	new DecimalFormat(subformatPattern, new DecimalFormatSymbols(getLocale()))
date	(none)	DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())
	short	DateFormat.getDateInstance(DateFormat.SHORT, getLocale())
	medium	DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())
	long	DateFormat.getDateInstance(DateFormat.LONG, getLocale())
	full	DateFormat.getDateInstance(DateFormat.FULL, getLocale())
	SubformatPattern	new SimpleDateFormat(subformatPattern, getLocale())
time	(none)	DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())
	short	DateFormat.getTimeInstance(DateFormat.SHORT, getLocale())
	medium	DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())
	long	DateFormat.getTimeInstance(DateFormat.LONG, getLocale())
	full	DateFormat.getTimeInstance(DateFormat.FULL, getLocale())
	SubformatPattern	new SimpleDateFormat(subformatPattern, getLocale())
choice	SubformatPattern	new ChoiceFormat(subformatPattern)

DecimalFormat Pattern Characters

Symbol	Location	Localized?	Meaning
0	Number	Yes	Digit
#	Number	Yes	Digit, zero shows as absent
.	Number	Yes	Decimal separator or monetary decimal separator
-	Number	Yes	Minus sign
,	Number	Yes	Grouping separator
E	Number	Yes	Separates mantissa and exponent in scientific notation. Need not be quoted in prefix or suffix.
;	Subpattern boundary	Yes	Separates positive and negative subpatterns
%	Prefix or suffix	Yes	Multiply by 100 and show as percentage
\u2030	Prefix or suffix	Yes	Multiply by 1000 and show as per mille
¤ (\u00A4)	Prefix or suffix	No	Currency sign, replaced by currency symbol. If doubled, replaced by international currency symbol. If present in a pattern, the monetary decimal separator is used instead of the decimal separator.
'	Prefix or suffix	No	Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock".

SimpleDateFormat Pattern Characters

Letter	Date or Time Component	Presentation	Examples
G	Era designator	Text	AD
y	Year	Year	1996; 96
M	Month in year	Month	July; Jul; 07
w	Week in year	Number	27
W	Week in month	Number	2
D	Day in year	Number	189
d	Day in month	Number	10
F	Day of week in month	Number	2
E	Day in week	Text	Tuesday; Tue
a	Am/pm marker	Text	PM
H	Hour in day (0-23)	Number	0
k	Hour in day (1-24)	Number	24
K	Hour in am/pm (0-11)	Number	0
h	Hour in am/pm (1-12)	Number	12
m	Minute in hour	Number	30
s	Second in minute	Number	55
S	Millisecond	Number	978
z	Time zone	General time zone	Pacific Standard Time; PST; GMT-08:00
Z	Time zone	RFC 822 time zone	-0800

Parameters:

pattern - the message format pattern

getMaxLength

public int getMaxLength()

The maximum column length. If maxLength is greater than 0 and the column data string length is greater than maxLength, the rendered value will be truncated with an eclipse(...).

Returns:

the maximum column length, or 0 if not defined

setMaxLength

public void setMaxLength(int value)

Set the maximum column length. If maxLength is greater than 0 and the column data string length is greater than maxLength, the rendered value will be truncated with an eclipse(...).

Parameters:

value - the maximum column length

getMessageFormat

public MessageFormat getMessageFormat()

Return the MessageFormat instance used to format the table cell value.

Returns:

the MessageFormat instance used to format the table cell value

setMessageFormat

public void setMessageFormat(MessageFormat messageFormat)

Set the MessageFormat instance used to format the table cell value.

Parameters:

messageFormat - the MessageFormat used to format the table cell value

getName

public String getName()

Return the property name.

Returns:

the name of the property

setName

public void setName(String name)

Set the property name.

Parameters:

name - the property name to set

getHeaderClass

public String getHeaderClass()

Return the table header <th> CSS class.

Returns:

the table header CSS class

setHeaderClass

public void setHeaderClass(String headerClass)

Set the table header <th> CSS class.

Parameters:

headerClass - the table header CSS class

getHeaderStyle

public String getHeaderStyle(String name)

Return the table header <th> CSS style.

Parameters:

name - the CSS style name

Returns:

the table header CSS style value for the given name

setHeaderStyle

public void setHeaderStyle(String name,
                           String value)

Set the table header <th> CSS style name and value pair.

Parameters:

name - the CSS style name

value - the CSS style value

hasHeaderStyles

public boolean hasHeaderStyles()

Return true if table header <th> CSS styles are defined.

Returns:

true if table header <th> CSS styles are defined

getHeaderStyles

public Map getHeaderStyles()

Return the Map of table header <th> CSS styles.

Returns:

the Map of table header <th> CSS styles

getHeaderTitle

public String getHeaderTitle()

Return the table header <th> title.

If the header title value is null, this method will attempt to find a localized message in the parent messages using the key:

getName() + ".headerTitle"

If not found then the message will be looked up in the /click-control.properties file using the same key. If a value still cannot be found then the Column name will be converted into a header title using the method: ClickUtils.toLabel(String)

Returns:

the table header title

setHeaderTitle

public void setHeaderTitle(String title)

Set the table header <th> title.

Parameters:

title - the table header title

getId

public String getId()

Return the Table and Column id appended: "table-column"

Use the field the "id" attribute value if defined, or the name otherwise.

Returns:

HTML element identifier attribute "id" value

getSortable

public boolean getSortable()

Return the column sortable status. If the column sortable status is not defined the value will be inherited from the Table.sortable property.

Returns:

the column sortable status

setRenderId

public void setRenderId(boolean value)

Set the column render id attribute status.

Parameters:

value - set the column render id attribute status

getRenderId

public boolean getRenderId()

Returns the column render id attribute status. If the column render id status is not defined the value will be inherited from the Table.renderId property.

Returns:

the column render id attribute status

setSortable

public void setSortable(boolean value)

Set the column sortable status.

Parameters:

value - the column sortable status

getTable

public Table getTable()

Return the parent Table containing the Column.

Returns:

the parent Table containing the Column

setTable

public void setTable(Table table)

Set the Column's the parent Table.

Parameters:

table - Column's parent Table

setTextAlign

public void setTextAlign(String align)

Set the column CSS "text-align" style for the header <th> and data <td> elements. Valid values include: [left, right, center]

Parameters:

align - the CSS "text-align" value: [left, right, center]

getTitleProperty

public String getTitleProperty()

Return the property name used to populate the <td> "title" attribute.

Returns:

the property name used to populate the <td> "title" attribute

setTitleProperty

public void setTitleProperty(String property)

Set the property name used to populate the <td> "title" attribute.

Parameters:

property - the property name used to populate the <td> "title" attribute

setVerticalAlign

public void setVerticalAlign(String align)

Set the column CSS "vertical-align" style for the header <th> and data <td> elements. Valid values include: [baseline | sub | super | top | text-top | middle | bottom | text-bottom | <percentage> | <length> | inherit]

Parameters:

align - the CSS "vertical-align" value

getWidth

public String getWidth()

Return the column HTML <td> width attribute.

Returns:

the column HTML <td> width attribute

setWidth

public void setWidth(String value)

Set the column HTML <td> width attribute.

Parameters:

value - the column HTML <td> width attribute

renderTableData

public void renderTableData(Object row,
                            HtmlStringBuffer buffer,
                            Context context,
                            int rowIndex)

Render the column table data <td> element to the given buffer using the passed row object.

Parameters:

row - the row object to render

buffer - the string buffer to render to

context - the request context

rowIndex - the index of the current row within the parent table

renderTableHeader

public void renderTableHeader(HtmlStringBuffer buffer,
                              Context context)

Render the column table header <tr> element to the given buffer.

Parameters:

buffer - the string buffer to render to

context - the request context

getProperty

public Object getProperty(Object row)

Return the column name property value from the given row object.

If the row object is a Map this method will attempt to return the map value for the column name.

The row map lookup will be performed using the property name, if a value is not found the property name in uppercase will be used, if a value is still not found the property name in lowercase will be used. If a map value is still not found then this method will return null.

Object property values can also be specified using an path expression.

Parameters:

row - the row object to obtain the property from

Returns:

the named row object property value

Throws:

RuntimeException - if an error occurred obtaining the property

getProperty

public Object getProperty(String name,
                          Object row)

Return the column property value from the given row object and property name.

If the row object is a Map this method will attempt to return the map value for the column.

The row map lookup will be performed using the property name, if a value is not found the property name in uppercase will be used, if a value is still not found the property name in lowercase will be used. If a map value is still not found then this method will return null.

Object property values can also be specified using an path expression.

Parameters:

name - the name of the property

row - the row object to obtain the property from

Returns:

the named row object property value

Throws:

RuntimeException - if an error occurred obtaining the property

renderTableDataContent

protected void renderTableDataContent(Object row,
                                      HtmlStringBuffer buffer,
                                      Context context,
                                      int rowIndex)

Render the content within the column table data <td> element.

Parameters:

row - the row object to render

buffer - the string buffer to render to

context - the request context

rowIndex - the index of the current row within the parent table

renderLink

protected boolean renderLink(Object value,
                             HtmlStringBuffer buffer)

Render the given table cell value to the buffer as a mailto: or http: hyperlink, or as an ordinary string if the value is determined not be linkable.

Parameters:

value - the table cell value to render

buffer - the StringBuffer to render to

Returns:

a rendered email or web hyperlink if applicable