org.apache.velocity.tools.generic
Class DisplayTool

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

@DefaultKey(value="display")
public class DisplayTool
extends AbstractLockConfig

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, and methods for displaying an alternate value when a specified value is null.

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(10, "This is a long string.")
   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

Field Summary
static java.lang.String DEFAULT_ALTERNATE_KEY
           
private  java.lang.String defaultAlternate
           
private  java.lang.String defaultDelim
           
private  java.lang.String defaultFinalDelim
           
private  int defaultMaxLength
           
private  java.lang.String defaultSuffix
           
static java.lang.String LIST_DELIM_KEY
           
static java.lang.String LIST_FINAL_DELIM_KEY
           
static java.lang.String TRUNCATE_MAX_LENGTH_KEY
           
static java.lang.String TRUNCATE_SUFFIX_KEY
           
 
Fields inherited from class org.apache.velocity.tools.generic.AbstractLockConfig
LOCK_CONFIG_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.
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)
          Does the actual formatting of the collection.
 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".
protected  void setDefaultAlternate(java.lang.String dflt)
           
protected  void setListDelimiter(java.lang.String delim)
           
protected  void setListFinalDelimiter(java.lang.String finalDelim)
           
protected  void setTruncateMaxLength(int maxlen)
           
protected  void setTruncateSuffix(java.lang.String suffix)
           
 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, java.lang.String suffix)
          Limits the string value of 'truncateMe' to the configured max length in characters (default is 30 characters).
 
Methods inherited from class org.apache.velocity.tools.generic.AbstractLockConfig
configure, isConfigLocked
 
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_MAX_LENGTH_KEY

public static final java.lang.String TRUNCATE_MAX_LENGTH_KEY
See Also:
Constant Field Values

TRUNCATE_SUFFIX_KEY

public static final java.lang.String TRUNCATE_SUFFIX_KEY
See Also:
Constant Field Values

DEFAULT_ALTERNATE_KEY

public static final java.lang.String DEFAULT_ALTERNATE_KEY
See Also:
Constant Field Values

defaultDelim

private java.lang.String defaultDelim

defaultFinalDelim

private java.lang.String defaultFinalDelim

defaultMaxLength

private int defaultMaxLength

defaultSuffix

private java.lang.String defaultSuffix

defaultAlternate

private java.lang.String defaultAlternate
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.

Specified by:
configure in class AbstractLockConfig

setListDelimiter

protected void setListDelimiter(java.lang.String delim)

setListFinalDelimiter

protected void setListFinalDelimiter(java.lang.String finalDelim)

setTruncateMaxLength

protected void setTruncateMaxLength(int maxlen)

setTruncateSuffix

protected void setTruncateSuffix(java.lang.String suffix)

setDefaultAlternate

protected void setDefaultAlternate(java.lang.String dflt)

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.

format

protected java.lang.String format(java.util.Collection list,
                                  java.lang.String delim,
                                  java.lang.String finaldelim)
Does the actual formatting of the collection.


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:
obj - 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.
obj - 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:
obj - 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:
maxLength - An int with the maximum length.
obj - The value to be truncated.
suffix - A String.
Returns:
A String.

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.


Copyright (c) 2003-2007 Apache Software Foundation