Author: cbrisson
Date: Mon Oct 1 10:14:06 2018
New Revision: 1842455
URL: http://svn.apache.org/viewvc?rev=1842455&view=rev
Log:
[site/tools] Fix links
Modified:
velocity/site/cms/trunk/content/tools/devel/frameworks.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=1842455&r1=1842454&r2=1842455&view=diff
==============================================================================
--- velocity/site/cms/trunk/content/tools/devel/frameworks.mdtext (original)
+++ velocity/site/cms/trunk/content/tools/devel/frameworks.mdtext Mon Oct 1
10:14:06 2018
@@ -6,7 +6,9 @@ Title: Apache Velocity Tools - Framework
## Overview
-VelocityTools is not meant to be a framework in itself, but rather should
ideally be integrated with other frameworks for applications of much size. The
simplest means of integration is to have your framework handle requests,
placing contextual data into the request, session or servlet context attributes
where templates and/or tools can find them, then forward those requests to a
VelocityViewServlet or VelocityLayoutServlet, letting those servlets manage
your VelocityView support for you and render your templates into the response.
If, however, your framework is one like Spring MVC and you either cannot or do
not wish to forward requests to one of the provided servlets, then the
instructions, tips and code below should make it easy for you to integrate
VelocityTools support into your framework of choice.
+This section covers the integration of the Velocity Tools in a J2EE
environment.
+
+Although VelocityTools can be used without any specific framework, it is
rather meant to be integrated with other frameworks for applications of much
size. The simplest means of integration is to have your framework handle
requests, placing contextual data into the request, session or servlet context
attributes where templates and/or tools can find them, then forward those
requests to a VelocityViewServlet or VelocityLayoutServlet, letting those
servlets manage your VelocityView support for you and render your templates
into the response. If, however, your framework is one like Spring MVC and you
either cannot or do not wish to forward requests to one of the provided
servlets, then the instructions, tips and code below should make it easy for
you to integrate VelocityTools support into your framework of choice.
## Integration Via VelocityView
@@ -14,29 +16,28 @@ VelocityTools is not meant to be a frame
[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**
-: 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**
-: 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.properties** = `/WEB-INF/velocity.properties`
+: Path and name of the Velocity engine configuration file. The path must be
relative to the web application root directory. First and foremost, the engine
configuration is initialized with default settings found in the classpath at
`org.apache.velocity.tools.view.velocity.properties`. If this parameter is not
present, Velocity will check for a properties file at
`/WEB-INF/velocity.properties`.
-**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`** = `/WEB-INF/tools.xml`
+: Path and name of the tools 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.tools.loadDefaults**
+**`org.apache.velocity.tools.loadDefaults`** = `true` | **`false`**
: 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`** = `true` | **`false`**
: 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`** = **`true`** | `false`
: 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).
+**`org.apache.velocity.tools.shared.config`** = **`true`** | `false`
+: At each servlet or filter initialization, if this parameter is false, then
the servlet/filter will own its own VelocityView instance. True by default.
+
+**`org.apache.velocity.tools.view.class`** =
`org.apache.velocity.tools.view.VelocityView`
+: Allows to specify a custom class inheriting from VelocityView as the View
class.
+
+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.
### Retrieving and Sharing
@@ -46,8 +47,33 @@ If you are using VelocityViewServlet, Ve
### Using
-This is unfinished. [You can help fix that!](index.html#Contribution) - TODO:
discuss basic functions, config options, etc
-{.note}
+The most basic environment is to bind the VelocityViewServlet to the extension
which pleases you (`*.vhtml`, `*.vm`, etc) in your `/WEB-INF/web.xml` file:
+
+ <?xml version="1.0" encoding="UTF-8" ?>
+ <web-app
+ xmlns="http://java.sun.com/xml/ns/javaee";
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
+ xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd";
+ metadata-complete="false"
+ version="3.0">
+ <servlet>
+ <servlet-name>view</servlet-name>
+ <servlet-class>servlet.ViewServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
+ <servlet-mapping>
+ <servlet-name>view</servlet-name>
+ <url-pattern>*.vhtml</url-pattern>
+ </servlet-mapping>
+ </web-app>
+
+Then, you would of course add some tools, either by providing a
`/WEB-INF/tools.xml` file or by enabling default tools (by means of the
`org.apache.velocity.tools.loadDefaults` configuration parameter described
above), or both. In the later case, your custom tools configuration will
overwrite the default ones.
+
+You can easily use a custom subclass of the
[VelocityViewServlet](apidocs/org/apache/velocity/tools/view/VelocityViewServlet.html)
and override its methods, amongs which but not limited to:
`createContext(request, response)`, `fillContext(context, request)`,
`getTempate(request, response)`, `setContentType()`.
+
+You can also override the
[VelocityView](apidocs/org/apache/velocity/tools/view/VelocityViewServlet.html)
class, which gives a wider range of subclassing options. You can do so by
providing a custom VelocityView class name tp the
`org.apache.velocity.tools.view.class` init (at the servlet/filter level) or
config (at the webapp level) parameter, see above.
+
+Be sure to check the tools integration mechanism described in the [creating
tools](creating-tools.html) section to see how the configuration, your custom
view and your custom tools do interact.
## Other Ways to Integrate VelocityTools
@@ -57,6 +83,6 @@ This is unfinished. [You can help fix th
### Standalone Use
-The so-called "standalone" methods of tool use developed from a desire to <a
href="standalone.html#Just_Use_Them!">use tools directly</a>, particularly the
GenericTools which had no servlet dependencies. However, now many VelocityView
tools can also be used "standalone" with varying degrees of effort and no need
to create any VelocityView instances. Most of the time, you just treat them
like any other POJO--create an instance, provide any need values/objects and
use it.
+The so-called "standalone" methods of tool use developed from a desire to [use
tools directly](standalone.html#Just_Use_Them), particularly the GenericTools
which had no servlet dependencies. However, now many VelocityView tools can
also be used "standalone" with varying degrees of effort and no need to create
any VelocityView instances. Most of the time, you just treat them like any
other POJO--create an instance, provide any need values/objects and use it.
If you want a little more help with things, consider using a
[ToolManager](standalone.html#ToolManager).
