Velocity Tools

Subprojects

Docs

Development

Velocity News Feed

Tools Usage Summary

You will find here a summary of all the available standard tools, sufficient for a basic integration and usage of each of them. Please refer to the javadoc for a complete reference of all their methods and properties, since only an excerpt is show here.

Index

Generic Tools

View Tools

Deprecated Tools

Generic Tools

AlternatorTool - tool to create alternators (variables that cycle through an array)

ClassTool - tool meant to use Java reflection in templates

$class
config.inspect [ = java.lang.Object ] string, class name of the class which is to be inspected
config.safeMode [ = true ] boolean, indicates whether to only show public members, fields and constructors
config.showDeprecated [ = false ] boolean, states whether deprecated members, fields and constructors are to be shown
$class.annotations returns a list of the Annotations of the class being inspected
$class.constructors returns a list of ConstructorSubs for each constructor declared in the inspected class, with the following methods and read-only properties: $ctor.name, $ctor.parameters (array of Class), $ctor.isVarArgs(), $ctor.modifiers (some were omitted)
$class.field returns a list of FieldSubs for each field declared in the inspected class, with the following read-only properties: $field.name, $field.modifiers, $field.staticValue, $field.type (some were omitted)
$class.fullName full name of the inspected class
$class.methods returns a list of MethodSubs for each method declared in the inspected class, with the following methods and read-only properties: $method.name, $method.parameters (array of Class), $method.returns, $method.isVarArgs(), $method.modifiers, $method.propertyName (If this method can be treated as a bean property in Velocity, then it will return the "bean property" equivalent of the method name), $method.isVoid() (some were omitted)
$class.name returns the simple name of the class being inspected
$class.package returns the package name of the class being inspected
$class.showDeprecated returns or sets the current showDeprecated setting
$class.super returns a new ClassTool instance that inspects the immediate superclass of the class being inspected
$class.type returns the actual Class being inspected
$class.inspect( class/object/string ) returns a new ClassTool instance that inspects the specified class or object
$class.abstract returns true if the class being inspected is abstract
$class.deprecated returns true if the class being inspected is deprecated
$class.final returns true if the class being inspected is final
$class.interface returns true if the class being inspected is an interface
$class.supportsNewInstance() returns true if a new instance of the class being inspected can be created via $class.type.newInstance()

CollectionTool - tool gathering several collection utilities

$collection
config.stringsDelimiter [ = , ] string, default delimiter for splitting strings
config.trimStrings [ = true ] boolean, indicates whether to trim splitted strings
$collection.split( string ) returns an array of strings obtained by splitting the input
$collection.sort( collection, map or array ) returns a sorted version of the input collection
$collection.sort( collection, map or array  [, property name ] ) returns a sorted version of the input collection under a spectific property ; contained objets are supposed to have the property passed as 2nd argument

ContextTool - tool allowing Velocity context introspection

$context
$context.keys returns a java.util.Set of the keys available in the current request context
$context.this returns the ViewContext currently being analyzed by this tool
$context.toolbox returns a java.util.Map of all the tools available in the current request context and their context keys
$context.values returns a java.util.Set of the values available in the current request context
$context.get( key ) returns the value for the specified key in the current request context

ComparisonDateTool - tool used to format, parse and compare dates

$date
config.format = [ JVM Locale default format ] default format (see formatting patterns)
config.locale = [ JVM Locale ] default locale
config.timezone = [ JVM timezone ] time zone
$date returns the current date and time formatted with the default format
$date.format( [ format, ] object [ , locale [ ,timezone ] ] ) formats the specified object
$date.get( format ) returns the current date and time formatted using the given format
$date.get( date style, time style ) returns the current date and time formatted using given styles, where each style is one of full, long, medium, short, default
$date.day current day in month
$date.month current month (warning: zero-based!)
$date.year current year
$date.getDay( object ) day of month of given date
$date.getMonth( object ) month of given date (warning: zero-based!)
$date.getYear( object ) year of given date
$date.format returns or sets the pattern or style to be used for formatting dates when none is specified
$date.locale returns or sets the default Locale configured for this instance
$date.timeZone returns or sets the default TimeZone configured for this instance - $date.timeZone.ID displays the ID of the currently active TimeZone
$date.systemDate gets the Date at the time this page was rendered for the system running this application
$date.toCalendar( object ) converts the given object to a java.util.Calendar
$date.toDate( object ) convers the given object to a java.util.Date
$date.whenIs( object ) returns a ComparisonDateTool.Comparison between current and specified date ; returned comparison will have properties like: $comp.years, $comp.months, $comp.weeks, $comp.days, $comp.hours, $comp.minutes, $comp.seconds, $comp.milliseconds, along with several other formatting methods
$date.whenIs( object, object ) returns a ComparisonDateTool.Comparison between the two specified dates ; returned comparison will have properties like: $comp.years, $comp.months, $comp.weeks, $comp.days, $comp.hours, $comp.minutes, $comp.seconds, $comp.milliseconds, along with several other formatting methods

[DisplayTool] - tool providing a variety of methods for controlling the output displayed by various references in your templates

$display
config.listDelim [ = ',' ] default delimiter used between items by the list formatting methods
config.listFinalDelim [ = '\'' ] default delimiter used between the last two items by the list formatting methods (defaults to ' and ')
config.truncateLength [ = 30 ] default length used by truncate(Object)
config.truncateSuffix [ = "..." ] default suffix used by the truncate methods
config.truncateAtWord [ = false ] boolean, whether to truncate at a precise character or the last fitting word
config.cellLength [ = 30 ] cell size
config.cellSuffix [ = "..." ] suffix used when cell contents need truncating
config.defaultAlternate [ = null ] alternate used by alt(Object)
config.allowedTags [ = null ] tags allowed to remain by stripTags(Object)
config.locale [ = JVM Locale ] used locale
$display.listDelimiter returns or sets the configured default delimiter used between items by the list formatting methods
$display.listFinalDelimiter returns or sets the configured default delimiter used between the last two items by the list formatting methods
$display.truncateLength returns or sets the configured default length used by truncate(Object)
$display.truncateSuffix returns or sets the default suffix used by the truncate methods
$display.truncateAtWord returns or sets whether or not to truncate at a precise character or the last fitting word
$display.cellLength returns or sets configured cell length
$display.cellSuffix returns or sets the suffix used when cell contents need truncating
$display.defaultAlternate returns or sets the configured default alternate used by alt(Object)
$display.allowedTags returns or sets the configured tags allowed to remain by stripTags(Object)
$display.alt( object [ , object ] ) returns the configured default value (or the second argument if specified) if the specified first value is null
$display.br( object ) inserts HTML line break tag (
) in front of all newline characters of the string value of the specified object and returns the resulting string
$display.capitalize( object ) changes the first character of the string value of the specified object to upper case and returns the resulting string
$display( object [ , suffix ] [ , length ] ) truncates or pads the string value of the specified object as necessary to ensure that the returned string's length equals the default or specified cell size, using the default suffix or the specified one when truncation is needed
$display.list( object [ , delim [ , finalDelim ] ] ) Formats a collection or array into a string, using the default or provided delimiter and final delimiter
$display.measure( object ) returns the measurements of the string value of the specified object
$display.message( string, object...) uses java.text.MessageFormat to format the specified string with the specified arguments. If there are no arguments, then the string is returned directly
$display.plural( count, singular [ , plural ] ) based on count, returns singular or build/specified plural
$display.printf( format, object... ) 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...)
$display.space( int ) returns a string of spaces of the specified length
$display.stripTags( object [ , allowedTags ] ) removes all not allowed HTML tags from the string value of the specified object and returns the resulting string
$display.truncate( object [ , size ] [ , suffix ] ) limits the string output of the first argument to the specified or default number of characters. If the string gets curtailed, the specified or default suffix is used as the ending of the truncated string
$display.uncapitalize( object ) changes the first character of the string value of the specified object to lower case and returns the resulting string

EscapeTool - tool providing some escaping facilities

$esc
$esc.b , $esc.backslash renders a backslash (\)
$esc.d , $esc.dollar renders a dollar sign ($)
$esc.e , $esc.exclamation renders an exclamation mark (!)
$esc.h , $esc.hash renders a hash (#)
$esc.q , $esc.quote renders a double quotation mark (")
$esc.s , $esc.singleQuote renders a single quotation mark (')
$esc.html( string ) escapes the characters in a string using HTML entities
$esc.url( string ) escapes the characters in a string using UTF-8 URL character encoding
$esc.java( string ) escapes the characters in a String using Java String rules
$esc.javascript( string ) escapes the characters in a String using JavaScript String rules
$esc.sql( string ) escapes the characters in a String to be suitable to pass to an SQL query
$esc.xml( string ) escapes the characters in a String using XML entities
$esc.propertyKey( string ) escapes the characters in a String using java.util.Properties rules for escaping keys
$esc.propertyValue( string ) escapes the characters in a String using java.util.Properties rules for escaping values

FieldTool - tool allowing easy access to public static fields in classes, such as string constants

$field
config.include [ = null ] coma-separated list of class names to include at initialization
config.storeDynamicLookups [ = true ] whether to keep fields of inspected classes
$field.get( string ) returns the value of the field with the specified name, if found
$fields.in( class/object/string ) loads all public static fields in the specified class or object

JsonTool - Tool for JSON parsing and rendering

$json
config.resource [ = null ] Sets the locale resource (file or classpath) as JSON source
config.url [ = null ] Sets the distant resource (specified as an URL) as JSON source
$json.parse(JSON content) Parse JSON content
$json.read(resource) Parse the content of a local resource
$json.fetch(URL) Parse the content of a distant resource
$json.root() Returns the root parsed JSON object or array
$json.get(index or property) Returns the value under the specified index (for an array) or named property (for a map), if present, or null
$json.keys() Returns an iterator on the root object, null if root is null or is not an object
$json.keySet() Returns the root object keys set, null if root is null or is not an object
$json.iterator() When root is an array, returns an iterator on contained elements ; when root is an object, returns an iterator on keys ; returns null otherwise
$json.size() Returns the size of the root array/object, or null
$json Returns a JSON representation of the root array or object, or null

LinkTool - tool used to format hyperlinks ; this tool is somewhat unusual in that every method that takes parameters will return a new instance of the tool that is a copy of the one the method was called upon, with the additional change specified by the method call, allowing for chained calls like href="$link.relative('foobar.html').param('id','25').anchor('section4')" (which would produce href="foobar.html?id=25#section4")

$link
config.uri [ = null ] sets the default scheme, user info, host, port, path, query, and anchor elements all at once
config.scheme [ = "http" ] sets the default scheme (http, https, mailto, ...)
config.info [ = null ] sets the default user info
config.host [ = null ] sets the default host
config.port [ = null ] sets the default port
config.requestPath [ = null ] sets the default path
config.params [ = null ] sets the defaut query parameters
config.anchor [ = null ] sets the defaut anchor
config.charset [ = "UTF-8" ] sets the defaut charset
config.xhtml [ = true ] if true, uses & as query delimiter, otherwise uses &
config.appendParameters [ = true ] sets whether or not the #setParam() method will override existing query values (false) for the same key or simply append the new value to a list of existing values (true)
config.forceRelative [ = false ] sets whether or not the #createURI() method should ignore the scheme, user, port and host values for non-opaque URIs, thus making #toString print the link as a relative one, not an absolute one ; NOTE: using #absolute() or #relative() will alter this setting accordingly on the new instances they return
$link.anchor returns the anchor set for this link
$link.path returns the path currently set for this link
$link.params returns the query data set for this link
$link.contextURI returns the URI that addresses this web application, e.g. http://myserver.net/myapp ; this string may not end with a "/"
$link.contextPath returns the context path that addresses this web application, e.g. /myapp ; this string starts with a "/" but does not end with a "/"
$link.requestPath retrieves the path for the current request regardless of whether this is a direct request or an include by the RequestDispatcher
$link.baseRef returns the full URI of this template without any query data. e.g. http://myserver.net/myapp/stuff/View.vm
$link.self this method returns a new self-referencing $link for the current request (e.g. /myapp/stuff/View.vm) ; however, the behavior can be changed via toolbox configuration to use absolute URIs and/or add the current request parameters
$link.anchor( string ) returns a new $link with the addition of the specified anchor value
$link.path( string ) returns a new $link with the addition of the specified path value
$link.relative( string ) returns a new $link with the addition of the specified relative value
$link.absolute( string ) returns a new $link with the addition of the specified absolute value
$link.params( key, value ) returns a new $link with the addition of the specified parameter
$link.encode( string ) performs URL encoding on the specified text
$link displays link

LogTool - tool to trigger logs from withing templates

$log
$log.trace( string ) emits a trace message
$log.debug( string ) emits a debug message
$log.info( string ) emits an info message
$log.warn( string ) emits a warning message
$log.error( string ) emits an error message

MathTool - tool providing math functions

$math
$math.add( object, object ) returns the sum of the numbers or null if they are invalid
$math.sub( object, object ) returns the difference of the numbers or null if they are invalid
$math.mul( object, object ) returns the product of the numbers or null if they are invalid
$math.div( object, object ) returns the quotient of the numbers or null if they are invalid
$math.pow( object, object ) returns the first number raised to the power of the second or null if they are invalid
$math.idiv( object, object ) returns the integer division of the numbers or null if they are invalid
$math.mod( object, object ) returns the integer molulus operation on the numbers or null if they are invalid
$math.max( object, object ) returns the largest of the numbers or null if they are invalid
$math.min( object, object ) returns the smallest of the numbers or null if they are invalid
$math.abs( object ) returns the absolute value of the number or null if it is invalid
$math.ceil( object ) returns the smallest integer that is not less than the given number or null if it is invalid
$math.floor( object ) returns the integer portion of the given number or null if it is invalid
$math.round( object ) returns the given number rounded to the nearest whole Integer or null if it is invalid
$math.roundTo( object, decimals ) rounds a number to the specified number of decimal places
$math.random returns a pseudo-random Double greater than or equal to 0.0 and less than 1.0
$math.random( lower, upper ) this returns a random Number within the specified range - the returned value will be greater than or equal to the first number and less than the second number - if both arguments are whole numbers then the returned number will also be, otherwise a double will be returned
$math.toInteger( object ) converts an object with a numeric value into an Integer ; valid formats are Number or a string representation of a number
$math.toDouble( object ) converts an object with a numeric value into a Double ; valid formats are Number or a string representation of a number
$math.toNumber( object ) converts an object with a numeric value into a Number ; valid formats are Number or a string representation of a number

NumberTool - tool used to format numbers

$number
config.format [ = JVM Locale number format ] default number format (depends upon the default locale by default, '#0.0' for en_US locale, '#0,0' for fr_FR, ...)
config.locale [ = JVM Locale ] default locale
$number.format returns or sets the pattern or style to be used for formatting numbers when none is specified
$number.locale returns or sets the default locale
$number.format( [ format/style, ] object [ , locale  ] ) formats the given number using the default or specified format or style, and the default or provided locale ; style is one of currency, integer, number, percent
$number.currency( object ) convenience method equivalent to $number.format("currency", $foo)
$number.integer( object ) convenience method equivalent to $number.format("integer", $foo)
$number.number( object ) convenience method equivalent to $number.format("number", $foo)
$number.percent( object ) convenience method equivalent to $number.format("percent", $foo)

RenderTool - tool that exposes methods to evaluate the given strings as VTL (Velocity Template Language) using either a pre-configured context or one you provide directly

$render
config.parse.depth [ = 20 ] default depth for recursive evaluation
config.catch.exceptions [ = true ] whether to catch exceptions during rendering
config.forceThreadSafe [ = true ] whether to force a thread-safe evaluation
$render.eval( string ) evaluates a String containing VTL using the current context, and returns the result as a String
$render.recurse( string ) recursively evaluates a String containing VTL using the current context, and returns the result as a String

ResourceTool - tool for accessing ResourceBundles and formatting messages therein ; most methods return a new object that has mostly the same methods as the original, allowing you to build up parameters elegantly and simply, rather than try to remember how to use methods with many parameters that must be in a specific order: so, you can access a resource with the key 'hello.whoever' in the 'otherStuff' bundle with one message argument like this: $text.hello.whoever.bundle('otherStuff').insert('World') instead of like this: $text.get('hello.whoever','otherStuff', $null, 'World')

$text
config.defaultBundle [ = null ] default (unique) bundle
config.bundles coma-separated list of bundles (the first one being used as the default)
config.locale [ = JVM Locale ] current locale
config.defaultLocale [ = JVM Locale ] default locale
$text.key returns the resource with the specified name, if it exists
$text.prefix.keys returns a list of the available keys starting with the given prefix
$text.key.bundle( bundle ) returns the resource with the specified name in the specified bundle, if it exists
$text.key.locale( locale ) returns a new $text that will try to find the resource with the specified name for the specified locale
$text.key.insert( value [ , value ... ] ) returns the named resource with the specified values inserted
$text.locale returns or sets the current locale

XmlTool - tool used for reading/navigating XML files; this uses dom4j under the covers to provide complete XPath support for traversing XML files

$xml
config.file target XML file
$xml.attr( string ) returns the value of the specified attribute for the first/sole Node in the internal Node list for this instance, if that Node is an Element; if it is a non-Element node type or there is no value for that attribute in this element, then this will return null
$xml.attributes() returns a Map of all attributes for the first/sole Node held internally by this instance; if that Node is not an Element, this will return null
$xml.children() returns a new XmlTool instance that wraps all the child Elements of all the current internally held nodes that are Elements themselves
$xml.find( xpath ) performs an XPath selection on the current set of Nodes held by this instance and returns a new instance that wraps those results; if the specified value is null or this instance does not currently hold any nodes, then this will return null; if the specified value, when converted to a string, does not contain a '/' character, then it has "//" prepended to it; this means that a call to $xml.find("a") is equivalent to calling $xml.find("//a"); the full range of XPath selectors is supported here
$xml.first returns a new instance that wraps only the first Node from this instance's internal Node list
$xml.last returns a new instance that wraps only the last Node from this instance's internal Node list
$xml.name asks get(Object) for "name"; if none, this will return the result of getNodeName()
$xml.nodeName returns the name of the root node; if the internal Node list has more than one Node, it will only return the name of the first node in the list
$xml.parent returns a new XmlTool instance that wraps the parent Element of the first/sole Node being wrapped by this instance
$xml.path returns the XPath that identifies the first/sole Node represented by this instance
$xml.text returns the concatenated text content of all the internally held nodes; obviously, this is most useful when only one node is held
$xml.get( number ) returns a new instance that wraps the specified Node from this instance's internal Node list
$xml.name, $xml.get( string ) this will first attempt to find an attribute with the specified name and return its value; if no such attribute exists or its value is null, this will attempt to convert the given value to a Number and get the result of get(Number); if the number conversion fails, then this will convert the object to a string; if that string does not start contain a '/', it appends the result of getPath() and a '/' to the front of it; finally, it delegates the string to the find(String) method and returns the result of that
$xml.empty returns true if there are no Nodes internally held by this instance
$xml.iterator() returns an Iterator that returns new XmlTool instances for each Node held internally by this instance; this allows VTL like #foreach($node in $xml)...#end
$xml.node() returns the first/sole Node from this instance's internal Node list, if any
$xml.parents() returns a new XmlTool instance that wraps the parent Elements of each of the Nodes being wrapped by this instance; this does not return all ancestors, just the immediate parents
$xml.parse( string ) accepts XML strings. If the XML is valid, it will return a new XmlTool instance with the XML's root as its internal node
$xml.read( filename/URL ) returns null if safe mode is on; otherwise this will accept url pointing to an XML document; it will then parse that document and return a new instance with that document's root element as its node
$xml.size()= returns the number of Nodes internally held by this instance
$xml if this instance has no XML Nodes, then this returns the result of super.toString(); otherwise, it returns the XML (as a string) of all the internally held nodes that are not Attributes; for attributes, only the value is used

View Tools

$breadcrumb
scope session
config.segment.name [ = null ] an optional custom displayed name for the specific URI segment
config.segment.url [ = null ] an optional custom displayed URL for the specific URI segment
$breadcrumb.iterator() Iterate on URI elements, like in #foreach($elem in $breadcrumb). Usefull if you want to customize the default displayed breadcrumbs trail rendered with $breadcrumb.

BrowserTool - browser-sniffing tool; it defines properties that are used to test the client browser, operating system, device, language... apart from properties related to browser version and language, all properties are booleans.

$browser
scope session
config.languagesFilter [ = null ] an optional coma-separated list of admissible languages in the webapp
$browser.languageFilter |returns or sets the current languages filter
$browser.version returns browser version
$browser.majorVersion returns browser major version
$browser.minorVersion returns browser minor version
$browser.geckoVersion version of the Gecko rendering engine for browsers belonging to the Mozilla family
$browser.browser tests for the specified browser, among: mosaic netscape nav2 nav3 nav4 nav4up nav45 nav45up nav6 nav6up navgold firefox safari ie ie3 ie4 ie4up ie5 ie5up ie55 ie55up ie6 ie6up ie7 ie7up ie8 ie8up opera opera3 opera4 opera5 opera6 opera7 opera8 opera9 lynx links w3m aol aol3 aol4 aol5 aol6 neoplanet neoplanet2 amaya icab avantgo emacs mozilla gecko webtv staroffice java hotjava httpclient lobo lotusnotes konqueror galeon kmeleon chrome
$browser.OS tests for the specified operating system, among: win16 win3x win31 win95 win98 winnt windows win32 winme win2k winxp vista dotnet mac macosx mac68k macppc os2 unix sun sun4 sun5 suni86 irix irix5 irix6 hpux hpux9 hpux10 aix aix1 aix2 aix3 aix4 linux sco unixware mpras reliant dec sinix freebsd bsd vms x11 amiga
$browser.device tests for the specified handled device, among: palm audrey iopener wap blackberry
$browser.feature tests for the given feature, among: javascript css css1 css2 dom0 dom1 dom2
$browser.robot tests for special request is issued by a known robot
$browser.robot tests for known robots: wget getright yahoo altavista lycos infoseek lwp webcrawler linkexchange slurp google java
$browser.preferredLanguageTag returns the browser's preferred langage tag (a string like 'en', 'da', 'en-US', ...), optionnaly affected by the languagesFilter configuration property
$browser.preferredLocale returns the browser's preferred locale

ViewContextTool - extension of the generic ContextTool that includes keys and values from the HttpServletRequest, HttpSession and ServletContext attributes; inherits all methods and properties from the generic ContextTool

$context
scope request

CookieTool - tool used to read and set cookies

$cookies
scope request
$cookies.add( Cookie ) Adds the cookie to the current servlet response; this does NOT add it to the current request
$cookies.add( name, value [ , expiry time ] ) adds a new Cookie with the specified name and value to the current servlet response; this does not add a Cookie to the current request
$cookies.create( name, value [ , expiry time ] ) creates a new Cookie with the specified name and value; this does not add the Cookie to the response, so the created Cookie will not be set unless you do $cookies.add($myCookie)
$cookies.delete( name ) instructs the browser to remove the specified cookie by setting it with a Max-Age of 0
$cookies.all returns a list of Cookies for this request
$cookies.name, $cookies.get( name ) returns the Cookie with the specified name, if it exists
$cookies if there are no Cookies in the request, this returns the standard Object.toString output; otherwise, it returns a pretty printed list of cookie names and values

ImportTool - general-purpose text-importing view tool for templates

$import
scope request
$import.read( url ) returns the content read from the specified URL

IncludeTool - tool allowing for transparent content negotiation in a manner mimicking Apache httpd's MultiViews; reads the default language out of the ViewToolContext as org.apache.velocity.tools.view.i18n.defaultLanguage; please note that it does NOT do the actual #include or #parse for you, but is merely to aid in include content negotiation

$include
scope request or session
config.org.apache.velocity.tools.view.i18n.defaultLanguage [ = JVM default ] this property is not searched directly in the provided tool's properties, but looked first at the Velocity context, then the servlet context, then lastly at the JVM default; this "narrow scope to wide scope" pattern makes it easy to setup language overrides at different levels within your application
$include.exists( name [ , locale ] ) checks whether or not a resource is available with the specified name and, if provided, specified language suffix
$include.find( name [ , locale / language code ] ) returns the localized name for the specified resource, with the specified Locales language suffix if specified; if one for that language is unavailable, then it will "widen" the language until one is found; if none is found at all, the name parameter is returned

LinkTool - tool used to format hyperlinks ; this tool is somewhat unusual in that every method that takes parameters will return a new instance of the tool that is a copy of the one the method was called upon, with the additional change specified by the method call, allowing for chained calls like href="$link.relative('foobar.html').param('id','25').anchor('section4')" (which would produce href="foobar.html?id=25#section4"); all methods and properties from the generic LinkTool are inherited

$link
scope request
config.includeRequestParams [ = false ] controls whether or not this tool starts off with all parameters from the last request automatically
$link.includeRequestParams returns or sets the includeRequestParams flag
$link.requestPath returns the path for the current request, regardless of whether this is a direct request or an include by the RequestDispatcher
$link.addRequestParams( [ amongThisOne [ , andThisOne ... ] ] ) adds the specified parameters (if they exist) from the current request to the query data of a copy of this instance; if no parameters are specified, then all of the current request's parameters will be added
$link.addRequestParamsExcept( [ exceptThisOne [ , andThisOne ... ] ] ) adds all of the current request's parameters to this link's query data except for those whose keys match any of the specified strings
$link.addMissingRequestParams( [ exceptThisOne [ , andThisOne ... ] ] ) adds all of the current request's parameters to this link's query data except for those whose keys match any of the specified strings or already have a value set for them in the current instance

PagerTool - tool for doing request-based pagination of items in an a list

$pager
scope request
config.newItemsKey [ = "new.items" ] key name used to search for items in request attributes
config.indexKey [ = "index" ] key name used to search for current page index in request attributes
config.itemsPerPageKey [ = "show" ] key name used to search for the number of items to be shown per page in request attributes
config.slipSizeKey [ = "slipSize" ] key name used to search for the max number of page indices to show in request attributes
config.itemsPerPage [ = 10 ] number of items per page
config.slipsize [ = 20 ] maximum number of page indices to show
$pager.newItemsKey returns or sets the key name used to search for items in request attributes
$pager.indexKey returns or sets the key name used to search for the first index in the current page in request attributes
$pager.itemsPerPageKey returns or sets the key name used to search for the number of items to be shown per page in request attributes
$pager.slipSizeKey returns or sets the key name used to search for the max number of page indices to show in request attributes
$pager.items returns or sets the current list of items
$pager.index returns or sets the first index in the current page (differs from $index.firstIndex in that it is not adjusted to fit the reality of the items available)
$pager.itemsPerPage returns or sets the number of items to show per page
$pager.slipSize returns or sets the maximum number of page indices to show
$pager.hasItems() checks whether or not the result list is empty
$pager.firstIndex returns the first index in the current page (as determined by the current index, items per page, and the number of items; differs from $index.index in that it is adjusted to fit the reality of the items available)
$pager.lastIndex returns the index of the last item on the current page of results (as determined by the current index, items per page, and the number of items)
$pager.prevIndex return the index for the previous page of items (as determined by the current index, items per page, and the number of items)
$pager.nextIndex returns the index for the next page of items (as determined by the current index, items per page, and the number of items)
$pager.page returns the current page of search items
$pager.pageDescription returns a description of the current page ("1 of n")
$pager.pageNumber returns the page number for the current index
$pager.pageNumber( integer ) returns the page number for the specified index
$pager.pagesAvailable returns the number of pages that can be made from this list given the set number of items per page
$pager.total returns the total number of items available
$pager.slip returns a Sliding List of Indices for Pages of items

ParameterTool - tool used to parse request parameters

$params 1
scope request
config.stringsDelimiter [ = <empty string> ] String which is used by the getStrings() method to split input strings - no splitting occurs if empty (the default value is ',' in the base class, org.apache.velocity.toos.generic.ValueParser).
$params.exists( name ) checks whether given request parameter exists
$params.name, $params.get( name ), $params.getString( name [ , alternate ] ) returns the parameter with the specified key as a string, if it exists; otherwise, returns the specified alternate value if specified
$params.getBoolean( name [ , alternate ] ) returns the parameter with the specified key as a java.lang.Boolean, if it exists; otherwise, returns the specified alternate Boolean if specified
$params.getNumber( name [ , alternate ] ) returns the parameter with the specified key as a java.lang.Number, if it exists; otherwise, returns the specified alternate Number if specified
$params.getDouble( name [ , alternate ] ) returns the parameter with the specified key as a java.lang.Double, if it exists; otherwise, returns the specified alternate Double if specified
$params.getInteger( name [ , alternate ] ) returns the parameter with the specified key as a java.lang.Integer, if it exists; otherwise, returns the specified alternate Integer if specified
$params.getLocale( name [ , alternate ] ) returns the parameter with the specified key as a java.util.Locale, if it exists; otherwise, returns the specified alternate Locale if specified
$params.getStrings( name ) returns the parameter(s) with the specified key in an array of strings, if any exist; otherwise, returns null
$params.getBooleans( name ) returns the parameter(s) with the specified key in an array of java.lang.Boolean, if any exist; otherwise, returns null
$params.getNumbers( name ) returns the parameter(s) with the specified key in an array of java.lang.Number, if any exist; otherwise, returns null
$params.getDoubles( name ) returns the parameter(s) with the specified key in an array of java.lang.Doubles, if any exist; otherwise, returns null
$params.getIntegers( name ) returns the parameter(s) with the specified key in an array of java.lang.Integers, if any exist; otherwise, returns null
$params.all returns the map of all parameters available for the current request

AbstractSearchTool - this tool is meant to be extended by a class defining the protected List executeQuery(Object crit) Java method; it allows doing "searching" and robust pagination of search results; the goal here is to provide a simple and uniform API for "search tools" that can be used in velocity templates (or even a standard Search.vm template); in particular, this class provides good support for result pagination and some very simple result caching; also check inherited configuration and properties from PagerTool

$search
scope request
config.criteriaKey [ = "find" ] search criteria key which is looked up in request parameters
$search.criteriaKey get or set the criteria key which is looked up in request parameters
$search.criteria returns or sets the current search criteria
$search.reset() resets the search criteria
$search.storedItems return selected items if valid, otherwise null