Spring/spring-framework
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Remove Velocity support

Browse Source 
Issue: SPR-13795
This commit is contained in:
Juergen Hoeller
2016-07-04 23:30:58 +02:00
parent 4027bda168
commit ff6ead1fff
54 changed files with 135 additions and 4242 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/asciidoc/images/full.svg
View File

@@ -154,7 +154,7 @@
x="11.15" dy="1.2em" class="st8">data to the domain </tspan><tspan x="27.83" dy="1.2em" class="st8">model</tspan></text> </g>
<g id="shape13-48" v:mID="13" v:groupContext="shape" transform="translate(263.76,-211.679)">
<title>Box.13</title>
<desc>Integration with JSP, Velocity, XSLT, PDF, Excel</desc>
<desc>Integration with JSP, FreeMarker, XSLT, PDF, Excel</desc>
<v:userDefs>
<v:ud v:nameU="visVersion" v:val="VT0(11):26"/>
</v:userDefs>
@@ -166,7 +166,7 @@
</g>
<rect x="0" y="214.421" width="72" height="44.7771" class="st6"/>
<text x="8.49" y="231.41" class="st7" v:langID="1033"><v:paragraph v:horizAlign="1"/><v:tabList/>Integration with JSP, <tspan
x="7.83" dy="1.2em" class="st8">Velocity</tspan>, XSLT, PDF, <tspan x="28.66" dy="1.2em" class="st8">Excel</tspan></text> </g>
x="7.83" dy="1.2em" class="st8">FreeMarker</tspan>, XSLT, PDF, <tspan x="28.66" dy="1.2em" class="st8">Excel</tspan></text> </g>
<g id="shape15-55" v:mID="15" v:groupContext="shape" transform="translate(16.44,-112.319)">
<title>Box.15</title>
<desc>Spring Context</desc>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

2
src/asciidoc/images/overview-full.graffle
View File

@@ -128,7 +128,7 @@
{\colortbl;\red255\green255\blue255;}
\pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\qc\pardirnatural
\f0\i\b\fs28 \cf0 Integration with JSP, Velocity, SLT. PDF, Excel}</string>
\f0\i\b\fs28 \cf0 Integration with JSP, FreeMarker, XSLT, PDF, Excel}</string>
</dict>
</dict>
<dict>

6
src/asciidoc/images/spring-overview.svg
View File

@@ -160,7 +160,7 @@
x="-78.63" dy="1.2em" class="st4">WebWork<v:newlineChar/></tspan><tspan x="-76.14" dy="1.2em"
class="st4">Tapestry<v:newlineChar/></tspan><tspan x="-65.57" dy="1.2em" class="st4">JSF<v:newlineChar/></tspan><tspan
x="-97.82" dy="1.2em" class="st4">Rich View Support<v:newlineChar/></tspan><tspan x="-68.36" dy="1.2em"
class="st4">JSPs<v:newlineChar/></tspan><tspan x="-74.19" dy="1.2em" class="st4">Velocity<v:newlineChar/></tspan><tspan
class="st4">JSPs<v:newlineChar/></tspan><tspan x="-74.19" dy="1.2em" class="st4">FreeMarker<v:newlineChar/></tspan><tspan
x="-82.52" dy="1.2em" class="st4">FreeMarker<v:newlineChar/></tspan><tspan x="-66.69" dy="1.2em"
class="st4">PDF<v:newlineChar/></tspan><tspan x="-90.59" dy="1.2em" class="st4">Jasper Reports<v:newlineChar/></tspan><tspan
x="-68.91" dy="1.2em" class="st4">Excel<v:newlineChar/></tspan><tspan x="-99.48" dy="1.2em" class="st4">Spring Portlet MVC</tspan></text> </g>
@@ -190,9 +190,7 @@
<v:textRect cx="53.8583" cy="749.764" width="107.72" height="184.252"/>
<text x="-88.86" y="717.96" transform="scale(-1,1)" class="st3" v:langID="2057"><v:paragraph v:horizAlign="1"/><v:tabList/>ORM<v:newlineChar/><v:newlineChar/><tspan
x="-75.55" dy="2.76em" class="st4">Hibernate<v:newlineChar/></tspan><tspan x="-63.04" dy="1.2em"
class="st4">JPA<v:newlineChar/></tspan><tspan x="-71.65" dy="1.2em" class="st4">TopLink<v:newlineChar/></tspan><tspan
x="-63.87" dy="1.2em" class="st4">JDO<v:newlineChar/></tspan><tspan x="-63.59" dy="1.2em" class="st4">OJB<v:newlineChar/></tspan><tspan
x="-66.09" dy="1.2em" class="st4">iBatis</tspan></text> </g>
class="st4">JPA<v:newlineChar/></tspan></g>
</g>
</g>
</svg>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 11 KiB

123
src/asciidoc/integration.adoc
View File

@@ -6043,124 +6043,11 @@ of your emails using the above approach for a number of reasons.
recompiling, redeploying...
Typically the approach taken to address these issues is to use a template library such
as FreeMarker or Velocity to define the display structure of email content. This leaves
your code tasked only with creating the data that is to be rendered in the email
template and sending the email. It is definitely a best practice for when the content of
your emails becomes even moderately complex, and with the Spring Framework's support
classes for FreeMarker and Velocity becomes quite easy to do. Find below an example of
using the Velocity template library to create email content.
[[mail-templates-example]]
===== A Velocity-based example
To use http://velocity.apache.org[Velocity] to create your email template(s), you will
need to have the Velocity libraries available on your classpath. You will also need to
create one or more Velocity templates for the email content that your application needs.
Find below the Velocity template that this example will be using. As you can see it is
HTML-based, and since it is plain text it can be created using your favorite HTML or
text editor.
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
# in the com/foo/package
<html>
<body>
<h3>Hi ${user.userName}, welcome to the Chipping Sodbury On-the-Hill message boards!</h3>
<div>
Your email address is <a href="mailto:${user.emailAddress}">${user.emailAddress}</a>.
</div>
</body>
</html>
----
Find below some simple code and Spring XML configuration that makes use of the above
Velocity template to create email content and send email(s).
[source,java,indent=0]
[subs="verbatim,quotes"]
----
package com.foo;
import org.apache.velocity.app.VelocityEngine;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.mail.javamail.MimeMessageHelper;
import org.springframework.mail.javamail.MimeMessagePreparator;
import org.springframework.ui.velocity.VelocityEngineUtils;
import javax.mail.internet.MimeMessage;
import java.util.HashMap;
import java.util.Map;
public class SimpleRegistrationService implements RegistrationService {
private JavaMailSender mailSender;
private VelocityEngine velocityEngine;
public void setMailSender(JavaMailSender mailSender) {
this.mailSender = mailSender;
}
public void setVelocityEngine(VelocityEngine velocityEngine) {
this.velocityEngine = velocityEngine;
}
public void register(User user) {
// Do the registration logic...
sendConfirmationEmail(user);
}
private void sendConfirmationEmail(final User user) {
MimeMessagePreparator preparator = new MimeMessagePreparator() {
public void prepare(MimeMessage mimeMessage) throws Exception {
MimeMessageHelper message = new MimeMessageHelper(mimeMessage);
message.setTo(user.getEmailAddress());
message.setFrom("webmaster@csonth.gov.uk"); // could be parameterized...
Map model = new HashMap();
model.put("user", user);
String text = VelocityEngineUtils.mergeTemplateIntoString(
velocityEngine, "com/dns/registration-confirmation.vm", model);
message.setText(text, true);
}
};
this.mailSender.send(preparator);
}
}
----
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd">
<bean id="mailSender" class="org.springframework.mail.javamail.JavaMailSenderImpl">
<property name="host" value="mail.csonth.gov.uk"/>
</bean>
<bean id="registrationService" class="com.foo.SimpleRegistrationService">
<property name="mailSender" ref="mailSender"/>
<property name="velocityEngine" ref="velocityEngine"/>
</bean>
<bean id="velocityEngine" class="org.springframework.ui.velocity.VelocityEngineFactoryBean">
<property name="velocityProperties">
<value>
resource.loader=class
class.resource.loader.class=org.apache.velocity.runtime.resource.loader.ClasspathResourceLoader
</value>
</property>
</bean>
</beans>
----
as FreeMarker to define the display structure of email content. This leaves your code
tasked only with creating the data that is to be rendered in the email template and
sending the email. It is definitely a best practice for when the content of your emails
becomes even moderately complex, and with the Spring Framework's support classes for
FreeMarker becomes quite easy to do.

36
src/asciidoc/overview.adoc
View File

@@ -145,8 +145,7 @@ The Context module also supports Java EE features such as EJB, JMX, and basic re
The `ApplicationContext` interface is the focal point of the Context module.
`spring-context-support` provides support for integrating common third-party libraries
into a Spring application context for caching (EhCache, Guava, JCache), mailing
(JavaMail), scheduling (CommonJ, Quartz) and template engines (FreeMarker, JasperReports,
Velocity).
(JavaMail), scheduling (CommonJ, Quartz) and template engines (FreeMarker, JasperReports).
The `spring-expression` module provides a powerful <<expressions,__Expression
@@ -198,14 +197,13 @@ management for classes that implement special interfaces and for __all your POJO
Old Java Objects)__.
The `spring-orm` module provides integration layers for popular
<<orm-introduction,object-relational mapping>> APIs, including <<orm-jpa,JPA>>,
<<orm-jdo,JDO>>, and <<orm-hibernate,Hibernate>>. Using the `spring-orm` module you can
use all of these O/R-mapping frameworks in combination with all of the other features
Spring offers, such as the simple declarative transaction management feature mentioned
previously.
<<orm-introduction,object-relational mapping>> APIs, including <<orm-jpa,JPA>> and
<<orm-hibernate,Hibernate>>. Using the `spring-orm` module you can use these
O/R-mapping frameworks in combination with all of the other features Spring offers,
such as the simple declarative transaction management feature mentioned previously.
The `spring-oxm` module provides an abstraction layer that supports <<oxm,Object/XML
mapping>> implementations such as JAXB, Castor, XMLBeans, JiBX and XStream.
mapping>> implementations such as JAXB, Castor, JiBX and XStream.
The `spring-jms` module (<<jms,Java Messaging Service>>) contains features for producing and
consuming messages. Since Spring Framework 4.1, it provides integration with the
@@ -214,8 +212,8 @@ consuming messages. Since Spring Framework 4.1, it provides integration with the
[[overview-web]]
==== Web
The __Web__ layer consists of the `spring-web`, `spring-webmvc`, `spring-websocket`, and
`spring-webmvc-portlet` modules.
The __Web__ layer consists of the `spring-web`, `spring-webmvc` and `spring-websocket`
modules.
The `spring-web` module provides basic web-oriented integration features such as
multipart file upload functionality and the initialization of the IoC container using
@@ -228,10 +226,6 @@ for web applications. Spring's MVC framework provides a clean separation between
model code and web forms and integrates with all of the other features of the Spring
Framework.
The `spring-webmvc-portlet` module (also known as the __Web-Portlet__ module) provides
the MVC implementation to be used in a Portlet environment and mirrors the functionality
of the `spring-webmvc` module.
[[overview-testing]]
==== Test
@@ -259,11 +253,11 @@ the web application fully transactional, just as it would be if you used EJB
container-managed transactions. All your custom business logic can be implemented with
simple POJOs and managed by Spring's IoC container. Additional services include support
for sending email and validation that is independent of the web layer, which lets you
choose where to execute validation rules. Spring's ORM support is integrated with JPA,
Hibernate and JDO; for example, when using Hibernate, you can continue to use
your existing mapping files and standard Hibernate `SessionFactory` configuration. Form
controllers seamlessly integrate the web-layer with the domain model, removing the need
for `ActionForms` or other classes that transform HTTP parameters to values for your
choose where to execute validation rules. Spring's ORM support is integrated with JPA
and Hibernate; for example, when using Hibernate, you can continue to use your existing
mapping files and standard Hibernate `SessionFactory` configuration. Form controllers
seamlessly integrate the web-layer with the domain model, removing the need for
`ActionForms` or other classes that transform HTTP parameters to values for your
domain model.
.Spring middle-tier using a third-party web framework
@@ -416,10 +410,6 @@ modules, see <<overview-modules>>.
|spring-webmvc
|REST Web Services and model-view-controller implementation for web applications
|org.springframework
|spring-webmvc-portlet
|MVC implementation to be used in a Portlet environment
|org.springframework
|spring-websocket
|WebSocket and SockJS implementations, including STOMP support

16
src/asciidoc/testing.adoc
View File

@@ -84,12 +84,6 @@ conjunction with your `WebApplicationContext` configuration for Spring MVC, see
<<spring-mvc-test-framework,_Spring MVC Test Framework_>>.
[[mock-objects-portlet]]
==== Portlet API
The `org.springframework.mock.web.portlet` package contains a set of Portlet API mock
objects, targeted at usage with Spring's Portlet MVC framework.
[[unit-testing-support-classes]]
=== Unit Testing support Classes
@@ -4091,9 +4085,9 @@ expectations.
This means if you are using JSPs you can verify the JSP page to which the request was
forwarded, but there won't be any HTML rendered. In other words, the JSP will not be
_invoked_. Note however that all other rendering technologies which don't rely on
forwarding such as Thymeleaf, Freemarker, and Velocity will render HTML to the response
body as expected. The same is true for rendering JSON, XML, and other formats via
`@ResponseBody` methods.
forwarding such as Thymeleaf and Freemarker will render HTML to the response body as
expected. The same is true for rendering JSON, XML, and other formats via `@ResponseBody`
methods.
Alternatively you may consider the full end-to-end integration testing support from
Spring Boot via `@WebIntegrationTest`. See the
@@ -4149,8 +4143,8 @@ need to deploy to a Servlet container
[NOTE]
====
`MockMvc` works with templating technologies that do not rely on a Servlet Container (e.g.,
Thymeleaf, Freemarker, Velocity, etc.), but it does not work with JSPs since they rely on
the Servlet Container.
Thymeleaf, FreeMarker, etc.), but it does not work with JSPs since they rely on the Servlet
container.
====
[[spring-mvc-test-server-htmlunit-why]]

32
src/asciidoc/web-mvc.adoc
View File

@@ -49,9 +49,9 @@ configurable through file extension or Accept header content type negotiation, t
bean names, a properties file, or even a custom `ViewResolver` implementation. The model
(the M in MVC) is a `Map` interface, which allows for the complete abstraction of the
view technology. You can integrate directly with template based rendering technologies
such as JSP, Velocity and Freemarker, or directly generate XML, JSON, Atom, and many
other types of content. The model `Map` is simply transformed into an appropriate
format, such as JSP request attributes, a Velocity template model.
such as JSP and FreeMarker, or directly generate XML, JSON, Atom, and many other types
of content. The model `Map` is simply transformed into an appropriate format, such as
JSP request attributes or a FreeMarker template model.
@@ -101,7 +101,7 @@ Spring's web module includes many unique web support features:
* __Flexible model transfer__. Model transfer with a name/value `Map` supports easy
integration with any view technology.
* __Customizable locale, time zone and theme resolution, support for JSPs with or without
Spring tag library, support for JSTL, support for Velocity without the need for extra
Spring tag library, support for JSTL, support for FreeMarker without the need for extra
bridges, and so on.__
* __A simple yet powerful JSP tag library known as the Spring tag library that provides
support for features such as data binding and themes__. The custom tags allow for
@@ -2772,7 +2772,7 @@ directly on `RequestMappingHandlerAdapter`.
== Resolving views
All MVC frameworks for web applications provide a way to address views. Spring provides
view resolvers, which enable you to render models in a browser without tying you to a
specific view technology. Out of the box, Spring enables you to use JSPs, Velocity
specific view technology. Out of the box, Spring enables you to use JSPs, FreeMarker
templates and XSLT views, for example. See <<view>> for a discussion of how to integrate
and use a number of disparate view technologies.
@@ -2824,9 +2824,9 @@ examples follow.
specify the view class for all views generated by this resolver by using
`setViewClass(..)`. See the `UrlBasedViewResolver` javadocs for details.
| `VelocityViewResolver` / `FreeMarkerViewResolver`
| Convenient subclass of `UrlBasedViewResolver` that supports `VelocityView` (in effect,
Velocity templates) or `FreeMarkerView` ,respectively, and custom subclasses of them.
| `FreeMarkerViewResolver`
| Convenient subclass of `UrlBasedViewResolver` that supports `FreeMarkerView` and
custom subclasses of them.
| `ContentNegotiatingViewResolver`
| Implementation of the `ViewResolver` interface that resolves a view based on the
@@ -2876,7 +2876,7 @@ file "extend". This way you can specify a default view class, for example.
Subclasses of `AbstractCachingViewResolver` cache view instances that they resolve.
Caching improves performance of certain view technologies. It's possible to turn off the
cache by setting the `cache` property to `false`. Furthermore, if you must refresh a
certain view at runtime (for example when a Velocity template is modified), you can use
certain view at runtime (for example when a FreeMarker template is modified), you can use
the `removeFromCache(String viewName, Locale loc)` method.
====
@@ -2926,7 +2926,7 @@ indicate the view could not be found. Not all view resolvers do this, however, b
in some cases, the resolver simply cannot detect whether or not the view exists. For
example, the `InternalResourceViewResolver` uses the `RequestDispatcher` internally, and
dispatching is the only way to figure out if a JSP exists, but this action can only
execute once. The same holds for the `VelocityViewResolver` and some others. Check the
execute once. The same holds for the `FreeMarkerViewResolver` and some others. Check the
javadocs of the specific view resolver to see whether it reports non-existing views.
Thus, putting an `InternalResourceViewResolver` in the chain in a place other than
the last results in the chain not being fully inspected, because the
@@ -2942,7 +2942,7 @@ JSPs that are processed through the Servlet or JSP engine, this resolution is us
handled through the combination of `InternalResourceViewResolver` and
`InternalResourceView`, which issues an internal forward or include via the Servlet
API's `RequestDispatcher.forward(..)` method or `RequestDispatcher.include()` method.
For other view technologies, such as Velocity, XSLT, and so on, the view itself writes
For other view technologies, such as FreeMarker, XSLT, and so on, the view itself writes
the content directly to the response stream.
It is sometimes desirable to issue an HTTP redirect back to the client, before the view
@@ -5228,7 +5228,7 @@ And the same in XML:
</mvc:view-resolvers>
----
Note however that FreeMarker, Velocity, Tiles, Groovy Markup and script templates also require
Note however that FreeMarker, Tiles, Groovy Markup and script templates also require
configuration of the underlying view technology.
The MVC namespace provides dedicated elements. For example with FreeMarker:
@@ -5438,10 +5438,10 @@ XML example:
In order for the above to work the application must also
render URLs with versions. The easiest way to do that is to configure the
`ResourceUrlEncodingFilter` which wraps the response and overrides its `encodeURL` method.
This will work in JSPs, FreeMarker, Velocity, and any other view technology that calls
the response `encodeURL` method. Alternatively, an application can also inject and
use directly the `ResourceUrlProvider` bean, which is automatically declared with the MVC
Java config and the MVC namespace.
This will work in JSPs, FreeMarker, and any other view technology that calls the response
`encodeURL` method. Alternatively, an application can also inject and use directly the
`ResourceUrlProvider` bean, which is automatically declared with the MVC Java config and
the MVC namespace.
Webjars are also supported with `WebJarsResourceResolver`, which is automatically registered
when the `"org.webjars:webjars-locator"` library is on classpath. This resolver allows

224
src/asciidoc/web-view.adoc
View File

@@ -36,6 +36,7 @@ text based content.
This requires Groovy 2.3.1+ on the classpath.
[[view-groovymarkup-configuration]]
=== Configuration
@@ -76,6 +77,7 @@ The XML counterpart using the MVC namespace is:
<mvc:groovy-configurer resource-loader-path="/WEB-INF/"/>
----
[[view-groovymarkup-example]]
=== Example
@@ -98,57 +100,27 @@ Here is a sample template for an HTML page:
----
[[view-velocity]]
== Velocity & FreeMarker
http://velocity.apache.org[Velocity] and http://www.freemarker.org[FreeMarker] are two
templating languages that can be used as view technologies within Spring MVC
applications. The languages are quite similar and serve similar needs and so are
considered together in this section. For semantic and syntactic differences between the
two languages, see the http://www.freemarker.org[FreeMarker] web site.
[[view-freemarker]]
== FreeMarker
http://www.freemarker.org[FreeMarker] is a templating language that can be used as a
view technology within Spring MVC applications. For details on the template language,
see the http://www.freemarker.org[FreeMarker] web site.
[[view-velocity-dependencies]]
[[view-freemarker-dependencies]]
=== Dependencies
Your web application will need to include `velocity-1.x.x.jar` or `freemarker-2.x.jar`
in order to work with Velocity or FreeMarker respectively and `commons-collections.jar`
is required for Velocity. Typically they are included in the `WEB-INF/lib` folder where
they are guaranteed to be found by a Java EE server and added to the classpath for your
Your web application will need to include `freemarker-2.x.jar` in order to work with
FreeMarker. Typically this is included in the `WEB-INF/lib` folder where the jars are
guaranteed to be found by a Java EE server and added to the classpath for your
application. It is of course assumed that you already have the `spring-webmvc.jar` in
your `'WEB-INF/lib'` directory too! If you make use of Spring's 'dateToolAttribute' or
'numberToolAttribute' in your Velocity views, you will also need to include the
`velocity-tools-generic-1.x.jar`
your `'WEB-INF/lib'` directory too!
[[view-velocity-contextconfig]]
[[view-freemarker-contextconfig]]
=== Context configuration
A suitable configuration is initialized by adding the relevant configurer bean
definition to your `'{asterisk}-servlet.xml'` as shown below:
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
<!--
This bean sets up the Velocity environment for us based on a root path for templates.
Optionally, a properties file can be specified for more control over the Velocity
environment, but the defaults are pretty sane for file based template loading.
-->
<bean id="velocityConfig" class="org.springframework.web.servlet.view.velocity.VelocityConfigurer">
<property name="resourceLoaderPath" value="/WEB-INF/velocity/"/>
</bean>
<!--
View resolvers can also be configured with ResourceBundles or XML files. If you need
different view resolving based on Locale, you have to use the resource bundle resolver.
-->
<bean id="viewResolver" class="org.springframework.web.servlet.view.velocity.VelocityViewResolver">
<property name="cache" value="true"/>
<property name="prefix" value=""/>
<property name="suffix" value=".vm"/>
</bean>
----
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
@@ -170,76 +142,22 @@ definition to your `'{asterisk}-servlet.xml'` as shown below:
[NOTE]
====
For non web-apps add a `VelocityConfigurationFactoryBean` or a
`FreeMarkerConfigurationFactoryBean` to your application context definition file.
For non web-apps add a `FreeMarkerConfigurationFactoryBean` to your application context
definition file.
====
[[view-velocity-createtemplates]]
[[view-freemarker-createtemplates]]
=== Creating templates
Your templates need to be stored in the directory specified by the `{asterisk}Configurer` bean
shown above. This document does not cover details of creating templates for the two
languages - please see their relevant websites for information. If you use the view
resolvers highlighted, then the logical view names relate to the template file names in
similar fashion to `InternalResourceViewResolver` for JSP's. So if your controller
returns a ModelAndView object containing a view name of "welcome" then the resolvers
will look for the `/WEB-INF/freemarker/welcome.ftl` or `/WEB-INF/velocity/welcome.vm`
template as appropriate.
[[view-velocity-advancedconfig]]
=== Advanced configuration
The basic configurations highlighted above will be suitable for most application
requirements, however additional configuration options are available for when unusual or
advanced requirements dictate.
[[view-velocity-example-velocityproperties]]
==== velocity.properties
This file is completely optional, but if specified, contains the values that are passed
to the Velocity runtime in order to configure velocity itself. Only required for
advanced configurations, if you need this file, specify its location on the
`VelocityConfigurer` bean definition above.
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
<bean id="velocityConfig" class="org.springframework.web.servlet.view.velocity.VelocityConfigurer">
<property name="configLocation" value="/WEB-INF/velocity.properties"/>
</bean>
----
Alternatively, you can specify velocity properties directly in the bean definition for
the Velocity config bean by replacing the "configLocation" property with the following
inline properties.
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
<bean id="velocityConfig" class="org.springframework.web.servlet.view.velocity.VelocityConfigurer">
<property name="velocityProperties">
<props>
<prop key="resource.loader">file</prop>
<prop key="file.resource.loader.class">
org.apache.velocity.runtime.resource.loader.FileResourceLoader
</prop>
<prop key="file.resource.loader.path">${webapp.root}/WEB-INF/velocity</prop>
<prop key="file.resource.loader.cache">false</prop>
</props>
</property>
</bean>
----
Refer to the
{api-spring-framework}/ui/velocity/VelocityEngineFactory.html[API
documentation] for Spring configuration of Velocity, or the Velocity documentation for
examples and definitions of the `'velocity.properties'` file itself.
Your templates need to be stored in the directory specified by the `FreeMarkerConfigurer`
shown above. If you use the view resolvers highlighted, then the logical view names
relate to the template file names in similar fashion to `InternalResourceViewResolver`
for JSP's. So if your controller returns a ModelAndView object containing a view name of
"welcome" then the resolver will look for the `/WEB-INF/freemarker/welcome.ftl` template.
[[views-freemarker]]
==== FreeMarker
=== Advanced FreeMarker configuration
FreeMarker 'Settings' and 'SharedVariables' can be passed directly to the FreeMarker
`Configuration` object managed by Spring by setting the appropriate bean properties on
the `FreeMarkerConfigurer` bean. The `freemarkerSettings` property requires a
@@ -266,14 +184,13 @@ the `Configuration` object.
[[view-velocity-forms]]
[[view-freemarker-forms]]
=== Bind support and form handling
Spring provides a tag library for use in JSP's that contains (amongst other things) a
`<spring:bind/>` tag. This tag primarily enables forms to display values from form
backing objects and to show the results of failed validations from a `Validator` in the
web or business tier. From version 1.1, Spring now has support for the same
functionality in both Velocity and FreeMarker, with additional convenience macros for
generating form input elements themselves.
web or business tier. Spring also has support for the same functionality in FreeMarker,
with additional convenience macros for generating form input elements themselves.
[[view-bind-macros]]
@@ -285,9 +202,8 @@ Some of the macros defined in the Spring libraries are considered internal (priv
no such scoping exists in the macro definitions making all macros visible to calling
code and user templates. The following sections concentrate only on the macros you need
to be directly calling from within your templates. If you wish to view the macro code
directly, the files are called spring.vm / spring.ftl and are in the packages
`org.springframework.web.servlet.view.velocity` or
`org.springframework.web.servlet.view.freemarker` respectively.
directly, the file is called `spring.ftl` in the package
`org.springframework.web.servlet.view.freemarker`.
[[view-simple-binding]]
@@ -295,28 +211,7 @@ directly, the files are called spring.vm / spring.ftl and are in the packages
In your HTML forms (vm / ftl templates) which act as a form view for a Spring MVC
controller, you can use code similar to the following to bind to field values and
display error messages for each input field in similar fashion to the JSP equivalent.
Example code is shown below for the `personFormV`/`personFormF` views configured earlier:
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
<!-- velocity macros are automatically available -->
<html>
...
<form action="" method="POST">
Name:
#springBind("myModelObject.name")
<input type="text"
name="${status.expression}"
value="$!status.value"/><br>
#foreach($error in $status.errorMessages) <b>$error</b> <br> #end
<br>
...
<input type="submit" value="submit"/>
</form>
...
</html>
----
Example code is shown below for the `personForm` view configured earlier:
[source,xml,indent=0]
[subs="verbatim,quotes"]
@@ -341,18 +236,18 @@ Example code is shown below for the `personFormV`/`personFormF` views configured
</html>
----
`#springBind` / `<@spring.bind>` requires a 'path' argument which consists of the name
of your command object (it will be 'command' unless you changed it in your
FormController properties) followed by a period and the name of the field on the command
object you wish to bind to. Nested fields can be used too such as
"command.address.street". The `bind` macro assumes the default HTML escaping behavior
specified by the ServletContext parameter `defaultHtmlEscape` in web.xml
`<@spring.bind>` requires a 'path' argument which consists of the name of your command
object (it will be 'command' unless you changed it in your FormController properties)
followed by a period and the name of the field on the command object you wish to bind to.
Nested fields can be used too such as "command.address.street". The `bind` macro assumes
the default HTML escaping behavior specified by the ServletContext parameter
`defaultHtmlEscape` in `web.xml`.
The optional form of the macro called `#springBindEscaped` / `<@spring.bindEscaped>`
takes a second argument and explicitly specifies whether HTML escaping should be used in
the status error messages or values. Set to true or false as required. Additional form
handling macros simplify the use of HTML escaping and these macros should be used
wherever possible. They are explained in the next section.
The optional form of the macro called `<@spring.bindEscaped>` takes a second argument
and explicitly specifies whether HTML escaping should be used in the status error
messages or values. Set to true or false as required. Additional form handling macros
simplify the use of HTML escaping and these macros should be used wherever possible.
They are explained in the next section.
[[views-form-macros]]
@@ -369,62 +264,49 @@ parameter list that each takes.
.Table of macro definitions
[cols="3,1,1"]
|===
| macro| VTL definition| FTL definition
| macro| FTL definition
| **message** (output a string from a resource bundle based on the code parameter)
| #springMessage($code)
| <@spring.message code/>
| **messageText** (output a string from a resource bundle based on the code parameter,
falling back to the value of the default parameter)
| #springMessageText($code $text)
| <@spring.messageText code, text/>
| **url** (prefix a relative URL with the application's context root)
| #springUrl($relativeUrl)
| <@spring.url relativeUrl/>
| **formInput** (standard input field for gathering user input)
| #springFormInput($path $attributes)
| <@spring.formInput path, attributes, fieldType/>
| **formHiddenInput *** (hidden input field for submitting non-user input)
| #springFormHiddenInput($path $attributes)
| <@spring.formHiddenInput path, attributes/>
| **formPasswordInput** * (standard input field for gathering passwords. Note that no
value will ever be populated in fields of this type)
| #springFormPasswordInput($path $attributes)
| <@spring.formPasswordInput path, attributes/>
| **formTextarea** (large text field for gathering long, freeform text input)
| #springFormTextarea($path $attributes)
| <@spring.formTextarea path, attributes/>
| **formSingleSelect** (drop down box of options allowing a single required value to be
selected)
| #springFormSingleSelect( $path $options $attributes)
| <@spring.formSingleSelect path, options, attributes/>
| **formMultiSelect** (a list box of options allowing the user to select 0 or more values)
| #springFormMultiSelect($path $options $attributes)
| <@spring.formMultiSelect path, options, attributes/>
| **formRadioButtons** (a set of radio buttons allowing a single selection to be made
from the available choices)
| #springFormRadioButtons($path $options $separator $attributes)
| <@spring.formRadioButtons path, options separator, attributes/>
| **formCheckboxes** (a set of checkboxes allowing 0 or more values to be selected)
| #springFormCheckboxes($path $options $separator $attributes)
| <@spring.formCheckboxes path, options, separator, attributes/>
| **formCheckbox** (a single checkbox)
| #springFormCheckbox($path $attributes)
| <@spring.formCheckbox path, attributes/>
| **showErrors** (simplify display of validation errors for the bound field)
| #springShowErrors($separator $classOrStyle)
| <@spring.showErrors separator, classOrStyle/>
|===
@@ -460,16 +342,6 @@ differences exist between the two languages, they are explained in the notes.
[[views-form-macros-input]]
===== Input Fields
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
<!-- the Name field example from above using form macros in VTL -->
...
Name:
#springFormInput("command.name" "")<br>
#springShowErrors("<br>" "")<br>
----
The formInput macro takes the path parameter (command.name) and an additional attributes
parameter which is empty in the example above. The macro, along with all other form
generation macros, performs an implicit spring bind on the path parameter. The binding
@@ -479,8 +351,7 @@ path parameter again - it simply operates on whichever field a bind was last cre
The showErrors macro takes a separator parameter (the characters that will be used to
separate multiple errors on a given field) and also accepts a second parameter, this
time a class name or style attribute. Note that FreeMarker is able to specify default
values for the attributes parameter, unlike Velocity, and the two macro calls above
could be expressed as follows in FTL:
values for the attributes parameter.
[source,xml,indent=0]
[subs="verbatim,quotes"]
@@ -559,15 +430,15 @@ codes would be created with suitable keys like the example below.
[source,java,indent=0]
[subs="verbatim,quotes"]
----
protected Map referenceData(HttpServletRequest request) throws Exception {
Map cityMap = new LinkedHashMap();
protected Map<String, String> referenceData(HttpServletRequest request) throws Exception {
Map<String, String> cityMap = new LinkedHashMap<>();
cityMap.put("LDN", "London");
cityMap.put("PRS", "Paris");
cityMap.put("NYC", "New York");
Map m = new HashMap();
m.put("cityMap", cityMap);
return m;
Map<String, String> model = new HashMap<>();
model.put("cityMap", cityMap);
return model;
}
----
@@ -600,9 +471,6 @@ model/context variable named xhtmlCompliant:
[source,jsp,indent=0]
[subs="verbatim,quotes"]
----
## for Velocity..
#set($springXhtmlCompliant = true)
<#-- for FreeMarker -->
<#assign xhtmlCompliant = true in spring>
----