org.apache.click.util
Class Format

java.lang.Object
  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   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