org.apache.click.control
Class Column

java.lang.Object
  extended by org.apache.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:

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).

See Also:
Decorator, Table, Serialized Form

Field Summary
protected  Map<String,String> 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<String,String> 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<String,String> 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<Object,Object> 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<String,String> 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<String,String> 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<String,String> 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<String,String> 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<String,String> 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<String,String> 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<Object,Object> 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<String,String> 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<String,String> 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<String,String> 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 a 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 a 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