Modified: velocity/site/cms/trunk/content/tools/devel/generic.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/generic.mdtext?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/generic.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/generic.mdtext Tue May 17 10:44:17 2016 @@ -14,20 +14,20 @@ The dependencies required for GenericToo ## Tools -+ [AlternatorTool](javadoc/org/apache/velocity/tools/generic/AlternatorTool.html) - For creating [Alternator](javadoc/org/apache/velocity/tools/generic/Alternator.html)s to easily alternate over a set of values. -+ [ClassTool](javadoc/org/apache/velocity/tools/generic/ClassTool.html) - For simplifying reflective lookup of information about Classes and their fields, methods and constructors. -+ [ContextTool](javadoc/org/apache/velocity/tools/generic/ContextTool.html) - For convenient access to Context data and meta-data. -+ [ConversionTool](javadoc/org/apache/velocity/tools/generic/ConversionTool.html) - For converting String values to richer object types. -+ [DateTool](javadoc/org/apache/velocity/tools/generic/DateTool.html) & [ComparisonDateTool](javadoc/org/apache/velocity/tools/generic/ComparisonDateTool.html) - For manipulating, formatting, and comparing dates. -+ [DisplayTool](javadoc/org/apache/velocity/tools/generic/DisplayTool.html) - For controlling display of references (e.g. truncating values, "pretty printing" lists, and displaying alternates when a reference is null). -+ [EscapeTool](javadoc/org/apache/velocity/tools/generic/EscapeTool.html) - For common escaping needs in Velocity templates (e.g. escaping html, xml, javascript etc.). -+ [FieldTool](javadoc/org/apache/velocity/tools/generic/FieldTool.html) - For (easy) access to static fields in a class, such as string constants. -+ [LoopTool](javadoc/org/apache/velocity/tools/generic/LoopTool.html) - A convenience tool to use with #foreach loops. It wraps a list with a custom iterator to provide greater control, allowing loops to end early, skip ahead and more. -+ [LinkTool](javadoc/org/apache/velocity/tools/generic/LinkTool.html) - For creating and manipulating URIs and URLs. The API for this tool is designed to closely resemble that of the VelocityView tool of the same name. -+ [ListTool](javadoc/org/apache/velocity/tools/generic/ListTool.html) - For working with arrays and lists, treats both transparently the same. -+ [MathTool](javadoc/org/apache/velocity/tools/generic/MathTool.html) - For performing math functions. -+ [NumberTool](javadoc/org/apache/velocity/tools/generic/NumberTool.html) - For formatting and converting numbers. -+ [RenderTool](javadoc/org/apache/velocity/tools/generic/RenderTool.html) - To evaluate and render arbitrary strings of VTL, including recursive rendering. -+ [ResourceTool](javadoc/org/apache/velocity/tools/generic/ResourceTool.html) - For simplified access to ResourceBundles for internationalization or other dynamic content needs. -+ [SortTool](javadoc/org/apache/velocity/tools/generic/SortTool.html) - Used to sort collections (or arrays, iterators, etc) on any arbitary set of properties exposed by the objects contained within the collection. -+ [XmlTool](javadoc/org/apache/velocity/tools/generic/XmlTool.html) - For reading/navigating XML files. This uses dom4j under the covers and provides complete XPath support. ++ [AlternatorTool](apidocs/org/apache/velocity/tools/generic/AlternatorTool.html) - For creating [Alternator](apidocs/org/apache/velocity/tools/generic/Alternator.html)s to easily alternate over a set of values. ++ [ClassTool](apidocs/org/apache/velocity/tools/generic/ClassTool.html) - For simplifying reflective lookup of information about Classes and their fields, methods and constructors. ++ [ContextTool](apidocs/org/apache/velocity/tools/generic/ContextTool.html) - For convenient access to Context data and meta-data. ++ [ConversionTool](apidocs/org/apache/velocity/tools/generic/ConversionTool.html) - For converting String values to richer object types. ++ [DateTool](apidocs/org/apache/velocity/tools/generic/DateTool.html) & [ComparisonDateTool](apidocs/org/apache/velocity/tools/generic/ComparisonDateTool.html) - For manipulating, formatting, and comparing dates. ++ [DisplayTool](apidocs/org/apache/velocity/tools/generic/DisplayTool.html) - For controlling display of references (e.g. truncating values, "pretty printing" lists, and displaying alternates when a reference is null). ++ [EscapeTool](apidocs/org/apache/velocity/tools/generic/EscapeTool.html) - For common escaping needs in Velocity templates (e.g. escaping html, xml, javascript etc.). ++ [FieldTool](apidocs/org/apache/velocity/tools/generic/FieldTool.html) - For (easy) access to static fields in a class, such as string constants. ++ [LoopTool](apidocs/org/apache/velocity/tools/generic/LoopTool.html) - A convenience tool to use with #foreach loops. It wraps a list with a custom iterator to provide greater control, allowing loops to end early, skip ahead and more. ++ [LinkTool](apidocs/org/apache/velocity/tools/generic/LinkTool.html) - For creating and manipulating URIs and URLs. The API for this tool is designed to closely resemble that of the VelocityView tool of the same name. ++ [ListTool](apidocs/org/apache/velocity/tools/generic/ListTool.html) - For working with arrays and lists, treats both transparently the same. ++ [MathTool](apidocs/org/apache/velocity/tools/generic/MathTool.html) - For performing math functions. ++ [NumberTool](apidocs/org/apache/velocity/tools/generic/NumberTool.html) - For formatting and converting numbers. ++ [RenderTool](apidocs/org/apache/velocity/tools/generic/RenderTool.html) - To evaluate and render arbitrary strings of VTL, including recursive rendering. ++ [ResourceTool](apidocs/org/apache/velocity/tools/generic/ResourceTool.html) - For simplified access to ResourceBundles for internationalization or other dynamic content needs. ++ [SortTool](apidocs/org/apache/velocity/tools/generic/SortTool.html) - Used to sort collections (or arrays, iterators, etc) on any arbitary set of properties exposed by the objects contained within the collection. ++ [XmlTool](apidocs/org/apache/velocity/tools/generic/XmlTool.html) - For reading/navigating XML files. This uses dom4j under the covers and provides complete XPath support.
Modified: velocity/site/cms/trunk/content/tools/devel/left.nav URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/left.nav?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/left.nav (original) +++ velocity/site/cms/trunk/content/tools/devel/left.nav Tue May 17 10:44:17 2016 @@ -25,4 +25,4 @@ ## Struts * [Overview](struts.html) * [User Guide](struts-user-guide.html) -* [Tools](javadoc/org/apache/velocity/tools/struts/package-summary.html) +* [Tools](apidocs/org/apache/velocity/tools/struts/package-summary.html) Added: velocity/site/cms/trunk/content/tools/devel/maven-velocity-tools-plugin/images/velocitytools.png URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/maven-velocity-tools-plugin/images/velocitytools.png?rev=1744249&view=auto ============================================================================== Binary file - no diff available. Propchange: velocity/site/cms/trunk/content/tools/devel/maven-velocity-tools-plugin/images/velocitytools.png ------------------------------------------------------------------------------ svn:mime-type = application/octet-stream Modified: velocity/site/cms/trunk/content/tools/devel/struts-user-guide.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/struts-user-guide.mdtext?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/struts-user-guide.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/struts-user-guide.mdtext Tue May 17 10:44:17 2016 @@ -236,13 +236,13 @@ A set of seven view tools is included wi Context Key | Class | Remarks ------------|-------|-------- -$text | [MessageTool](javadoc/org/apache/velocity/tools/struts/MessageTool.html) | Provides access to the Struts application resources for internationalized text. -$errors | [ErrorTool](javadoc/org/apache/velocity/tools/struts/ErrorsTool.html) | Provides methods to check for and output Struts error messages. -$messages | [ActionMessagesTool](javadoc/org/apache/velocity/tools/struts/ActionMessagesTool.html) | Provides methods to work with Struts action messages. -$link | [StrutsLinkTool](javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html) | Provides methods to work with URIs. -$form | [FormTool](javadoc/org/apache/velocity/tools/struts/FormTool.html) | Provides miscellaneous methods to work with forms and form beans in the context of Struts applications. -$tiles | [TilesTool](javadoc/org/apache/velocity/tools/struts/TilesTool.html) | Provides miscellaneous methods to work with Tiles in the context of Struts applications. -$validator | [ValidatorTool](javadoc/org/apache/velocity/tools/struts/ValidatorTool.html) | Provides methods to dynamically generate javascript validation in the context of Struts applications. +$text | [MessageTool](apidocs/org/apache/velocity/tools/struts/MessageTool.html) | Provides access to the Struts application resources for internationalized text. +$errors | [ErrorTool](apidocs/org/apache/velocity/tools/struts/ErrorsTool.html) | Provides methods to check for and output Struts error messages. +$messages | [ActionMessagesTool](apidocs/org/apache/velocity/tools/struts/ActionMessagesTool.html) | Provides methods to work with Struts action messages. +$link | [StrutsLinkTool](apidocs/org/apache/velocity/tools/struts/StrutsLinkTool.html) | Provides methods to work with URIs. +$form | [FormTool](apidocs/org/apache/velocity/tools/struts/FormTool.html) | Provides miscellaneous methods to work with forms and form beans in the context of Struts applications. +$tiles | [TilesTool](apidocs/org/apache/velocity/tools/struts/TilesTool.html) | Provides miscellaneous methods to work with Tiles in the context of Struts applications. +$validator | [ValidatorTool](apidocs/org/apache/velocity/tools/struts/ValidatorTool.html) | Provides methods to dynamically generate javascript validation in the context of Struts applications. Note: The shown keys are the recommended values. They can be changed in the configuration. @@ -266,5 +266,5 @@ Then, the following script... false whatever -Please see the [Tool Reference Documentation](javadoc/org/apache/velocity/tools/struts/package-summary.html) for more details about the view tools. Furthermore, the Velocity/Struts [example application](index.html#Download) comes with several working examples that show how these tools are used. +Please see the [Tool Reference Documentation](apidocs/org/apache/velocity/tools/struts/package-summary.html) for more details about the view tools. Furthermore, the Velocity/Struts [example application](index.html#Download) comes with several working examples that show how these tools are used. Modified: velocity/site/cms/trunk/content/tools/devel/struts.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/struts.mdtext?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/struts.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/struts.mdtext Tue May 17 10:44:17 2016 @@ -30,15 +30,15 @@ The dependencies required for VelocitySt These are in addition to tools provided by [GenericTools](generic.html#Tools) and [VelocityView](view.html#Tools). -+ [ActionMessagesTool](javadoc/org/apache/velocity/tools/struts/ActionMessagesTool.html) - For accessing/displaying Struts action messages. -+ [ErrorTool](javadoc/org/apache/velocity/tools/struts/ErrorsTool.java) - For accessing/displaying Struts error messages. -+ [FormTool](javadoc/org/apache/velocity/tools/struts/FormTool.html) - For working with HTML forms in Struts apps. -+ [MessageResourcesTool](javadoc/org/apache/velocity/tools/struts/MessageResourcesTool.html) - Abstract view tool that provides access to Struts message resources. -+ [MessageTool](javadoc/org/apache/velocity/tools/struts/MessageTool.html) - Provides methods to render Struts application resources (for i18n and other textual content access). -+ [SecureLinkTool](javadoc/org/apache/velocity/tools/struts/SecureLinkTool.html) - For using Struts SSL Extensions. It has the same interface as [StrutsLinkTool](javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html) and can function as a substitute if Struts 1.x and SSL Ext are installed. -+ [StrutsLinkTool](javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html) - Subclass of [LinkTool](javadoc/org/apache/velocity/tools/view/LinkTool.html) for creating URI links in Struts by adding support for Struts actions and forwards. -+ [TilesTool](javadoc/org/apache/velocity/tools/struts/TilesTool.html) - For using Struts-Tiles (not for Tiles 2!) in Velocity. -+ [ValidatorTool](javadoc/org/apache/velocity/tools/struts/ValidatorTool.html) - Uses Struts-Validator to produce client side javascript validation for your forms. ++ [ActionMessagesTool](apidocs/org/apache/velocity/tools/struts/ActionMessagesTool.html) - For accessing/displaying Struts action messages. ++ [ErrorTool](apidocs/org/apache/velocity/tools/struts/ErrorsTool.html) - For accessing/displaying Struts error messages. ++ [FormTool](apidocs/org/apache/velocity/tools/struts/FormTool.html) - For working with HTML forms in Struts apps. ++ [MessageResourcesTool](apidocs/org/apache/velocity/tools/struts/MessageResourcesTool.html) - Abstract view tool that provides access to Struts message resources. ++ [MessageTool](apidocs/org/apache/velocity/tools/struts/MessageTool.html) - Provides methods to render Struts application resources (for i18n and other textual content access). ++ [SecureLinkTool](apidocs/org/apache/velocity/tools/struts/SecureLinkTool.html) - For using Struts SSL Extensions. It has the same interface as [StrutsLinkTool](apidocs/org/apache/velocity/tools/struts/StrutsLinkTool.html) and can function as a substitute if Struts 1.x and SSL Ext are installed. ++ [StrutsLinkTool](apidocs/org/apache/velocity/tools/struts/StrutsLinkTool.html) - Subclass of [LinkTool](apidocs/org/apache/velocity/tools/view/LinkTool.html) for creating URI links in Struts by adding support for Struts actions and forwards. ++ [TilesTool](apidocs/org/apache/velocity/tools/struts/TilesTool.html) - For using Struts-Tiles (not for Tiles 2!) in Velocity. ++ [ValidatorTool](apidocs/org/apache/velocity/tools/struts/ValidatorTool.html) - Uses Struts-Validator to produce client side javascript validation for your forms. ## Examples Modified: velocity/site/cms/trunk/content/tools/devel/tools-summary.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/tools-summary.mdtext?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/tools-summary.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/tools-summary.mdtext Tue May 17 10:44:17 2016 @@ -38,20 +38,20 @@ You will find here a summary of all the #### Struts Tools -+ [ActionMessagesTool](javadoc/org/apache/velocity/tools/struts/ActionMessagesTool.html), -+ [ErrorsTool](javadoc/org/apache/velocity/tools/struts/ErrorsTool.html), -+ [FormTool](javadoc/org/apache/velocity/tools/struts/FormTool.html), -+ [MessageResourcesTool](javadoc/org/apache/velocity/tools/struts/MessageResourcesTool.html), -+ [MessageTool](javadoc/org/apache/velocity/tools/struts/MessageTool.html), -+ [SecureLinkTool](javadoc/org/apache/velocity/tools/struts/SecureLinkTool.html), -+ [StrutsLinkTool](javadoc/org/apache/velocity/tools/struts/StrutsLinkTool.html), -+ [TilesTool](javadoc/org/apache/velocity/tools/struts/TilesTool.html), -+ [ValidatorTool](javadoc/org/apache/velocity/tools/struts/ValidatorTool.html) ++ [ActionMessagesTool](apidocs/org/apache/velocity/tools/struts/ActionMessagesTool.html), ++ [ErrorsTool](apidocs/org/apache/velocity/tools/struts/ErrorsTool.html), ++ [FormTool](apidocs/org/apache/velocity/tools/struts/FormTool.html), ++ [MessageResourcesTool](apidocs/org/apache/velocity/tools/struts/MessageResourcesTool.html), ++ [MessageTool](apidocs/org/apache/velocity/tools/struts/MessageTool.html), ++ [SecureLinkTool](apidocs/org/apache/velocity/tools/struts/SecureLinkTool.html), ++ [StrutsLinkTool](apidocs/org/apache/velocity/tools/struts/StrutsLinkTool.html), ++ [TilesTool](apidocs/org/apache/velocity/tools/struts/TilesTool.html), ++ [ValidatorTool](apidocs/org/apache/velocity/tools/struts/ValidatorTool.html) ### Generic Tools -#### [**AlternatorTool**](javadoc/org/apache/velocity/tools/generic/AlternatorTool.html){#AlternatorTool} - tool to create [alternators](javadoc/org/apache/velocity/tools/generic/Alternator.java) (variables that cycle through an array) +#### [**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) **`$alternator`** | --|-- @@ -66,7 +66,7 @@ You will find here a summary of all the `$alt.shift` | shifts to next value `$alt.auto` | read/write property stating if this is an automatic alternator -#### [**ClassTool**](javadoc/org/apache/velocity/tools/generic/ClassTool.html) - tool meant to use Java reflection in templates{#ClassTool} +#### [**ClassTool**](apidocs/org/apache/velocity/tools/generic/ClassTool.html) - tool meant to use Java reflection in templates{#ClassTool} **`$class`** | --|-- @@ -74,10 +74,10 @@ You will find here a summary of all the `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`](javadoc/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`](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.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`](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.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 @@ -90,7 +90,7 @@ You will find here a summary of all the `$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()` -#### [**ContextTool**](javadoc/org/apache/velocity/tools/generic/ContextTool.html) - tool allowing Velocity context introspection{#ContextTool} +#### [**ContextTool**](apidocs/org/apache/velocity/tools/generic/ContextTool.html) - tool allowing Velocity context introspection{#ContextTool} **`$context`** | --|-- @@ -100,7 +100,7 @@ You will find here a summary of all the `$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 -#### [**ConversionTool**](javadoc/org/apache/velocity/tools/generic/ConversionTool.html) - tool allowing conversions between datatypes{#ConversionTool} +#### [**ConversionTool**](apidocs/org/apache/velocity/tools/generic/ConversionTool.html) - tool allowing conversions between datatypes{#ConversionTool} **`$convert`** | --|-- @@ -117,11 +117,11 @@ You will find here a summary of all the `$convert.to`*Type*`(` *object* `)` | converts an object to an instance of *Type*, where *Type* can be one of `Boolean`, `Calendar`, `Date`, `Double`, `Integer`, `Locale`, `Number`, `String` `$convert.to`*Type*`s(` *object* `)` | converts an array, Collection, delimited String, or object to an array of *Type*s, where *Type* can be one of `Boolean`, `Calendar`, `Date`, `Double`, `Integer`, `Locale`, `Number`, `String` -#### [**ComparisonDateTool**](javadoc/org/apache/velocity/tools/generic/ComparisonDateTool.html) - tool used to format, parse and compare dates{#ComparisonDateTool} +#### [**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](javadoc/org/apache/velocity/tools/generic/DateTool.html#format(java.lang.String, java.lang.Object, java.util.Locale, java.util.TimeZone))) +`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 @@ -140,8 +140,8 @@ You will find here a summary of all the `$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`](javadoc/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`](javadoc/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 +`$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} @@ -180,7 +180,7 @@ You will find here a summary of all the `$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**](javadoc/org/apache/velocity/tools/generic/EscapeTool.html) - tool providing some escaping facilities{#EscapeTool} +#### [**EscapeTool**](apidocs/org/apache/velocity/tools/generic/EscapeTool.html) - tool providing some escaping facilities{#EscapeTool} **`$esc`** | --|-- @@ -199,7 +199,7 @@ You will find here a summary of all the `$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**](javadoc/org/apache/velocity/tools/generic/FieldTool.html) - tool allowing easy access to public static fields in classes, such as string constants{#FieldTool} +#### [**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`** | --|-- @@ -208,7 +208,7 @@ You will find here a summary of all the `$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 -#### [**LinkTool**](javadoc/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} +#### [**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`** | --|-- @@ -240,7 +240,7 @@ You will find here a summary of all the `$link.encode(` *string* `)` | performs URL encoding on the specified text `$link` | displays link -#### [**MathTool**](javadoc/org/apache/velocity/tools/generic/MathTool.html) - tool providing math functions{#MathTool} +#### [**MathTool**](apidocs/org/apache/velocity/tools/generic/MathTool.html) - tool providing math functions{#MathTool} **`$math`** | --|-- @@ -264,7 +264,7 @@ You will find here a summary of all the `$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**](javadoc/org/apache/velocity/tools/generic/NumberTool.html) - tool used to format numbers{#NumberTool} +#### [**NumberTool**](apidocs/org/apache/velocity/tools/generic/NumberTool.html) - tool used to format numbers{#NumberTool} **`$number`** | --|-- @@ -278,7 +278,7 @@ You will find here a summary of all the `$number.number(` *object* `)` | convenience method equivalent to `$number.format("number", $foo)` `$number.percent(` *object* `)` | convenience method equivalent to `$number.format("percent", $foo)` -#### [**RenderTool**](javadoc/org/apache/velocity/tools/generic/RenderTool.html" name="RenderTool">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{#RenderTool} +#### [**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`** | --|-- @@ -288,13 +288,13 @@ You will find here a summary of all the `$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 -#### [**SortTool**](javadoc/org/apache/velocity/tools/generic/SortTool.html) - tool used to sort collections{#SortTool} +#### [**SortTool**](apidocs/org/apache/velocity/tools/generic/SortTool.html) - tool used to sort collections{#SortTool} **`$sort`** | --|-- `$sorter.sort(` *collection* [ , *property / property list* ] `)` | sorts the values of the specified `Collection`, `Map`, or array of `Objects`, either by their natural order or according to the values returned by the specified property or list of properties -#### [**ResourceTool**](javadoc/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} +#### [**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`** | --|-- @@ -309,7 +309,7 @@ You will find here a summary of all the `$text.`*key*`.insert(` *value* [ , *value* ... ] `)` | returns the named resource with the specified values inserted `$text.locale` | returns or sets the current locale -#### [**XmlTool**](javadoc/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} +#### [**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`** | --|-- @@ -338,7 +338,7 @@ You will find here a summary of all the ### View Tools -#### [**BrowserTool**](javadoc/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} +#### [**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`** | --|-- @@ -358,13 +358,13 @@ You will find here a summary of all the `$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**](javadoc/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} +#### [**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**](javadoc/org/apache/velocity/tools/view/CookieTool.html) - tool used to read and set cookies{#CookieTool} +#### [**CookieTool**](apidocs/org/apache/velocity/tools/view/CookieTool.html) - tool used to read and set cookies{#CookieTool} **`$cookies`** | --|-- @@ -377,14 +377,14 @@ You will find here a summary of all the `$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**](javadoc/org/apache/velocity/tools/view/ImportTool.html) - general-purpose text-importing view tool for templates{#ImportTool} +#### [**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**](javadoc/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} +#### [**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`** | --|-- @@ -393,7 +393,7 @@ You will find here a summary of all the `$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**](javadoc/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} +#### [**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`** | --|-- @@ -405,7 +405,7 @@ You will find here a summary of all the `$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**](javadoc/org/apache/velocity/tools/view/PagerTool.html) - tool for doing request-based pagination of items in an a list +#### [**PagerTool**](apidocs/org/apache/velocity/tools/view/PagerTool.html) - tool for doing request-based pagination of items in an a list **`$pager`** | --|-- @@ -437,7 +437,7 @@ You will find here a summary of all the `$pager.total` | returns the total number of items available `$pager.slip` | returns a Sliding List of Indices for Pages of items -#### [**ParameterTool**](javadoc/org/apache/velocity/tools/view/ParameterTool.html) - tool used to parse request parameters{#ParameterTool} +#### [**ParameterTool**](apidocs/org/apache/velocity/tools/view/ParameterTool.html) - tool used to parse request parameters{#ParameterTool} **`$params`** |1 --|-- @@ -456,7 +456,7 @@ You will find here a summary of all the `$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**](javadoc/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} +#### [**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`** | --|-- Modified: velocity/site/cms/trunk/content/tools/devel/upgrading.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/upgrading.mdtext?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/upgrading.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/upgrading.mdtext Tue May 17 10:44:17 2016 @@ -37,16 +37,16 @@ The extra packages had proved superfluou Some specific ones to watch out for are as follows. If you directly referenced: -+ VelocityViewServlet, it is now at [org.apache.velocity.tools.view.VelocityViewServlet](javadoc/org/apache/velocity/tools/view/VelocityViewServlet.html) -+ VelocityLayoutServlet, it is now at [org.apache.velocity.tools.view.VelocityLayoutServlet](javadoc/org/apache/velocity/tools/view/VelocityLayoutServlet.html) -+ WebappLoader, it is now at [javadoc/org/apache/velocity/tools/view/WebappResourceLoader.html">org.apache.velocity.tools.view.WebappResourceLoader] -+ ViewContext, it is now at [org.apache.velocity.tools.view.ViewContext](javadoc/org/apache/velocity/tools/view/ViewContext.html) -+ ServletLogger, it has been replaced by [org.apache.velocity.tools.view.ServletLogChute](javadoc/org/apache/velocity/tools/view/ServletLogChute.html) -+ ServletUtils, it is now at [org.apache.velocity.tools.view.ServletUtils](javadoc/org/apache/velocity/tools/view/ServletUtils.html) -+ BrowserSniffer, it is now at [org.apache.velocity.tools.view.BrowserTool](javadoc/org/apache/velocity/tools/view/BrowserTool.html) -+ AbstractPagerTool, it is now at [org.apache.velocity.tools.view.PagerTool](javadoc/org/apache/velocity/tools/view/PagerTool.html) -+ ParameterParser, it is now at [org.apache.velocity.tools.view.ParameterTool](javadoc/org/apache/velocity/tools/view/ParameterTool.html) -+ ContextTool, it is now at [org.apache.velocity.tools.view.ViewContextTool](javadoc/org/apache/velocity/tools/view/ViewContextTool.html) ++ VelocityViewServlet, it is now at [org.apache.velocity.tools.view.VelocityViewServlet](apidocs/org/apache/velocity/tools/view/VelocityViewServlet.html) ++ VelocityLayoutServlet, it is now at [org.apache.velocity.tools.view.VelocityLayoutServlet](apidocs/org/apache/velocity/tools/view/VelocityLayoutServlet.html) ++ WebappLoader, it is now at [org.apache.velocity.tools.view.WebappResourceLoader](apidocs/org/apache/velocity/tools/view/WebappResourceLoader.html) ++ ViewContext, it is now at [org.apache.velocity.tools.view.ViewContext](apidocs/org/apache/velocity/tools/view/ViewContext.html) ++ ServletLogger, it has been replaced by [org.apache.velocity.tools.view.ServletLogChute](apidocs/org/apache/velocity/tools/view/ServletLogChute.html) ++ ServletUtils, it is now at [org.apache.velocity.tools.view.ServletUtils](apidocs/org/apache/velocity/tools/view/ServletUtils.html) ++ BrowserSniffer, it is now at [org.apache.velocity.tools.view.BrowserTool](apidocs/org/apache/velocity/tools/view/BrowserTool.html) ++ AbstractPagerTool, it is now at [org.apache.velocity.tools.view.PagerTool](apidocs/org/apache/velocity/tools/view/PagerTool.html) ++ ParameterParser, it is now at [org.apache.velocity.tools.view.ParameterTool](apidocs/org/apache/velocity/tools/view/ParameterTool.html) ++ ContextTool, it is now at [org.apache.velocity.tools.view.ViewContextTool](apidocs/org/apache/velocity/tools/view/ViewContextTool.html) **NOTE:** If you are still using the old toolbox.xml format do NOT update the tool paths in that file! First, [update your configuration](#Configuration), otherwise your tools may not work as expected. Also, this is not a complete list. Please take note of all deprecation warnings and notices when compiling and running your app. @@ -56,32 +56,32 @@ Along with the class renamings above hav **XMLToolboxManager** was the the central tool management class in Tools 1.x. If you used it or **ServletToolboxManager** you were probably a more advanced user or a framework developer working to integrate VelocityTools support. If so, you should go read [this document](frameworks.html). If you used XMLToolboxManager directly, you should familiarize yourself with these classes: -+ [ToolManager](javadoc/org/apache/velocity/tools/ToolManager.html) -+ [ConfigurationUtils](javadoc/org/apache/velocity/tools/config/ConfigurationUtils.html) -+ [FactoryConfiguration](javadoc/org/apache/velocity/tools/config/FactoryConfiguration.html) -+ [ToolboxFactory](javadoc/org/apache/velocity/tools/ToolboxFactory.html) -+ [ToolContext](javadoc/org/apache/velocity/tools/ToolContext.html) ++ [ToolManager](apidocs/org/apache/velocity/tools/ToolManager.html) ++ [ConfigurationUtils](apidocs/org/apache/velocity/tools/config/ConfigurationUtils.html) ++ [FactoryConfiguration](apidocs/org/apache/velocity/tools/config/FactoryConfiguration.html) ++ [ToolboxFactory](apidocs/org/apache/velocity/tools/ToolboxFactory.html) ++ [ToolContext](apidocs/org/apache/velocity/tools/ToolContext.html) If you used ServletToolboxManager directly, you should learn about all of the above classes (except perhaps ToolManager) and the following ones as well: -+ [VelocityView](javadoc/org/apache/velocity/tools/view/VelocityView.html) -+ [ViewToolContext](javadoc/org/apache/velocity/tools/view/ViewToolContext.html) -+ [ServletUtils](javadoc/org/apache/velocity/tools/view/ServletUtils.html) ++ [VelocityView](apidocs/org/apache/velocity/tools/view/VelocityView.html) ++ [ViewToolContext](apidocs/org/apache/velocity/tools/view/ViewToolContext.html) ++ [ServletUtils](apidocs/org/apache/velocity/tools/view/ServletUtils.html) -**NOTE:** For the vast majority of users and developers, [ToolManager](javadoc/org/apache/velocity/tools/ToolManager.html) or [VelocityView](javadoc/org/apache/velocity/tools/view/VelocityView.html) should be all they really need to work with directly. Don't waste time trying to manage <code>Toolbox</code> es yourself until you are sure that ToolManager/VelocityView can't do the job for you. +**NOTE:** For the vast majority of users and developers, [ToolManager](apidocs/org/apache/velocity/tools/ToolManager.html) or [VelocityView](apidocs/org/apache/velocity/tools/view/VelocityView.html) should be all they really need to work with directly. Don't waste time trying to manage <code>Toolbox</code> es yourself until you are sure that ToolManager/VelocityView can't do the job for you. All of the upgrades to tool management allowed some GenericTool classes to perform functions previously only possible to implement in VelocityView tools. As such, some VelocityView subclasses of generic tools have become obsolete. If you used: -+ ViewRenderTool, you should now just use [`org.apache.velocity.tools.generic.RenderTool`](javadoc/org/apache/velocity/tools/generic/RenderTool.html) -+ ViewResourceTool, you should now just use [`org.apache.velocity.tools.generic.ResourceTool`](javadoc/org/apache/velocity/tools/generic/ResourceTool.html) ++ ViewRenderTool, you should now just use [`org.apache.velocity.tools.generic.RenderTool`](apidocs/org/apache/velocity/tools/generic/RenderTool.html) ++ ViewResourceTool, you should now just use [`org.apache.velocity.tools.generic.ResourceTool`](apidocs/org/apache/velocity/tools/generic/ResourceTool.html) ### Configuration in 2.0 -Since Tools 2 does lazy-loading of tools, it now makes sense to have almost all tools available by default for most uses, as there is minimal overhead for that at startup and essentially no cost at runtime unless/until the tool is used. So, in Tools 2, unless the user is doing something to trigger the "deprecation support mode" for VelocityView (using the old toolbox.xml format would do this) or explicitly telling [VelocityView](javadoc/org/apache/velocity/tools/view/VelocityView.html) not to load the default tools, then all of the supported, standard VelocityTools will be automatically made available by default. If you don't custom configure any of the provided tools and don't have any custom tools of your own, then you don't actually need a configuration at all! Tools 2 comes with a default tools.xml file each for GenericTools, VelocityView and VelocityStruts, and the [ToolManager](javadoc/org/apache/velocity/tools/ToolManager.html), [VelocityViewServlet](javadoc/org/apache/veloc ity/tools/view/VelocityViewServlet.html), [VelocityLayoutServlet](javadoc/org/apache/velocity/tools/view/VelocityLayoutServlet.html) and [VelocityViewTag](javadoc/org/apache/velocity/tools/view/jsp/VelocityViewTag.html) will all automatically look for and load those unless you are using a deprecated toolbox.xml file or explicitly tell them not to by adding the init-param `org.apache.velocity.tools.loadDefaults` with the value of false to the relevant servlet. +Since Tools 2 does lazy-loading of tools, it now makes sense to have almost all tools available by default for most uses, as there is minimal overhead for that at startup and essentially no cost at runtime unless/until the tool is used. So, in Tools 2, unless the user is doing something to trigger the "deprecation support mode" for VelocityView (using the old toolbox.xml format would do this) or explicitly telling [VelocityView](apidocs/org/apache/velocity/tools/view/VelocityView.html) not to load the default tools, then all of the supported, standard VelocityTools will be automatically made available by default. If you don't custom configure any of the provided tools and don't have any custom tools of your own, then you don't actually need a configuration at all! Tools 2 comes with a default tools.xml file each for GenericTools, VelocityView and VelocityStruts, and the [ToolManager](apidocs/org/apache/velocity/tools/ToolManager.html), [VelocityViewServlet](apidocs/org/apache/veloc ity/tools/view/VelocityViewServlet.html), [VelocityLayoutServlet](apidocs/org/apache/velocity/tools/view/VelocityLayoutServlet.html) and [VelocityViewTag](apidocs/org/apache/velocity/tools/view/jsp/VelocityViewTag.html) will all automatically look for and load those unless you are using a deprecated toolbox.xml file or explicitly tell them not to by adding the init-param `org.apache.velocity.tools.loadDefaults` with the value of false to the relevant servlet. If you do need a configuration, you should update your configuration to one of the new formats. Easiest would be to go from the old xml format to [the new xml format](config-xml.html). Remember, you can just leave out standard tools that you don't do any configuration of, as your configuration will just be added to the default one (again, unless the default behavior is turned off). Also, do note that all VelocityView tools have [changed packages and/or names](#Renamings-in-2.0); please avoid using the deprecated versions as those will eventually be removed. -If you are largely happy with the default tools.xml configuration, but wish to override just a few parts, you can override them with your own file. Tool configurations are key-centric. If you just want to provide a different default format for the [DateTool](javadoc/org/apache/velocity/tools/generic/DateTool.html) and a second bundle for the ResourceTool, your tools.xml can be just: +If you are largely happy with the default tools.xml configuration, but wish to override just a few parts, you can override them with your own file. Tool configurations are key-centric. If you just want to provide a different default format for the [DateTool](apidocs/org/apache/velocity/tools/generic/DateTool.html) and a second bundle for the ResourceTool, your tools.xml can be just: <tools> <toolbox scope="application"> @@ -104,11 +104,11 @@ Please see the [framework integration](f Those of you who write your own custom tools may want to make a few changes to upgrade your custom tools to do things the "Tools 2 way". Here's a few quick starts for that, though this doesn't cover everything. More details can be found in the [instructions for creating tools](creating-tools.html). -**Naming:** The recommended practice is to give a tool to be used as `$foo` the name `FooTool` . This is not required but is a convention that keeps things easy follow and learn. If you have to name a tool FooBarUtility but want it to be `$foo` in templates, the second best thing is to provide a [`@DefaultKey("foo")`](javadoc/org/apache/velocity/tools/config/DefaultKey.html) annotation on the class, though this introduces a dependency on VelocityTools. As a last resort, if you are providing tools for a framework or otherwise can influence or control the configuration, you might consider providing a default configuration -- perhaps even one automatically discoverable by [ConfigurationUtils](javadoc/org/apache/velocity/tools/config/ConfigurationUtils.html) -- to set the tool's key for your users. +**Naming:** The recommended practice is to give a tool to be used as `$foo` the name `FooTool` . This is not required but is a convention that keeps things easy follow and learn. If you have to name a tool FooBarUtility but want it to be `$foo` in templates, the second best thing is to provide a [`@DefaultKey("foo")`](apidocs/org/apache/velocity/tools/config/DefaultKey.html) annotation on the class, though this introduces a dependency on VelocityTools. As a last resort, if you are providing tools for a framework or otherwise can influence or control the configuration, you might consider providing a default configuration -- perhaps even one automatically discoverable by [ConfigurationUtils](apidocs/org/apache/velocity/tools/config/ConfigurationUtils.html) -- to set the tool's key for your users. -**Scoping:** If your tool is only meant to be used in a particular scope, it's recommended that you give the class a [`@ValidScope(Scope.REQUEST)`](javadoc/org/apache/velocity/tools/config/ValidScope.html) annotation as well. If you only want to ban a particular scope and allow all others, you could provide a [`@InvalidScope(Scope.APPLICATION)`](javadoc/org/apache/velocity/tools/config/InvalidScope.html) annotation on the class. The [`Scope`](javadoc/org/apache/velocity/tools/Scope.html) class provides constants for REQUEST, SESSION, and APPLICATION. Other scopes are now theoretically possible, but only a little work and no testing has been done there at this point. +**Scoping:** If your tool is only meant to be used in a particular scope, it's recommended that you give the class a [`@ValidScope(Scope.REQUEST)`](apidocs/org/apache/velocity/tools/config/ValidScope.html) annotation as well. If you only want to ban a particular scope and allow all others, you could provide a [`@InvalidScope(Scope.APPLICATION)`](apidocs/org/apache/velocity/tools/config/InvalidScope.html) annotation on the class. The [`Scope`](apidocs/org/apache/velocity/tools/Scope.html) class provides constants for REQUEST, SESSION, and APPLICATION. Other scopes are now theoretically possible, but only a little work and no testing has been done there at this point. -**Configuration:** If you have a configurable tool whose configuration should not changed by the templates which use it, then consider having your tool extend the [SafeConfig](javadoc/org/apache/velocity/tools/generic/SafeConfig.html) class (or [FormatConfig](javadoc/org/apache/velocity/tools/generic/FormatConfig.html) or [LocaleConfig](javadoc/org/apache/velocity/tools/generic/LocaleConfig.html)). These safely standardize configuration of these common configuration properties. Also take note that the `configure(Map)` and `init(Object)` methods have been changed into just the `configure(Map)` and individual setter methods (e.g. `setRequest`, `setSession`, etc). Basically, when it's time to instantiate a tool, the tool manager will gather all the "configuration properties" for that tool, its toolbox, etc and combine it into a single map with the "init data" (context, request, session, etc). The manager searches for relevant setter methods that accept that data and also for a `confi gure(Map)` method. The setters get what they're asking for (if available) and the `configure()` method accepts the whole combined `Map`. The upshot of this approach is that tools no longer need to conform to any interfaces or patterns. In fact, it's possible to write a FooTool that doesn't know anything about any VelocityTools classes whatsoever and yet be fully instantiable and configurable by VelocityTools. Your tools don't need to know about anything except what they need to know about. +**Configuration:** If you have a configurable tool whose configuration should not changed by the templates which use it, then consider having your tool extend the [SafeConfig](apidocs/org/apache/velocity/tools/generic/SafeConfig.html) class (or [FormatConfig](apidocs/org/apache/velocity/tools/generic/FormatConfig.html) or [LocaleConfig](apidocs/org/apache/velocity/tools/generic/LocaleConfig.html)). These safely standardize configuration of these common configuration properties. Also take note that the `configure(Map)` and `init(Object)` methods have been changed into just the `configure(Map)` and individual setter methods (e.g. `setRequest`, `setSession`, etc). Basically, when it's time to instantiate a tool, the tool manager will gather all the "configuration properties" for that tool, its toolbox, etc and combine it into a single map with the "init data" (context, request, session, etc). The manager searches for relevant setter methods that accept that data and also for a `confi gure(Map)` method. The setters get what they're asking for (if available) and the `configure()` method accepts the whole combined `Map`. The upshot of this approach is that tools no longer need to conform to any interfaces or patterns. In fact, it's possible to write a FooTool that doesn't know anything about any VelocityTools classes whatsoever and yet be fully instantiable and configurable by VelocityTools. Your tools don't need to know about anything except what they need to know about. ## Upgrading to 1.4 Modified: velocity/site/cms/trunk/content/tools/devel/view-layoutservlet.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/view-layoutservlet.mdtext?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/view-layoutservlet.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/view-layoutservlet.mdtext Tue May 17 10:44:17 2016 @@ -8,7 +8,7 @@ This is an extension to the basic Veloci Since this class is an extension of the VelocityViewServlet (VVS), to use it simply change the servlet-class value of the web.xml entry to the following class: -[org.apache.velocity.tools.view.servlet.VelocityLayoutServlet](javadoc/org/apache/velocity/tools/view/servlet/VelocityLayoutServlet.html) +[org.apache.velocity.tools.view.servlet.VelocityLayoutServlet](apidocs/org/apache/velocity/tools/view/servlet/VelocityLayoutServlet.html) ## Configuration Settings Modified: velocity/site/cms/trunk/content/tools/devel/view-servlet.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/view-servlet.mdtext?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/view-servlet.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/view-servlet.mdtext Tue May 17 10:44:17 2016 @@ -2,10 +2,10 @@ Title: Apache Velocity Tools - VelocityV ## Overview -This page is still unfinished. Much of this needs to be moved or at least copied to a VelocityView page, as it applies to anything using a [VelocityView](javadoc/org/apache/velocity/tools/view/VelocityView.html) instance under the covers (including the [VelocityViewTag](view-tag.html)). [Help is welcome!](index.html#Contribution) +This page is still unfinished. Much of this needs to be moved or at least copied to a VelocityView page, as it applies to anything using a [VelocityView](apidocs/org/apache/velocity/tools/view/VelocityView.html) instance under the covers (including the [VelocityViewTag](view-tag.html)). [Help is welcome!](index.html#Contribution) {.note} -[Javadoc is here](javadoc/org/apache/velocity/tools/view/VelocityViewServlet.html). +[Javadoc is here](apidocs/org/apache/velocity/tools/view/VelocityViewServlet.html). A typical application use-case for the VelocityViewServlet is to provide the view rendering layer for a servlet-based web application framework. The [VelocityStruts](struts.html) subproject uses the approach to bring Velocity templates to the Struts 1 application framework. @@ -101,7 +101,7 @@ You may have noticed that toolbox suppor The scope that you set for your toolbox will determine the lifecycle of the tools within it: -+ *application* scoped tools will be instantiated only once when first used by a template and then reused by all templates for each subsequent request. Due to this, it is *strongly* encouraged that your application scoped tools be completely threadsafe. The [MathTool](javadoc/org/apache/velocity/tools/generic/MathTool.html) (one of the [GenericTools](generic.html)) is a good example of tool meant to be application scoped. ++ *application* scoped tools will be instantiated only once when first used by a template and then reused by all templates for each subsequent request. Due to this, it is *strongly* encouraged that your application scoped tools be completely threadsafe. The [MathTool](apidocs/org/apache/velocity/tools/generic/MathTool.html) (one of the [GenericTools](generic.html)) is a good example of tool meant to be application scoped. + *session* scoped tools are instantiated at most once per unique session (if they are used by a template processed for that session) and are then reused for every request associated with that particular session. + *request* is the most common scope. Tools with this scope are instantiated at most once per servlet request fed to that VelocityView (if they are used by a template processed during that request). @@ -112,7 +112,7 @@ You can specify a restriction on the req <tool restrictTo="/catalog/*" class="com.mycompany.tools.CatalogTool"/> -You may have noticed that this example tool configuration doesn't have a "key" attribute. This is because VelocityTools 2 honors the [Key]Tool naming convention. So a tool with the simple name of "CatalogTool" will automatically be given the key "catalog" unless another key is specified in the tool configuration or using the [DefaultKey](javadoc/org/apache/velocity/tools/config/DefaultKey.html) annotation on the class. +You may have noticed that this example tool configuration doesn't have a "key" attribute. This is because VelocityTools 2 honors the [Key]Tool naming convention. So a tool with the simple name of "CatalogTool" will automatically be given the key "catalog" unless another key is specified in the tool configuration or using the [DefaultKey](apidocs/org/apache/velocity/tools/config/DefaultKey.html) annotation on the class. #### Tool Properties Modified: velocity/site/cms/trunk/content/tools/devel/view-tag.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/view-tag.mdtext?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/view-tag.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/view-tag.mdtext Tue May 17 10:44:17 2016 @@ -51,4 +51,4 @@ You can also store the results of any of #end </velocity:view> -For more details, see the [Javadoc](javadoc/org/apache/velocity/tools/view/jsp/VelocityViewTag.html) or the [TLD](http://svn.apache.org/repos/asf/velocity/tools/trunk/src/main/java/META-INF/velocity-view.tld). +For more details, see the [Javadoc](apidocs/org/apache/velocity/tools/view/jsp/VelocityViewTag.html) or the [TLD](http://svn.apache.org/repos/asf/velocity/tools/trunk/src/main/java/META-INF/velocity-view.tld). Modified: velocity/site/cms/trunk/content/tools/devel/view.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/view.mdtext?rev=1744249&r1=1744248&r2=1744249&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/view.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/view.mdtext Tue May 17 10:44:17 2016 @@ -22,11 +22,11 @@ The dependencies required for VelocityVi ## VelocityView Object -The [VelocityView](javadoc/org/apache/velocity/tools/view/VelocityView.html) object forms the core of the VelocityView infrastructure. In particular, it serves as the base class for the following: +The [VelocityView](apidocs/org/apache/velocity/tools/view/VelocityView.html) object forms the core of the VelocityView infrastructure. In particular, it serves as the base class for the following: ### [VelocityViewServlet](view-servlet.html) -The [VelocityViewServlet](javadoc/org/apache/velocity/tools/view/VelocityViewServlet.html) class is a standalone servlet that renders Velocity templates. It can be invoked directly from web client's requests, or via servlet forwarding similar to how JSP files are rendered by JSPServlet. +The [VelocityViewServlet](apidocs/org/apache/velocity/tools/view/VelocityViewServlet.html) class is a standalone servlet that renders Velocity templates. It can be invoked directly from web client's requests, or via servlet forwarding similar to how JSP files are rendered by JSPServlet. Detailed documentation is [here](view-servlet.html). @@ -51,14 +51,14 @@ Detailed documentation is [here](view-ta These are in addition to those provided by [GenericTools](generic.html#Tools): -+ [AbstractSearchTool](javadoc/org/apache/velocity/tools/view/AbstractSearchTool.html) - For doing "searching" and robust pagination of search results. Requires you to create a subclass. -+ [BrowserTool](javadoc/org/apache/velocity/tools/view/BrowserTool.html) - For identifying the browser and features thereof requesting the template. -+ [CookieTool](javadoc/org/apache/velocity/tools/view/CookieTool.html) - For convenient cookie access and creation. -+ [ImportTool](javadoc/org/apache/velocity/tools/view/ImportTool.html) - For pulling down textual content from a URL. -+ [LinkTool](javadoc/org/apache/velocity/tools/view/LinkTool.html) - For easy building of URLs (both relative or absolute). -+ [PagerTool](javadoc/org/apache/velocity/tools/view/PagerTool.html) - For doing request-based pagination of items in an arbitrary list. -+ [ParameterTool](javadoc/org/apache/velocity/tools/view/ParameterTool.html) - For easy retrieval and parsing of ServletRequest parameters. -+ [ViewContextTool](javadoc/org/apache/velocity/tools/view/ViewContextTool.html) - For convenient access to ViewContext data and meta-data. ++ [AbstractSearchTool](apidocs/org/apache/velocity/tools/view/AbstractSearchTool.html) - For doing "searching" and robust pagination of search results. Requires you to create a subclass. ++ [BrowserTool](apidocs/org/apache/velocity/tools/view/BrowserTool.html) - For identifying the browser and features thereof requesting the template. ++ [CookieTool](apidocs/org/apache/velocity/tools/view/CookieTool.html) - For convenient cookie access and creation. ++ [ImportTool](apidocs/org/apache/velocity/tools/view/ImportTool.html) - For pulling down textual content from a URL. ++ [LinkTool](apidocs/org/apache/velocity/tools/view/LinkTool.html) - For easy building of URLs (both relative or absolute). ++ [PagerTool](apidocs/org/apache/velocity/tools/view/PagerTool.html) - For doing request-based pagination of items in an arbitrary list. ++ [ParameterTool](apidocs/org/apache/velocity/tools/view/ParameterTool.html) - For easy retrieval and parsing of ServletRequest parameters. ++ [ViewContextTool](apidocs/org/apache/velocity/tools/view/ViewContextTool.html) - For convenient access to ViewContext data and meta-data. ## Examples
