org.apache.click.util
Class Format

java.lang.Object
  extended by org.apache.click.util.Format
All Implemented Interfaces:
Serializable

public class Format
extends Object
implements Serializable

Provides the default object for formatting the display of model objects in Velocity templates and JSP pages.

For Velocity templates a Format object is added to the Velocity Context using the name "format", while for JSP pages an instance is added as a request attribute using the same key.

For example the following Page code adds a date to the model:

 public void onGet() {
    Date date = order.deliveryDate();
    addModel("deliveryDate", date);
 } 
In the page template we use the format object:
 Delivery date: $format.date($deliveryDate, "dd MMM yyyy") 
Which renders the output as:
Delivery date: 21 Jan 2004
The custom format class can be defined in the "click.xml" configuration file using the syntax:
 <format classname="com.mycorp.utils.MyFormat"/> 
After a Page is created its format property is set. The ClickServlet will then add this property to the Velocity Context.

When subclassing Format ensure it is light weight object, as a new format object will be created for every new Page.

See Also:
PageImports, Serialized Form

Field Summary
protected  String emptyString
          The empty string value.
protected  Locale locale
          The request context locale.
 
Constructor Summary
Format()
           
 
Method Summary
 String currency(Number number)
          Return a currency formatted String value for the given number, using the default Locale.
 String currentDate()
          Return a formatted current date string using the default DateFormat.
 String currentDate(String pattern)
          Return a formatted current date string using the given formatting pattern.
 String date(Date date)
          Return a formatted date string using the given date and the default DateFormat.
 String date(Date date, String pattern)
          Return a formatted date string using the given date and formatting pattern.
 String decimal(Number number)
          Return a decimal formatted string using the given number and pattern.
 String decimal(Number number, String pattern)
          Return a decimal formatted string using the given number and pattern.
 String email(String email)
          Return an email hyperlink using the given email address.
 String email(String email, String attribute)
          Return an email hyperlink using the given email address.
 String escape(Object value)
          Escape the given object value as a string.
 String getEmptyString()
          Returns the format empty string value:   "".
 Locale getLocale()
          Return the locale used to format objects.
 String html(Object value)
          Escape the given object value as a HTML string.
 String javascript(String value)
          Escape the given object value as a JavaScript string, or "" if the object is null.
 String limitLength(String value, int maxlength)
          Return the value string limited to maxlength characters.
 String limitLength(String value, int maxlength, String suffix)
          Return the value string limited to maxlength characters.
 String link(String value)
          Return an hyperlink using the given URL or email address value.
 String link(String value, String attribute)
          Return an hyperlink using the given URL or email address value.
 String message(String pattern, List<?> arguments)
          Return a formatted string using the given message pattern and arguments.
 String message(String pattern, Object argument)
          Return a formatted string using the given message pattern and argument.
 String message(String pattern, Object[] arguments)
          Return a formatted string using the given message pattern and arguments.
 String percentage(Number number)
          Return a percentage formatted number string using number.
 void setEmptyString(String value)
          Set the format empty string value.
 String string(Object object)
          Return the string representation of the given object.
 String time(Date date)
          Return a formatted time string using the given date and the default DateFormat.
 String url(Object object)
          Return an encoded URL value for the given object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

locale

protected Locale locale
The request context locale.


emptyString

protected String emptyString
The empty string value.

Constructor Detail

Format

public Format()
Method Detail

getLocale

public Locale getLocale()
Return the locale used to format objects.

Returns:
the locale used to format objects

getEmptyString

public String getEmptyString()
Returns the format empty string value:   "".

This method is designed to be overridden. If you need a different empty string value simply override this method.

Note the IE browser does not fully support CSS attribute:   table { empty-cells: show }. Also note returning &nbsp; value will prevent AJAX XML responses being rendered in browsers.

Returns:
the formatter methods empty string value

setEmptyString

public void setEmptyString(String value)
Set the format empty string value.

Parameters:
value - the format empty string value

currency

public String currency(Number number)
Return a currency formatted String value for the given number, using the default Locale.

If the number is null this method will return the getEmptyString() value.

Parameters:
number - the number to format
Returns:
a currency formatted number string

currentDate

public String currentDate()
Return a formatted current date string using the default DateFormat.

Returns:
a formatted date string

currentDate

public String currentDate(String pattern)
Return a formatted current date string using the given formatting pattern. See SimpleDateFormat for information on the format pattern string.

Parameters:
pattern - the SimpleDateFormat formatting pattern
Returns:
a formatted date string
Throws:
IllegalArgumentException - if the pattern string is null

date

public String date(Date date,
                   String pattern)
Return a formatted date string using the given date and formatting pattern. See SimpleDateFormat for information on the format pattern string.

If the date is null this method will return the getEmptyString() value.

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:
date - the date value to format
pattern - the SimpleDateFormat formatting pattern
Returns:
a formatted date string
Throws:
IllegalArgumentException - if the pattern string is null

date

public String date(Date date)
Return a formatted date string using the given date and the default DateFormat.

If the date is null this method will return the getEmptyString() value.

Parameters:
date - the date value to format
Returns:
a formatted date string

decimal

public String decimal(Number number,
                      String pattern)
Return a decimal formatted string using the given number and pattern. See DecimalFormat for information on the format pattern string.

If the number is null this method will return the getEmptyString() value.

Please Note: Velocity will not correctly parse the '#' decimal number pattern character and will throw a parsing exception. When using this method substitute the '#' decimal pattern character (Digit, zero shows as absent) with 'N'. Internally this method will reverse the substitution before invoking DecimalFormat. For example:

 $format.decimal($value, "N,NN0.00") -> "#,##0.00"
 

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

Parameters:
number - the number to format
pattern - the decimal format pattern
Returns:
the formatted decimal number
Throws:
IllegalArgumentException - if the pattern string is null

decimal

public String decimal(Number number)
Return a decimal formatted string using the given number and pattern.

If the number is null this method will return the getEmptyString() value.

Parameters:
number - the number to format
Returns:
the formatted decimal number

email

public String email(String email)
Return an email hyperlink using the given email address. If the given value is not a valid email string it will be rendered as is and not as a hyperlink.

If the given value is blank then the getEmptyString() value will rendered instead.

The format of the returned email string will be:

 <a href='mailto:email'>email</a> 

Parameters:
email - the email address to hyperlink
Returns:
a hyperlinked email

email

public String email(String email,
                    String attribute)
Return an email hyperlink using the given email address. If the given value is not a valid email string it will be rendered as is and not as a hyperlink.

If the given value is blank then the getEmptyString() value will rendered instead.

The format of the returned email string will be:

 <a href='mailto:email' attribute>email</a> 

Parameters:
email - the email address to hyperlink
attribute - the anchor tag attribute to render
Returns:
a hyperlinked email

escape

public String escape(Object value)
Escape the given object value as a string. The following characters are escaped: <, >, ", ', &.

If the value is null this method will return the getEmptyString() value.

Parameters:
value - unescaped value
Returns:
the escaped string

html

public String html(Object value)
Escape the given object value as a HTML string.

If the value is null this method will return the getEmptyString() value.

Parameters:
value - unescaped HTML
Returns:
the HTML escaped string

javascript

public String javascript(String value)
Escape the given object value as a JavaScript string, or "" if the object is null.

Implementation is provided by Jakarta Commons Lang utility: StringEscapeUtils.escapeJavaScript(String)

Parameters:
value - unescaped JavaScript
Returns:
the JavaScript escaped string

limitLength

public String limitLength(String value,
                          int maxlength)
Return the value string limited to maxlength characters. If the string gets curtailed, "..." is appended to it.

Adapted from Velocity Tools Formatter.

Parameters:
value - the string value to limit the length of
maxlength - the maximum string length
Returns:
a length limited string

limitLength

public String limitLength(String value,
                          int maxlength,
                          String suffix)
Return the value string limited to maxlength characters. If the string gets curtailed and the suffix parameter is appended to it.

Adapted from Velocity Tools Formatter.

Parameters:
value - the string value to limit the length of
maxlength - the maximum string length
suffix - the suffix to append to the length limited string
Returns:
a length limited string

link

public String link(String value)
Return an hyperlink using the given URL or email address value. If the given value is not a valid email string or URL it will note be hyperlinked and will be rendered as is.

If the given value is blank then the getEmptyString() value will rendered instead.

Parameters:
value - the URL or email address to hyperlink
Returns:
a hyperlinked URL or email address

link

public String link(String value,
                   String attribute)
Return an hyperlink using the given URL or email address value. If the given value is not a valid email string or URL it will note be hyperlinked and will be rendered as is.

If the given value is blank then the getEmptyString() value will rendered instead.

Parameters:
value - the URL or email address to hyperlink
attribute - the anchor tag attribute to render
Returns:
a hyperlinked URL or email address

message

public String message(String pattern,
                      Object argument)
Return a formatted string using the given message pattern and argument. See MessageFormat for information on the message pattern string.

Parameters:
pattern - the message pattern
argument - the message argument
Returns:
the formatted string

message

public String message(String pattern,
                      Object[] arguments)
Return a formatted string using the given message pattern and arguments. See MessageFormat for information on the message pattern string.

Parameters:
pattern - the message pattern
arguments - the message arguments
Returns:
the formatted string

message

public String message(String pattern,
                      List<?> arguments)
Return a formatted string using the given message pattern and arguments. See MessageFormat for information on the message pattern string.

Parameters:
pattern - the message pattern
arguments - list of message arguments
Returns:
the formatted string

percentage

public String percentage(Number number)
Return a percentage formatted number string using number.

If the number is null this method will return the getEmptyString() value.

Parameters:
number - the number value to format
Returns:
a percentage formatted number string

time

public String time(Date date)
Return a formatted time string using the given date and the default DateFormat.

If the date is null this method will return the getEmptyString() value.

Parameters:
date - the date value to format
Returns:
a formatted time string

string

public String string(Object object)
Return the string representation of the given object.

If the object is null this method will return the getEmptyString() value.

Parameters:
object - the object to format
Returns:
the string representation of the object

url

public String url(Object object)
Return an encoded URL value for the given object.

Parameters:
object - the object value to encode as a URL string
Returns:
an encoded URL string