org.apache.velocity.tools.generic
Class DisplayTool

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

@DefaultKey(value="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 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
static class DisplayTool.Measurements
          Measures the dimensions of the string given to its constructor.
 
Field Summary
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
DisplayTool()
           
 
Method Summary
 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 the DisplayTool.Measurements of the string value of the specified object.
 java.lang.String message(java.lang.String format, java.util.Collection args)
          Deprecated. Will be unnecessary with Velocity 1.6
 java.lang.String message(java.lang.String format, java.lang.Object... args)
          Uses MessageFormat to format the specified String with the specified arguments.
 java.lang.String message(java.lang.String format, java.lang.Object arg)
          Deprecated. Will be unnecessary with Velocity 1.6
 java.lang.String message(java.lang.String format, java.lang.Object arg1, java.lang.Object arg2)
          Deprecated. Will be unnecessary with Velocity 1.6
 java.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 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
 
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 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
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

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

Since:
VelocityTools 2.0

printf

public java.lang.String printf(java.lang.String format,
                               java.lang.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...).

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 placed
suffix - 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 the DisplayTool.Measurements of the string value of the specified object.



Copyright (c) 2003-2007 Apache Software Foundation