Author: cbrisson Date: Thu Jun 21 00:07:30 2018 New Revision: 1833961 URL: http://svn.apache.org/viewvc?rev=1833961&view=rev Log: [site] Document recent changes
Modified: velocity/site/cms/trunk/content/tools/devel/frameworks.mdtext velocity/site/cms/trunk/content/tools/devel/upgrading.mdtext velocity/site/cms/trunk/content/tools/devel/view-servlet.mdtext Modified: velocity/site/cms/trunk/content/tools/devel/frameworks.mdtext URL: http://svn.apache.org/viewvc/velocity/site/cms/trunk/content/tools/devel/frameworks.mdtext?rev=1833961&r1=1833960&r2=1833961&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/frameworks.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/frameworks.mdtext Thu Jun 21 00:07:30 2018 @@ -12,28 +12,28 @@ VelocityTools is not meant to be a frame ### Configuring -[VelocityView](apidocs/org/apache/velocity/tools/view/VelocityView.html) supports the following configuration parameters as <init-param>s in web.xml: +[VelocityView](apidocs/org/apache/velocity/tools/view/VelocityView.html) supports the following configuration parameters as application <context-param>s or as specific servlet <init-param>s in web.xml: -org.apache.velocity.toolbox +**org.apache.velocity.toolbox** : Path and name of the toolbox configuration file. The path must be relative to the web application root directory. If this parameter is not found, the servlet will check for a toolbox file at `/WEB-INF/tools.xml`. -org.apache.velocity.properties +**org.apache.velocity.properties** : Path and name of the Velocity configuration file. The path must be relative to the web application root directory. If this parameter is not present, Velocity will check for a properties file at `/WEB-INF/velocity.properties`. If no file is found there, then Velocity is initialized with the settings in the classpath at `org.apache.velocity.tools.view.velocity.properties`. -org.apache.velocity.tools.deprecationSupportMode +**org.apache.velocity.tools.deprecationSupportMode** : Tells VelocityView whether or not it should : + support old tools that rely on init(Object) methods, : + look for and translate old toolbox.xml configurations, and : + use the deprecated ChainedContext class instead of ViewToolContext. : By default, this is true, so turn it to false if you want to fully upgrade to the new systems. Also, specific tools may look for and respect the deprecationSupportMode setting (e.g. ValueParser, ResourceTool) to provide old behavior where it has otherwise changed. -org.apache.velocity.tools.loadDefaults -: Tells VelocityView whether or not it should include the default tools.xml configurations provided in the VelocityTools jar(s). This is true by default. +**org.apache.velocity.tools.loadDefaults** +: Tells VelocityView whether or not it should include the default tools.xml configurations provided in the VelocityTools jar(s). This was true by default in 2.0, it's now false by default. -org.apache.velocity.tools.cleanConfiguration +**org.apache.velocity.tools.cleanConfiguration** : Tells VelocityView to test all the tool configurations and remove any invalid ones, rather than allow them to throw errors. This is false by default. -org.apache.velocity.tools.userCanOverwriteTools +**org.apache.velocity.tools.userCanOverwriteTools** : Tells VelocityView to construct the context in such a way that any user-set variables with the same keys as any of the configured tools are given primacy when resolving references. This is true by default, unlike in Tools 1.x. The VelocityView instance is typically the heart of any VelocityTools-using application. It encapsulates all necessary VelocityEngine and ToolboxFactory configuration and provides a simple API for processing templates or other VTL (e.g. VelocityViewTag body content). 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=1833961&r1=1833960&r2=1833961&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/upgrading.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/upgrading.mdtext Thu Jun 21 00:07:30 2018 @@ -14,6 +14,20 @@ Support for the Struts 1.x tools has bee For custom objects refering directly to the Velocity Engine API, please refer to the [Velocity Engine 2.0 Upgrading section](http://velocity.apache.org/engine/2.0/upgrading.html). +Default tools aren't loaded anymore in velocity-tools-view. To load them, you must enable default loading from your `WEB-INF/web.xml` file: + + <context-param> + <param-name>org.apache.velocity.tools.loadDefaults</param-name> + <param-value>true</param-value> + </context-param> + +or do the same for a specific servlet inside its `<servlet>` tag: + + <init-param> + <param-name>org.apache.velocity.tools.loadDefaults</param-name> + <param-value>true</param-value> + </init-param> + ## Upgrading to 2.0 VelocityTools 2.0 marks the most significant set of upgrades and changes ever done for the VelocityTools library. In order to provide flexible configurations, lazy-loading for tools, and a host of other improvements, almost all of the tool management and configuration code from Tools 1.x has been deprecated and replaced by completely different APIs. Thankfully, we were able to continue supporting old toolbox.xml configuration files and old tool design patterns, though these too have been deprecated and are unable to take full advantage of many of the new features. 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=1833961&r1=1833960&r2=1833961&view=diff ============================================================================== --- velocity/site/cms/trunk/content/tools/devel/view-servlet.mdtext (original) +++ velocity/site/cms/trunk/content/tools/devel/view-servlet.mdtext Thu Jun 21 00:07:30 2018 @@ -52,6 +52,19 @@ The servlet configuration (**web.xml**) <url-pattern>*.vm</url-pattern> </servlet-mapping> +Please note that the `org.apache.velocity.toolbox` and `org.apache.velocity.properties` parameters can also be set as `<context-params>` at the application level as follow: + + <context-param> + <param-name>org.apache.velocity.toolbox</param-name> + <param-value>/WEB-INF/tools.xml</param-value> + </context-param> + + <context-param> + <param-name>org.apache.velocity.properties</param-name> + <param-value>/WEB-INF/velocity.properties</param-value> + </context-param> + + ### Velocity Configuration Velocity configuration is **optional**, and for most applications the defaults will work fine. The **velocity.properties** file contains settings that affect logging, encoding, and macro settings.