DisplayTool (VelocityTools 3.1 API)

java.lang.Object
- org.apache.velocity.tools.generic.SafeConfig
- - org.apache.velocity.tools.generic.LocaleConfig
  - - org.apache.velocity.tools.generic.DisplayTool

All Implemented Interfaces:

Serializable
```
@DefaultKey(value="display")
 @ValidScope(value="application")
public class DisplayTool
extends LocaleConfig
implements Serializable
```
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

See Also:

Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class DisplayTool.Measurements
Measures the dimensions of the string given to its constructor.

Nested Classes
Modifier and Type	Class and Description
`static class`	`DisplayTool.Measurements` Measures the dimensions of the string given to its constructor.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`ALLOWED_TAGS_KEY`
`static String`	`CELL_LENGTH_KEY`
`static String`	`CELL_SUFFIX_KEY`
`static String`	`DEFAULT_ALTERNATE_KEY`
`static String`	`LIST_DELIM_KEY`
`static String`	`LIST_FINAL_DELIM_KEY`
`static String`	`TRUNCATE_AT_WORD_KEY`
`static String`	`TRUNCATE_LENGTH_KEY`
`static 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, log, LOGGER_NAME_KEY, SAFE_MODE_KEY, USE_CLASS_LOGGER_KEY

Constructor Summary

Constructors
Constructor and Description

DisplayTool()

Constructors
Constructor and Description
`DisplayTool()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Object`	`alt(Object checkMe)` Returns a configured default value if specified value is null.
`Object`	`alt(Object checkMe, Object alternate)` Returns the second argument if first argument specified is null.
`String`	`br(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.
`String`	`capitalize(Object capitalizeMe)` Changes the first character of the string value of the specified object to upper case and returns the resulting string.
`String`	`cell(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.
`String`	`cell(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.
`String`	`cell(Object obj, int cellsize, 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.
`String`	`cell(Object obj, 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 String`	`format(Collection list, String delim, String finaldelim, String property)` Does the actual formatting of the collection.
`String[]`	`getAllowedTags()`
`int`	`getCellLength()`
`String`	`getCellSuffix()`
`String`	`getDefaultAlternate()`
`String`	`getListDelimiter()`
`String`	`getListFinalDelimiter()`
`protected Object`	`getProperty(Object object, String property)` Safely retrieves the specified property from the specified object.
`boolean`	`getTruncateAtWord()`
`int`	`getTruncateLength()`
`String`	`getTruncateSuffix()`
`String`	`list(Object list)` Formats a collection or array into the form "A, B and C".
`String`	`list(Object list, String delim)` Formats a collection or array into the form "A<delim>B<delim>C".
`String`	`list(Object list, String delim, String finaldelim)` Formats a collection or array into the form "A<delim>B<finaldelim>C".
`String`	`list(Object list, String delim, String finaldelim, String property)` Formats a specified property of collection or array of objects into the form "A<delim>B<finaldelim>C".
`DisplayTool.Measurements`	`measure(Object measureMe)` Returns the `DisplayTool.Measurements` of the string value of the specified object.
`String`	`message(String format, Object... args)` Uses `MessageFormat` to format the specified String with the specified arguments.
`String`	`plural(int value, String singular)` Builds plural form of a passed word if 'value' is plural, otherwise returns 'singular'.
`String`	`plural(int value, String singular, String plural)` Returns 'plural' parameter if passed 'value' is plural, otherwise 'singular' is returned.
`String`	`printf(String format, Object... args)` Uses `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)`
`String`	`space(int length)` Returns a string of spaces of the specified length.
`String`	`stripTags(Object obj)` Removes HTML tags from the string value of the specified object and returns the resulting string.
`String`	`stripTags(Object obj, String... allowedTags)` Removes all not allowed HTML tags from the string value of the specified object and returns the resulting string.
`String`	`truncate(Object truncateMe)` Limits the string value of 'truncateMe' to the configured max length in characters (default is 30 characters).
`String`	`truncate(Object truncateMe, int maxLength)` Limits the string value of 'truncateMe' to 'maxLength' characters.
`String`	`truncate(Object truncateMe, int maxLength, String suffix)` Limits the string value of 'truncateMe' to the specified max length in characters.
`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.
`String`	`truncate(Object truncateMe, String suffix)` Limits the string value of 'truncateMe' to the configured max length in characters (default is 30 characters).
`String`	`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, toLocale

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig
configure, getLog, initLogger, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - LIST_DELIM_KEY
```
public static final String LIST_DELIM_KEY
```
    See Also:
    
    Constant Field Values
  - LIST_FINAL_DELIM_KEY
```
public static final String LIST_FINAL_DELIM_KEY
```
    See Also:
    
    Constant Field Values
  - TRUNCATE_LENGTH_KEY
```
public static final String TRUNCATE_LENGTH_KEY
```
    See Also:
    
    Constant Field Values
  - TRUNCATE_SUFFIX_KEY
```
public static final String TRUNCATE_SUFFIX_KEY
```
    See Also:
    
    Constant Field Values
  - TRUNCATE_AT_WORD_KEY
```
public static final String TRUNCATE_AT_WORD_KEY
```
    See Also:
    
    Constant Field Values
  - CELL_LENGTH_KEY
```
public static final String CELL_LENGTH_KEY
```
    See Also:
    
    Constant Field Values
  - CELL_SUFFIX_KEY
```
public static final String CELL_SUFFIX_KEY
```
    See Also:
    
    Constant Field Values
  - DEFAULT_ALTERNATE_KEY
```
public static final String DEFAULT_ALTERNATE_KEY
```
    See Also:
    
    Constant Field Values
  - ALLOWED_TAGS_KEY
```
public static final String ALLOWED_TAGS_KEY
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - DisplayTool
```
public DisplayTool()
```
- 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 class LocaleConfig
    
    Parameters:
    
    values - configuration values
  - getListDelimiter
```
public String getListDelimiter()
```
  - setListDelimiter
```
protected void setListDelimiter(String delim)
```
  - getListFinalDelimiter
```
public String getListFinalDelimiter()
```
  - setListFinalDelimiter
```
protected void setListFinalDelimiter(String finalDelim)
```
  - getTruncateLength
```
public int getTruncateLength()
```
  - setTruncateLength
```
protected void setTruncateLength(int maxlen)
```
  - getTruncateSuffix
```
public String getTruncateSuffix()
```
  - setTruncateSuffix
```
protected void setTruncateSuffix(String suffix)
```
  - getTruncateAtWord
```
public boolean getTruncateAtWord()
```
  - setTruncateAtWord
```
protected void setTruncateAtWord(boolean atWord)
```
  - getCellSuffix
```
public String getCellSuffix()
```
  - setCellSuffix
```
protected void setCellSuffix(String suffix)
```
  - getCellLength
```
public int getCellLength()
```
  - setCellLength
```
protected void setCellLength(int maxlen)
```
  - getDefaultAlternate
```
public String getDefaultAlternate()
```
  - setDefaultAlternate
```
protected void setDefaultAlternate(String dflt)
```
  - getAllowedTags
```
public String[] getAllowedTags()
```
  - setAllowedTags
```
protected void setAllowedTags(String[] tags)
```
  - list
```
public String list(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 String list(Object list,
                   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 String list(Object list,
                   String delim,
                   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 String list(Object list,
                   String delim,
                   String finaldelim,
                   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 String format(Collection list,
                        String delim,
                        String finaldelim,
                        String property)
```
    Does the actual formatting of the collection.
    
    Parameters:
    
    list - collection of objects to format
    
    delim - delimiter
    
    finaldelim - final delimiter
    
    property - objects property to use
    
    Returns:
    
    formatted string
  - message
```
public String message(String format,
                      Object... args)
```
    Uses MessageFormat 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 of printf(String,Object...).
    
    Parameters:
    
    format - format string
    
    args - arguments
    
    Returns:
    
    formatted message
    
    Since:
    
    VelocityTools 2.0
  - printf
```
public String printf(String format,
                     Object... args)
```
    Uses 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 of message(String,Object...).
    
    Parameters:
    
    format - format string
    
    args - printf arguments
    
    Returns:
    
    formatted string
    
    Since:
    
    VelocityTools 2.0
    
    See Also:
    
    Formatter
  - truncate
```
public String truncate(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 String truncate(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 String truncate(Object truncateMe,
                       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 String truncate(Object truncateMe,
                       int maxLength,
                       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 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
```
public String space(int length)
```
    Returns a string of spaces of the specified length.
    
    Parameters:
    
    length - the number of spaces to return
    
    Returns:
    
    string of spaces
  - cell
```
public String cell(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'
    
    Returns:
    
    truncated/padded string
  - cell
```
public String cell(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
    
    Returns:
    
    truncated/padded string
  - cell
```
public String cell(Object obj,
                   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
    
    Returns:
    
    truncated/padded string
  - cell
```
public String cell(Object obj,
                   int cellsize,
                   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 placed
    
    suffix - the suffix to put at the end of any values that need truncating to indicate that they've been truncated
    
    Returns:
    
    truncated/padded string
  - capitalize
```
public String capitalize(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.
    
    Returns:
    
    capitalized string
  - uncapitalize
```
public String uncapitalize(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.
    
    Returns:
    
    uncapitalized string
  - alt
```
public Object alt(Object checkMe)
```
    Returns a configured default value if specified value is null.
    
    Parameters:
    
    checkMe - object to check
    
    Returns:
    
    a configured default value if the specified value is null.
  - alt
```
public Object alt(Object checkMe,
                  Object alternate)
```
    Returns the second argument if first argument specified is null.
    
    Parameters:
    
    checkMe - object to check
    
    alternate - alternate value
    
    Returns:
    
    the second argument if the first is null.
  - br
```
public String br(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 - source object
    
    Returns:
    
    string with added br tags
  - stripTags
```
public String stripTags(Object obj)
```
    Removes HTML tags from the string value of the specified object and returns the resulting string.
    
    Parameters:
    
    obj - source object
    
    Returns:
    
    text stripped from HTML tags
  - stripTags
```
public String stripTags(Object obj,
                        String... allowedTags)
```
    Removes all not allowed HTML tags from the string value of the specified object and returns the resulting string.
    
    Parameters:
    
    obj - source object
    
    allowedTags - An array of allowed tag names (i.e. "h1","br","img")
    
    Returns:
    
    text stripped from given HTML tags
  - plural
```
public String plural(int value,
                     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 - count
    
    singular - Singular form of a word.
    
    Returns:
    
    guessed plural
  - plural
```
public String plural(int value,
                     String singular,
                     String plural)
```
    Returns 'plural' parameter if passed 'value' is plural, otherwise 'singular' is returned.
    
    Parameters:
    
    value - count
    
    singular - Singular form of a word.
    
    plural - Plural form of a word.
    
    Returns:
    
    guessed plural
  - getProperty
```
protected Object getProperty(Object object,
                             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.
    
    Parameters:
    
    object - target object
    
    property - target property
    
    Returns:
    
    property value
    
    Throws:
    
    IllegalArgumentException - if it wasn't possible to get the object's property value
  - measure
```
public DisplayTool.Measurements measure(Object measureMe)
```
    Returns the DisplayTool.Measurements of the string value of the specified object.
    
    Parameters:
    
    measureMe - object to measure
    
    Returns:
    
    DisplayTool.Measurements object

Class DisplayTool

Nested Class Summary

Field Summary

Fields inherited from class org.apache.velocity.tools.generic.LocaleConfig

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

Constructor Summary

Method Summary

Methods inherited from class org.apache.velocity.tools.generic.LocaleConfig

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

Methods inherited from class java.lang.Object

Field Detail

LIST_DELIM_KEY

LIST_FINAL_DELIM_KEY

TRUNCATE_LENGTH_KEY

TRUNCATE_SUFFIX_KEY

TRUNCATE_AT_WORD_KEY

CELL_LENGTH_KEY

CELL_SUFFIX_KEY

DEFAULT_ALTERNATE_KEY

ALLOWED_TAGS_KEY

Constructor Detail

DisplayTool

Method Detail

configure

getListDelimiter

setListDelimiter

getListFinalDelimiter

setListFinalDelimiter

getTruncateLength

setTruncateLength

getTruncateSuffix

setTruncateSuffix

getTruncateAtWord

setTruncateAtWord

getCellSuffix

setCellSuffix

getCellLength

setCellLength

getDefaultAlternate

setDefaultAlternate

getAllowedTags

setAllowedTags

list

list

list

list

format

message

printf

truncate

truncate

truncate

truncate

truncate

space

cell

cell

cell

cell

capitalize

uncapitalize

alt

alt

br

stripTags

stripTags

plural

plural

getProperty

measure