Class DisplayTool
java.lang.Object
org.apache.velocity.tools.generic.SafeConfig
org.apache.velocity.tools.generic.LocaleConfig
org.apache.velocity.tools.generic.DisplayTool
Provides general utility methods for controlling the display of references.
Currently, this class contains methods for "pretty printing" an array or
Collection
, 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 ClassesModifier and TypeClassDescriptionstatic class
Measures the dimensions of the string given to its constructor. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
static final String
static final String
static final String
private String[]
private String
private int
private String
private String
private String
private boolean
private int
private String
static final String
static final String
static final String
static final String
static final String
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 -
Method Summary
Modifier and TypeMethodDescriptionReturns a configured default value if specified value is null.Returns the second argument if first argument specified is null.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.capitalize
(Object capitalizeMe) Changes the first character of the string value of the specified object to upper case and returns the resulting string.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.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.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.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 String
format
(Collection list, String delim, String finaldelim, String property) Does the actual formatting of the collection.String[]
int
protected Object
getProperty
(Object object, String property) Safely retrieves the specified property from the specified object.boolean
int
Formats a collection or array into the form "A, B and C".Formats a collection or array into the form "A<delim>B<delim>C".Formats a collection or array into the form "A<delim>B<finaldelim>C".Formats a specified property of collection or array of objects into the form "A<delim>B<finaldelim>C".Returns theDisplayTool.Measurements
of the string value of the specified object.Deprecated.Will be unnecessary with Velocity 1.6UsesMessageFormat
to format the specified String with the specified arguments.Deprecated.Will be unnecessary with Velocity 1.6message
(String format, Collection args) Deprecated.Will be unnecessary with Velocity 1.6Builds plural form of a passed word if 'value' is plural, otherwise returns 'singular'.Returns 'plural' parameter if passed 'value' is plural, otherwise 'singular' is returned.Uses {@link String#format(Locale,String,Object...} to format the specified String with the specified arguments.protected void
setAllowedTags
(String[] tags) protected void
setCellLength
(int maxlen) protected void
setCellSuffix
(String suffix) protected void
setDefaultAlternate
(String dflt) protected void
setListDelimiter
(String delim) protected void
setListFinalDelimiter
(String finalDelim) protected void
setTruncateAtWord
(boolean atWord) protected void
setTruncateLength
(int maxlen) protected void
setTruncateSuffix
(String suffix) space
(int length) Returns a string of spaces of the specified length.Removes HTML tags from the string value of the specified object and returns the resulting string.Removes all not allowed HTML tags from the string value of the specified object and returns the resulting string.Limits the string value of 'truncateMe' to the configured max length in characters (default is 30 characters).Limits the string value of 'truncateMe' to 'maxLength' characters.Limits the string value of 'truncateMe' to the specified max length in characters.Limits the string value of 'truncateMe' to the latest complete word within the specified maxLength.Limits the string value of 'truncateMe' to the configured max length in characters (default is 30 characters).uncapitalize
(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 Details
-
LIST_DELIM_KEY
- See Also:
-
LIST_FINAL_DELIM_KEY
- See Also:
-
TRUNCATE_LENGTH_KEY
- See Also:
-
TRUNCATE_SUFFIX_KEY
- See Also:
-
TRUNCATE_AT_WORD_KEY
- See Also:
-
CELL_LENGTH_KEY
- See Also:
-
CELL_SUFFIX_KEY
- See Also:
-
DEFAULT_ALTERNATE_KEY
- See Also:
-
ALLOWED_TAGS_KEY
- See Also:
-
defaultDelim
-
defaultFinalDelim
-
defaultTruncateLength
private int defaultTruncateLength -
defaultTruncateSuffix
-
defaultTruncateAtWord
private boolean defaultTruncateAtWord -
defaultCellLength
private int defaultCellLength -
defaultCellSuffix
-
defaultAlternate
-
defaultAllowedTags
-
-
Constructor Details
-
DisplayTool
public DisplayTool()
-
-
Method Details
-
configure
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
-
setListDelimiter
-
getListFinalDelimiter
-
setListFinalDelimiter
-
getTruncateLength
public int getTruncateLength() -
setTruncateLength
protected void setTruncateLength(int maxlen) -
getTruncateSuffix
-
setTruncateSuffix
-
getTruncateAtWord
public boolean getTruncateAtWord() -
setTruncateAtWord
protected void setTruncateAtWord(boolean atWord) -
getCellSuffix
-
setCellSuffix
-
getCellLength
public int getCellLength() -
setCellLength
protected void setCellLength(int maxlen) -
getDefaultAlternate
-
setDefaultAlternate
-
getAllowedTags
-
setAllowedTags
-
list
Formats a collection or array into the form "A, B and C".- Parameters:
list
- A collection or array.- Returns:
- A String.
-
list
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
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
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
Does the actual formatting of the collection. -
message
Deprecated.Will be unnecessary with Velocity 1.6 -
message
Deprecated.Will be unnecessary with Velocity 1.6 -
message
Deprecated.Will be unnecessary with Velocity 1.6 -
message
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
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:
-
truncate
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
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
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
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 String truncate(Object truncateMe, int maxLength, 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
Returns a string of spaces of the specified length.- Parameters:
length
- the number of spaces to return
-
cell
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
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
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
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
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
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
Returns a configured default value if specified value is null.- Parameters:
checkMe
-- Returns:
- a configured default value if the specified value is null.
-
alt
Returns the second argument if first argument specified is null.- Parameters:
checkMe
-alternate
-- Returns:
- the second argument if the first is null.
-
br
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
Removes HTML tags from the string value of the specified object and returns the resulting string.- Parameters:
obj
-
-
stripTags
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
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
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
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
Returns theDisplayTool.Measurements
of the string value of the specified object.
-