Class DisplayTool
- java.lang.Object
-
- org.apache.velocity.tools.generic.SafeConfig
-
- org.apache.velocity.tools.generic.LocaleConfig
-
- org.apache.velocity.tools.generic.DisplayTool
-
@DefaultKey("display") public class DisplayTool extends LocaleConfig
Provides general utility methods for controlling the display of references. Currently, this class contains methods for "pretty printing" an array orCollection
, methods for truncating the string value of a reference at a configured or specified length, methods for displaying an alternate value when a specified value is null, a method for generating whitespace, a "printf" type of method for formatting messages, and methods for forcing values into "cells" of equal size (via truncation or padding with whitespace).Example Use:
tools.xml... <tools> <toolbox scope="application"> <tool class="org.apache.velocity.tools.generic.DisplayTool"/> </toolbox> </tools> template... #set( $list = [1..5] ) $display.list($list) $display.truncate("This is a long string.", 10) Not Null: $display.alt("not null", "--") Null: $display.alt($null, "--") output... 1, 2, 3, 4 and 5 This is... Not Null: not null Null: --
- Since:
- VelocityTools 2.0
- Version:
- $Id: DisplayTool.java 463298 2006-10-12 16:10:32Z henning $
- Author:
- Sean Legassick, Daniel Rall, Nathan Bubna
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
DisplayTool.Measurements
Measures the dimensions of the string given to its constructor.
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
ALLOWED_TAGS_KEY
static java.lang.String
CELL_LENGTH_KEY
static java.lang.String
CELL_SUFFIX_KEY
static java.lang.String
DEFAULT_ALTERNATE_KEY
private java.lang.String[]
defaultAllowedTags
private java.lang.String
defaultAlternate
private int
defaultCellLength
private java.lang.String
defaultCellSuffix
private java.lang.String
defaultDelim
private java.lang.String
defaultFinalDelim
private boolean
defaultTruncateAtWord
private int
defaultTruncateLength
private java.lang.String
defaultTruncateSuffix
static java.lang.String
LIST_DELIM_KEY
static java.lang.String
LIST_FINAL_DELIM_KEY
static java.lang.String
TRUNCATE_AT_WORD_KEY
static java.lang.String
TRUNCATE_LENGTH_KEY
static java.lang.String
TRUNCATE_SUFFIX_KEY
-
Fields inherited from class org.apache.velocity.tools.generic.LocaleConfig
DEFAULT_LOCALE
-
Fields inherited from class org.apache.velocity.tools.generic.SafeConfig
LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY
-
-
Constructor Summary
Constructors Constructor Description DisplayTool()
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description java.lang.Object
alt(java.lang.Object checkMe)
Returns a configured default value if specified value is null.java.lang.Object
alt(java.lang.Object checkMe, java.lang.Object alternate)
Returns the second argument if first argument specified is null.java.lang.String
br(java.lang.Object obj)
Inserts HTML line break tag (<br />) in front of all newline characters of the string value of the specified object and returns the resulting string.java.lang.String
capitalize(java.lang.Object capitalizeMe)
Changes the first character of the string value of the specified object to upper case and returns the resulting string.java.lang.String
cell(java.lang.Object obj)
Truncates or pads the string value of the specified object as necessary to ensure that the returned string's length equals the default cell size.java.lang.String
cell(java.lang.Object obj, int cellsize)
Truncates or pads the string value of the specified object as necessary to ensure that the returned string's length equals the specified cell size.java.lang.String
cell(java.lang.Object obj, int cellsize, java.lang.String suffix)
Truncates or pads the string value of the specified object as necessary to ensure that the returned string's length equals the specified cell size.java.lang.String
cell(java.lang.Object obj, java.lang.String suffix)
Truncates or pads the string value of the specified object as necessary to ensure that the returned string's length equals the default cell size.protected void
configure(ValueParser values)
Does the actual configuration.protected java.lang.String
format(java.util.Collection list, java.lang.String delim, java.lang.String finaldelim, java.lang.String property)
Does the actual formatting of the collection.java.lang.String[]
getAllowedTags()
int
getCellLength()
java.lang.String
getCellSuffix()
java.lang.String
getDefaultAlternate()
java.lang.String
getListDelimiter()
java.lang.String
getListFinalDelimiter()
protected java.lang.Object
getProperty(java.lang.Object object, java.lang.String property)
Safely retrieves the specified property from the specified object.boolean
getTruncateAtWord()
int
getTruncateLength()
java.lang.String
getTruncateSuffix()
java.lang.String
list(java.lang.Object list)
Formats a collection or array into the form "A, B and C".java.lang.String
list(java.lang.Object list, java.lang.String delim)
Formats a collection or array into the form "A<delim>B<delim>C".java.lang.String
list(java.lang.Object list, java.lang.String delim, java.lang.String finaldelim)
Formats a collection or array into the form "A<delim>B<finaldelim>C".java.lang.String
list(java.lang.Object list, java.lang.String delim, java.lang.String finaldelim, java.lang.String property)
Formats a specified property of collection or array of objects into the form "A<delim>B<finaldelim>C".DisplayTool.Measurements
measure(java.lang.Object measureMe)
Returns theDisplayTool.Measurements
of the string value of the specified object.java.lang.String
message(java.lang.String format, java.lang.Object arg)
Deprecated.Will be unnecessary with Velocity 1.6java.lang.String
message(java.lang.String format, java.lang.Object... args)
UsesMessageFormat
to format the specified String with the specified arguments.java.lang.String
message(java.lang.String format, java.lang.Object arg1, java.lang.Object arg2)
Deprecated.Will be unnecessary with Velocity 1.6java.lang.String
message(java.lang.String format, java.util.Collection args)
Deprecated.Will be unnecessary with Velocity 1.6java.lang.String
plural(int value, java.lang.String singular)
Builds plural form of a passed word if 'value' is plural, otherwise returns 'singular'.java.lang.String
plural(int value, java.lang.String singular, java.lang.String plural)
Returns 'plural' parameter if passed 'value' is plural, otherwise 'singular' is returned.java.lang.String
printf(java.lang.String format, java.lang.Object... args)
Uses {@link String#format(Locale,String,Object...} to format the specified String with the specified arguments.protected void
setAllowedTags(java.lang.String[] tags)
protected void
setCellLength(int maxlen)
protected void
setCellSuffix(java.lang.String suffix)
protected void
setDefaultAlternate(java.lang.String dflt)
protected void
setListDelimiter(java.lang.String delim)
protected void
setListFinalDelimiter(java.lang.String finalDelim)
protected void
setTruncateAtWord(boolean atWord)
protected void
setTruncateLength(int maxlen)
protected void
setTruncateSuffix(java.lang.String suffix)
java.lang.String
space(int length)
Returns a string of spaces of the specified length.java.lang.String
stripTags(java.lang.Object obj)
Removes HTML tags from the string value of the specified object and returns the resulting string.java.lang.String
stripTags(java.lang.Object obj, java.lang.String... allowedTags)
Removes all not allowed HTML tags from the string value of the specified object and returns the resulting string.java.lang.String
truncate(java.lang.Object truncateMe)
Limits the string value of 'truncateMe' to the configured max length in characters (default is 30 characters).java.lang.String
truncate(java.lang.Object truncateMe, int maxLength)
Limits the string value of 'truncateMe' to 'maxLength' characters.java.lang.String
truncate(java.lang.Object truncateMe, int maxLength, java.lang.String suffix)
Limits the string value of 'truncateMe' to the specified max length in characters.java.lang.String
truncate(java.lang.Object truncateMe, int maxLength, java.lang.String suffix, boolean defaultTruncateAtWord)
Limits the string value of 'truncateMe' to the latest complete word within the specified maxLength.java.lang.String
truncate(java.lang.Object truncateMe, java.lang.String suffix)
Limits the string value of 'truncateMe' to the configured max length in characters (default is 30 characters).java.lang.String
uncapitalize(java.lang.Object uncapitalizeMe)
Changes the first character of the string value of the specified object to lower case and returns the resulting string.-
Methods inherited from class org.apache.velocity.tools.generic.LocaleConfig
getLocale, setLocale
-
Methods inherited from class org.apache.velocity.tools.generic.SafeConfig
configure, isConfigLocked, isSafeMode, setLockConfig, setSafeMode
-
-
-
-
Field Detail
-
LIST_DELIM_KEY
public static final java.lang.String LIST_DELIM_KEY
- See Also:
- Constant Field Values
-
LIST_FINAL_DELIM_KEY
public static final java.lang.String LIST_FINAL_DELIM_KEY
- See Also:
- Constant Field Values
-
TRUNCATE_LENGTH_KEY
public static final java.lang.String TRUNCATE_LENGTH_KEY
- See Also:
- Constant Field Values
-
TRUNCATE_SUFFIX_KEY
public static final java.lang.String TRUNCATE_SUFFIX_KEY
- See Also:
- Constant Field Values
-
TRUNCATE_AT_WORD_KEY
public static final java.lang.String TRUNCATE_AT_WORD_KEY
- See Also:
- Constant Field Values
-
CELL_LENGTH_KEY
public static final java.lang.String CELL_LENGTH_KEY
- See Also:
- Constant Field Values
-
CELL_SUFFIX_KEY
public static final java.lang.String CELL_SUFFIX_KEY
- See Also:
- Constant Field Values
-
DEFAULT_ALTERNATE_KEY
public static final java.lang.String DEFAULT_ALTERNATE_KEY
- See Also:
- Constant Field Values
-
ALLOWED_TAGS_KEY
public static final java.lang.String ALLOWED_TAGS_KEY
- See Also:
- Constant Field Values
-
defaultDelim
private java.lang.String defaultDelim
-
defaultFinalDelim
private java.lang.String defaultFinalDelim
-
defaultTruncateLength
private int defaultTruncateLength
-
defaultTruncateSuffix
private java.lang.String defaultTruncateSuffix
-
defaultTruncateAtWord
private boolean defaultTruncateAtWord
-
defaultCellLength
private int defaultCellLength
-
defaultCellSuffix
private java.lang.String defaultCellSuffix
-
defaultAlternate
private java.lang.String defaultAlternate
-
defaultAllowedTags
private java.lang.String[] defaultAllowedTags
-
-
Method Detail
-
configure
protected void configure(ValueParser values)
Does the actual configuration. This is protected, so subclasses may share the same ValueParser and call configure at any time, while preventing templates from doing so when configure(Map) is locked.- Overrides:
configure
in classLocaleConfig
-
getListDelimiter
public java.lang.String getListDelimiter()
-
setListDelimiter
protected void setListDelimiter(java.lang.String delim)
-
getListFinalDelimiter
public java.lang.String getListFinalDelimiter()
-
setListFinalDelimiter
protected void setListFinalDelimiter(java.lang.String finalDelim)
-
getTruncateLength
public int getTruncateLength()
-
setTruncateLength
protected void setTruncateLength(int maxlen)
-
getTruncateSuffix
public java.lang.String getTruncateSuffix()
-
setTruncateSuffix
protected void setTruncateSuffix(java.lang.String suffix)
-
getTruncateAtWord
public boolean getTruncateAtWord()
-
setTruncateAtWord
protected void setTruncateAtWord(boolean atWord)
-
getCellSuffix
public java.lang.String getCellSuffix()
-
setCellSuffix
protected void setCellSuffix(java.lang.String suffix)
-
getCellLength
public int getCellLength()
-
setCellLength
protected void setCellLength(int maxlen)
-
getDefaultAlternate
public java.lang.String getDefaultAlternate()
-
setDefaultAlternate
protected void setDefaultAlternate(java.lang.String dflt)
-
getAllowedTags
public java.lang.String[] getAllowedTags()
-
setAllowedTags
protected void setAllowedTags(java.lang.String[] tags)
-
list
public java.lang.String list(java.lang.Object list)
Formats a collection or array into the form "A, B and C".- Parameters:
list
- A collection or array.- Returns:
- A String.
-
list
public java.lang.String list(java.lang.Object list, java.lang.String delim)
Formats a collection or array into the form "A<delim>B<delim>C".- Parameters:
list
- A collection or array.delim
- A String.- Returns:
- A String.
-
list
public java.lang.String list(java.lang.Object list, java.lang.String delim, java.lang.String finaldelim)
Formats a collection or array into the form "A<delim>B<finaldelim>C".- Parameters:
list
- A collection or array.delim
- A String.finaldelim
- A String.- Returns:
- A String.
-
list
public java.lang.String list(java.lang.Object list, java.lang.String delim, java.lang.String finaldelim, java.lang.String property)
Formats a specified property of collection or array of objects into the form "A<delim>B<finaldelim>C".- Parameters:
list
- A collection or array.delim
- A String.finaldelim
- A String.property
- An object property to format.- Returns:
- A String.
-
format
protected java.lang.String format(java.util.Collection list, java.lang.String delim, java.lang.String finaldelim, java.lang.String property)
Does the actual formatting of the collection.
-
message
@Deprecated public java.lang.String message(java.lang.String format, java.util.Collection args)
Deprecated.Will be unnecessary with Velocity 1.6
-
message
@Deprecated public java.lang.String message(java.lang.String format, java.lang.Object arg)
Deprecated.Will be unnecessary with Velocity 1.6
-
message
@Deprecated public java.lang.String message(java.lang.String format, java.lang.Object arg1, java.lang.Object arg2)
Deprecated.Will be unnecessary with Velocity 1.6
-
message
public java.lang.String message(java.lang.String format, java.lang.Object... args)
UsesMessageFormat
to format the specified String with the specified arguments. If there are no arguments, then the String is returned directly. Please note that the format required here is quite different from that ofprintf(String,Object...)
.- Since:
- VelocityTools 2.0
-
printf
public java.lang.String printf(java.lang.String format, java.lang.Object... args)
Uses {@link String#format(Locale,String,Object...} to format the specified String with the specified arguments. Please note that the format required here is quite different from that ofmessage(String,Object...)
.- Since:
- VelocityTools 2.0
- See Also:
Formatter
-
truncate
public java.lang.String truncate(java.lang.Object truncateMe)
Limits the string value of 'truncateMe' to the configured max length in characters (default is 30 characters). If the string gets curtailed, the configured suffix (default is "...") is used as the ending of the truncated string.- Parameters:
truncateMe
- The value to be truncated.- Returns:
- A String.
-
truncate
public java.lang.String truncate(java.lang.Object truncateMe, int maxLength)
Limits the string value of 'truncateMe' to 'maxLength' characters. If the string gets curtailed, the configured suffix (default is "...") is used as the ending of the truncated string.- Parameters:
maxLength
- An int with the maximum length.truncateMe
- The value to be truncated.- Returns:
- A String.
-
truncate
public java.lang.String truncate(java.lang.Object truncateMe, java.lang.String suffix)
Limits the string value of 'truncateMe' to the configured max length in characters (default is 30 characters). If the string gets curtailed, the specified suffix is used as the ending of the truncated string.- Parameters:
truncateMe
- The value to be truncated.suffix
- A String.- Returns:
- A String.
-
truncate
public java.lang.String truncate(java.lang.Object truncateMe, int maxLength, java.lang.String suffix)
Limits the string value of 'truncateMe' to the specified max length in characters. If the string gets curtailed, the specified suffix is used as the ending of the truncated string.- Parameters:
truncateMe
- The value to be truncated.maxLength
- An int with the maximum length.suffix
- A String.- Returns:
- A String.
-
truncate
public java.lang.String truncate(java.lang.Object truncateMe, int maxLength, java.lang.String suffix, boolean defaultTruncateAtWord)
Limits the string value of 'truncateMe' to the latest complete word within the specified maxLength. If the string gets curtailed, the specified suffix is used as the ending of the truncated string.- Parameters:
truncateMe
- The value to be truncated.maxLength
- An int with the maximum length.suffix
- A String.defaultTruncateAtWord
- Truncate at a word boundary if true.- Returns:
- A String.
-
space
public java.lang.String space(int length)
Returns a string of spaces of the specified length.- Parameters:
length
- the number of spaces to return
-
cell
public java.lang.String cell(java.lang.Object obj)
Truncates or pads the string value of the specified object as necessary to ensure that the returned string's length equals the default cell size.- Parameters:
obj
- the value to be put in the 'cell'
-
cell
public java.lang.String cell(java.lang.Object obj, int cellsize)
Truncates or pads the string value of the specified object as necessary to ensure that the returned string's length equals the specified cell size.- Parameters:
obj
- the value to be put in the 'cell'cellsize
- the size of the cell into which the object must be placed
-
cell
public java.lang.String cell(java.lang.Object obj, java.lang.String suffix)
Truncates or pads the string value of the specified object as necessary to ensure that the returned string's length equals the default cell size. If truncation is necessary, the specified suffix will replace the end of the string value to indicate that.- Parameters:
obj
- the value to be put in the 'cell'suffix
- the suffix to put at the end of any values that need truncating to indicate that they've been truncated
-
cell
public java.lang.String cell(java.lang.Object obj, int cellsize, java.lang.String suffix)
Truncates or pads the string value of the specified object as necessary to ensure that the returned string's length equals the specified cell size.- Parameters:
obj
- the value to be put in the 'cell'cellsize
- the size of the cell into which the object must be placedsuffix
- the suffix to put at the end of any values that need truncating to indicate that they've been truncated
-
capitalize
public java.lang.String capitalize(java.lang.Object capitalizeMe)
Changes the first character of the string value of the specified object to upper case and returns the resulting string.- Parameters:
capitalizeMe
- The value to be capitalized.
-
uncapitalize
public java.lang.String uncapitalize(java.lang.Object uncapitalizeMe)
Changes the first character of the string value of the specified object to lower case and returns the resulting string.- Parameters:
uncapitalizeMe
- The value to be uncapitalized.
-
alt
public java.lang.Object alt(java.lang.Object checkMe)
Returns a configured default value if specified value is null.- Parameters:
checkMe
-- Returns:
- a configured default value if the specified value is null.
-
alt
public java.lang.Object alt(java.lang.Object checkMe, java.lang.Object alternate)
Returns the second argument if first argument specified is null.- Parameters:
checkMe
-alternate
-- Returns:
- the second argument if the first is null.
-
br
public java.lang.String br(java.lang.Object obj)
Inserts HTML line break tag (<br />) in front of all newline characters of the string value of the specified object and returns the resulting string.- Parameters:
obj
-
-
stripTags
public java.lang.String stripTags(java.lang.Object obj)
Removes HTML tags from the string value of the specified object and returns the resulting string.- Parameters:
obj
-
-
stripTags
public java.lang.String stripTags(java.lang.Object obj, java.lang.String... allowedTags)
Removes all not allowed HTML tags from the string value of the specified object and returns the resulting string.- Parameters:
obj
-allowedTags
- An array of allowed tag names (i.e. "h1","br","img")
-
plural
public java.lang.String plural(int value, java.lang.String singular)
Builds plural form of a passed word if 'value' is plural, otherwise returns 'singular'. Plural form is built using some basic English language rules for nouns which does not guarantee correct syntax of a result in all cases.- Parameters:
value
-singular
- Singular form of a word.
-
plural
public java.lang.String plural(int value, java.lang.String singular, java.lang.String plural)
Returns 'plural' parameter if passed 'value' is plural, otherwise 'singular' is returned.- Parameters:
value
-singular
- Singular form of a word.plural
- Plural form of a word.
-
getProperty
protected java.lang.Object getProperty(java.lang.Object object, java.lang.String property)
Safely retrieves the specified property from the specified object. Subclasses that wish to perform more advanced, efficient, or just different property retrieval methods should override this method to do so.
-
measure
public DisplayTool.Measurements measure(java.lang.Object measureMe)
Returns theDisplayTool.Measurements
of the string value of the specified object.
-
-