| Title: Apache Velocity Tools Usage Summary |
| |
| ## 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 |
| |
| + [`$class` - ClassTool](#ClassTool), |
| + [`$collection` - CollectionTool](#CollectionTool) |
| + [`$context` - ContextTool](#ContextTool), |
| + [`$date` - ComparisonDateTool](#ComparisonDateTool), |
| + [`$display` - DisplayTool](#DisplayTool), |
| + [`$esc` - EscapeTool](#EscapeTool), |
| + [`$field` - FieldTool](#FieldTool), |
| + [`$json` - JsonTool](#JsonTool), |
| + [`$link` - LinkTool](#LinkTool), |
| + [`$log` - LogTool](#LogTool), |
| + [`$math` - MathTool](#MathTool), |
| + [`$number` - NumberTool](#NumberTool), |
| + [`$render` - RenderTool](#RenderTool), |
| + [`$text` - ResourceTool](#ResourceTool), |
| + [`$xml` - XmlTool](#XmlTool) |
| |
| #### View Tools |
| |
| + [`$breadcrumb` - BreadcrumbTool (beta)](#BreadcrumbTool) |
| + [`$browser` - BrowserTool](#BrowserTool), |
| + [`$context` - ViewContextTool](#ViewContextTool) |
| + [`$cookie` - CookieTool](#CookieTool), |
| + [`$import` - ImportTool](#ImportTool), |
| + [`$include` - IncludeTool](#IncludeTool), |
| + [`$link` - LinkTool](#LinkTool2), |
| + [`$pager` - PagerTool](#PagerTool), |
| + [`$params` - ParameterTool](#ParameterTool), |
| + [`$search` - AbstractSearchTool](#AbstractSearchTool), |
| |
| #### Deprecated Tools |
| |
| + [`$alt` - ~~AlternatorTool~~](apidocs/org/apache/velocity/tools/generic/AlternatorTool.html), use `#if( $foreach.index % 2)` or, for HTML, css3 `nth-child(even/odd)` selectors. |
| + [`$convert` - ~~ConversionTool~~](apidocs/org/apache/velocity/tools/generic/ConversionTool.html), use `NumberTool` for numbers formatting/parsing, `DateTool` for date/time formatting/parsing, or `CollectionTool` for string splitting. |
| + [`$sort` - ~~SortTool~~](apidocs/org/apache/velocity/tools/generic/SortTool.html), use CollectionTool sort methods |
| |
| ### Generic Tools |
| |
| #### [**AlternatorTool**](apidocs/org/apache/velocity/tools/generic/AlternatorTool.html){#AlternatorTool} - tool to create [alternators](apidocs/org/apache/velocity/tools/generic/Alternator.html) (variables that cycle through an array) |
| |
| #### [**ClassTool**](apidocs/org/apache/velocity/tools/generic/ClassTool.html) - tool meant to use Java reflection in templates{#ClassTool} |
| |
| **`$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`](http://java.sun.com/j2se/1.5.0/docs/api/java/lang/annotation/Annotation.html) of the class being inspected |
| `$class.constructors` | returns a list of [`ConstructorSub`](apidocs/org/apache/velocity/tools/generic/ClassTool.ConstructorSub.html)s 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 [`FieldSub`](apidocs/org/apache/velocity/tools/generic/ClassTool.FieldSub.html)s 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 [`MethodSub`](apidocs/org/apache/velocity/tools/generic/ClassTool.MethodSub.html)s 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**](apidocs/org/apache/velocity/tools/generic/CollectionTool.html) - tool gathering several collection utilities {#CollectionTool} |
| |
| **`$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 2<sup>nd</sup> argument |
| |
| #### [**ContextTool**](apidocs/org/apache/velocity/tools/generic/ContextTool.html) - tool allowing Velocity context introspection{#ContextTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/generic/ComparisonDateTool.html) - tool used to format, parse and compare dates{#ComparisonDateTool} |
| |
| **`$date`** | |
| --|-- |
| `config.format` = [ JVM Locale default format ] | default format (see [formatting patterns](apidocs/org/apache/velocity/tools/generic/DateTool.html#format(java.lang.String, java.lang.Object, java.util.Locale, java.util.TimeZone))) |
| `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`](apidocs/org/apache/velocity/tools/generic/ComparisonDateTool.Comparison.html) 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`](apidocs/org/apache/velocity/tools/generic/ComparisonDateTool.Comparison.html) 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{#DisplayTool} |
| |
| **`$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 (<br/>) 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**](apidocs/org/apache/velocity/tools/generic/EscapeTool.html) - tool providing some escaping facilities{#EscapeTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/generic/FieldTool.html) - tool allowing easy access to public static fields in classes, such as string constants{#FieldTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/generic/JsonTool.html) - 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**](apidocs/org/apache/velocity/tools/generic/LinkTool.html) - 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"`){#LinkTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/generic/LogTool.html) - tool to trigger logs from withing templates{#LogTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/generic/MathTool.html) - tool providing math functions{#MathTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/generic/NumberTool.html) - tool used to format numbers{#NumberTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/generic/RenderTool.html) - 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{#RenderTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/generic/ResourceTool.html) - 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')`{#ResourceTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/generic/XmlTool.html) - tool used for reading/navigating XML files; this uses dom4j under the covers to provide complete XPath support for traversing XML files{#XmlTool} |
| |
| **`$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 |
| |
| #### [**BreadcrumbTool**](apidocs/org/apache/velocity/tools/view/BreadcrumbTool.html) - (beta) Tool helping maintaining a breadcrumbs trail UI component (also called an Ariane thread). {#BreadcrumbTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/view/BrowserTool.html) - 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.{#BrowserTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/view/ViewContextTool.html) - 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`](#ContextTool){#ViewContextTool} |
| |
| **`$context`** | |
| --|-- |
| **scope** | request |
| |
| #### [**CookieTool**](apidocs/org/apache/velocity/tools/view/CookieTool.html) - tool used to read and set cookies{#CookieTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/view/ImportTool.html) - general-purpose text-importing view tool for templates{#ImportTool} |
| |
| **`$import`** | |
| --|-- |
| **scope** | request |
| `$import.read(` *url* `)` | returns the content read from the specified URL |
| |
| #### [**IncludeTool**](apidocs/org/apache/velocity/tools/view/IncludeTool.html) - 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{#IncludeTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/view/LinkTool.html) - 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`](#LinkTool) are inherited{#LinkTool2} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/view/PagerTool.html) - 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**](apidocs/org/apache/velocity/tools/view/ParameterTool.html) - tool used to parse request parameters{#ParameterTool} |
| |
| **`$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**](apidocs/org/apache/velocity/tools/view/AbstractSearchTool.html) - 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](#PagerTool){#AbstractSearchTool} |
| |
| **`$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` |
