diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupConfigurer.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupConfigurer.java
index b85c92219f0..e8a39846836 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupConfigurer.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupConfigurer.java
@@ -79,7 +79,7 @@ import org.springframework.util.StringUtils;
* @author Rossen Stoyanchev
* @since 4.1
* @see GroovyMarkupView
- * @see
+ * @see
* Groovy Markup Template engine documentation
*/
public class GroovyMarkupConfigurer extends TemplateConfiguration
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupView.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupView.java
index cd8d1b74979..83fc3c4112b 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupView.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/view/groovy/GroovyMarkupView.java
@@ -45,7 +45,7 @@ import org.springframework.web.util.NestedServletException;
* @since 4.1
* @see GroovyMarkupViewResolver
* @see GroovyMarkupConfigurer
- * @see
+ * @see
* Groovy Markup Template engine documentation
*/
public class GroovyMarkupView extends AbstractTemplateView {
diff --git a/src/asciidoc/web-view.adoc b/src/asciidoc/web-view.adoc
index 7e5a01ecd31..522c40b9c92 100644
--- a/src/asciidoc/web-view.adoc
+++ b/src/asciidoc/web-view.adoc
@@ -5,213 +5,830 @@
[[view-introduction]]
== Introduction
One of the areas in which Spring excels is in the separation of view technologies from
-the rest of the MVC framework. For example, deciding to use Velocity or XSLT in place of
-an existing JSP is primarily a matter of configuration. This chapter covers the major
-view technologies that work with Spring and touches briefly on how to add new ones. This
-chapter assumes you are already familiar with <> which covers the
-basics of how views in general are coupled to the MVC framework.
+the rest of the MVC framework. For example, deciding to use Groovy Markup Templates
+or Thymeleaf in place of an existing JSP is primarily a matter of configuration.
+This chapter covers the major view technologies that work with Spring and touches
+briefly on how to add new ones. This chapter assumes you are already familiar with
+<> which covers the basics of how views in general are coupled
+to the MVC framework.
+[[view-thymeleaf]]
+== Thymeleaf
+http://www.thymeleaf.org/[Thymeleaf] is a good example of a view technology fitting
+perfectly in the MVC framework. Support for this integration is not provided by
+the Spring team but by the Thymeleaf team itself.
-[[view-jsp]]
-== JSP & JSTL
-Spring provides a couple of out-of-the-box solutions for JSP and JSTL views. Using JSP
-or JSTL is done using a normal view resolver defined in the `WebApplicationContext`.
-Furthermore, of course you need to write some JSPs that will actually render the view.
+Configuring Thymeleaf for Spring usually requires a few beans defined, like a
+`ServletContextTemplateResolver`, a `SpringTemplateEngine` and a `ThymeleafViewResolver`.
+Please refer to the http://www.thymeleaf.org/documentation.html[Thymeleaf+Spring]
+documentation section for more details.
-[NOTE]
-====
-Setting up your application to use JSTL is a common source of error, mainly caused by
-confusion over the different servlet spec., JSP and JSTL version numbers, what they mean
-and how to declare the taglibs correctly. The article
-http://www.mularien.com/blog/2008/04/24/how-to-reference-and-use-jstl-in-your-web-application/[How
-to Reference and Use JSTL in your Web Application] provides a useful guide to the common
-pitfalls and how to avoid them. Note that as of Spring 3.0, the minimum supported
-servlet version is 2.4 (JSP 2.0 and JSTL 1.1), which reduces the scope for confusion
-somewhat.
-====
+[[view-groovymarkup]]
+== Groovy Markup Templates
+The http://groovy-lang.org/templating.html#_the_markuptemplateengine[Groovy Markup Template Engine]
+is another view technology, supported by Spring. This template engine is a template engine primarily
+aimed at generating XML-like markup (XML, XHTML, HTML5, ...), but that can be used to generate any
+text based content.
-[[view-jsp-resolver]]
-=== View resolvers
-Just as with any other view technology you're integrating with Spring, for JSPs you'll
-need a view resolver that will resolve your views. The most commonly used view resolvers
-when developing with JSPs are the `InternalResourceViewResolver` and the
-`ResourceBundleViewResolver`. Both are declared in the `WebApplicationContext`:
+This requires Groovy 2.3.1+ on the the classpath.
-[source,xml,indent=0]
+[[view-groovymarkup-configuration]]
+=== Configuration
+
+Configuring the Groovy Markup Teplate Engine is quite easy:
+
+[source,java,indent=0]
[subs="verbatim,quotes"]
----
-
-
-
-
+ @Configuration
+ @EnableWebMvc
+ public class WebConfig extends WebMvcConfigurerAdapter {
- # And a sample properties file is uses (views.properties in WEB-INF/classes):
- welcome.(class)=org.springframework.web.servlet.view.JstlView
- welcome.url=/WEB-INF/jsp/welcome.jsp
+ @Override
+ public void configureViewResolvers(ViewResolverRegistry registry) {
+ registry.groovy();
+ }
- productList.(class)=org.springframework.web.servlet.view.JstlView
- productList.url=/WEB-INF/jsp/productlist.jsp
+ @Bean
+ public GroovyMarkupConfigurer groovyMarkupConfigurer() {
+ GroovyMarkupConfigurer configurer = new GroovyMarkupConfigurer();
+ configurer.setResourceLoaderPath("/WEB-INF/");
+ return configurer;
+ }
+ }
----
-As you can see, the `ResourceBundleViewResolver` needs a properties file defining the
-view names mapped to 1) a class and 2) a URL. With a `ResourceBundleViewResolver` you
-can mix different types of views using only one resolver.
+The XML counterpart using the MVC namespace is:
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
-
-
-
-
-
-----
-
-The `InternalResourceBundleViewResolver` can be configured for using JSPs as described
-above. As a best practice, we strongly encourage placing your JSP files in a directory
-under the `'WEB-INF'` directory, so there can be no direct access by clients.
+
+
+
+
+
+----
-[[view-jsp-jstl]]
-=== 'Plain-old' JSPs versus JSTL
-When using the Java Standard Tag Library you must use a special view class, the
-`JstlView`, as JSTL needs some preparation before things such as the I18N features will
-work.
+[[view-groovymarkup-example]]
+=== Example
+Unlike traditional template engines, this one relies on a DSL that uses the builder syntax.
+Here is a sample template for an HTML page:
+[source,groovy,indent=0]
+[subs="verbatim,quotes"]
+----
+ yieldUnescaped ''
+ html(lang:'en') {
+ head {
+ meta('http-equiv':'"Content-Type" content="text/html; charset=utf-8"')
+ title('My page')
+ }
+ body {
+ p('This is an example of HTML contents')
+ }
+ }
+----
-[[view-jsp-tags]]
-=== Additional tags facilitating development
-Spring provides data binding of request parameters to command objects as described in
-earlier chapters. To facilitate the development of JSP pages in combination with those
-data binding features, Spring provides a few tags that make things even easier. All
-Spring tags have__HTML escaping__ features to enable or disable escaping of characters.
-The tag library descriptor (TLD) is included in the `spring-webmvc.jar`. Further
-information about the individual tags can be found in the appendix entitled
-<>.
+[[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-jsp-formtaglib]]
-=== Using Spring's form tag library
-As of version 2.0, Spring provides a comprehensive set of data binding-aware tags for
-handling form elements when using JSP and Spring Web MVC. Each tag provides support for
-the set of attributes of its corresponding HTML tag counterpart, making the tags
-familiar and intuitive to use. The tag-generated HTML is HTML 4.01/XHTML 1.0 compliant.
+[[view-velocity-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
+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`
-Unlike other form/input tag libraries, Spring's form tag library is integrated with
-Spring Web MVC, giving the tags access to the command object and reference data your
-controller deals with. As you will see in the following examples, the form tags make
-JSPs easier to develop, read and maintain.
-Let's go through the form tags and look at an example of how each tag is used. We have
-included generated HTML snippets where certain tags require further commentary.
+[[view-velocity-contextconfig]]
+=== Context configuration
+A suitable configuration is initialized by adding the relevant configurer bean
+definition to your `'{asterisk}-servlet.xml'` as shown below:
-[[view-jsp-formtaglib-configuration]]
-==== Configuration
-The form tag library comes bundled in `spring-webmvc.jar`. The library descriptor is
-called `spring-form.tld`.
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+
+
+
+
-To use the tags from this library, add the following directive to the top of your JSP
-page:
+
+
+
+
+
+
+----
[source,xml,indent=0]
[subs="verbatim,quotes"]
----
- <%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %>
+
+
+
+
+
+
+
+
+
+
+
----
-where `form` is the tag name prefix you want to use for the tags from this library.
+[NOTE]
+====
+For non web-apps add a `VelocityConfigurationFactoryBean` or a
+`FreeMarkerConfigurationFactoryBean` to your application context definition file.
+====
-[[view-jsp-formtaglib-formtag]]
-==== The form tag
-This tag renders an HTML 'form' tag and exposes a binding path to inner tags for
-binding. It puts the command object in the `PageContext` so that the command object can
-be accessed by inner tags. __All the other tags in this library are nested tags of the
-`form` tag__.
+[[view-velocity-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.
-Let's assume we have a domain object called `User`. It is a JavaBean with properties
-such as `firstName` and `lastName`. We will use it as the form backing object of our
-form controller which returns `form.jsp`. Below is an example of what `form.jsp` would
-look like:
-[source,xml,indent=0]
-[subs="verbatim,quotes"]
-----
-
-
-
-
First Name:
-
-
-
-
Last Name:
-
-
-
-
-
-
-
-
-
-----
-The `firstName` and `lastName` values are retrieved from the command object placed in
-the `PageContext` by the page controller. Keep reading to see more complex examples of
-how inner tags are used with the `form` tag.
+[[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.
-The generated HTML looks like a standard form:
+
+[[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"]
----
-
+
+
+
----
-The preceding JSP assumes that the variable name of the form backing object is
-`'command'`. If you have put the form backing object into the model under another name
-(definitely a best practice), then you can bind the form to the named variable like so:
+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"]
----
-
-
-
-
First Name:
-
-
-
-
Last Name:
-
-
-
+
+
+
+ file
+
+ org.apache.velocity.runtime.resource.loader.FileResourceLoader
+
+ ${webapp.root}/WEB-INF/velocity
+ false
+
+
+
+----
+
+Refer to the
+{javadoc-baseurl}/org/springframework/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.
+
+
+[[views-freemarker]]
+==== FreeMarker
+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
+`java.util.Properties` object and the `freemarkerVariables` property requires a
+`java.util.Map`.
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+
+
+
+
+
+
+
+
+----
+
+See the FreeMarker documentation for details of settings and variables as they apply to
+the `Configuration` object.
+
+
+
+[[view-velocity-forms]]
+=== Bind support and form handling
+Spring provides a tag library for use in JSP's that contains (amongst other things) a
+`` 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.
+
+
+[[view-bind-macros]]
+==== The bind macros
+A standard set of macros are maintained within the `spring-webmvc.jar` file for both
+languages, so they are always available to a suitably configured application.
+
+Some of the macros defined in the Spring libraries are considered internal (private) but
+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.
+
+
+[[view-simple-binding]]
+==== Simple binding
+In your html forms (vm / ftl templates) that act as the 'formView' for a Spring form
+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.
+Note that the name of the command object is "command" by default, but can be overridden
+in your MVC configuration by setting the 'commandName' bean property on your form
+controller. Example code is shown below for the `personFormV` and `personFormF` views
+configured earlier;
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+
+
+ ...
+
+ ...
+
+----
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+
+ <#import "/spring.ftl" as spring />
+
+ ...
+
+ ...
+
+----
+
+`#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
+
+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.
+
+
+[[views-form-macros]]
+==== Form input generation macros
+Additional convenience macros for both languages simplify both binding and form
+generation (including validation error display). It is never necessary to use these
+macros to generate form input fields, and they can be mixed and matched with simple HTML
+or calls direct to the spring bind macros highlighted previously.
+
+The following table of available macros show the VTL and FTL definitions and the
+parameter list that each takes.
+
+[[views-macros-defs-tbl]]
+.Table of macro definitions
+[cols="3,1,1"]
+|===
+| macro| VTL definition| 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/>
+|===
+
+* In FTL (FreeMarker), these two macros are not actually required as you can use the
+ normal `formInput` macro, specifying ' `hidden`' or ' `password`' as the value for the
+ `fieldType` parameter.
+
+The parameters to any of the above macros have consistent meanings:
+
+* path: the name of the field to bind to (ie "command.name")
+* options: a Map of all the available values that can be selected from in the input
+ field. The keys to the map represent the values that will be POSTed back from the form
+ and bound to the command object. Map objects stored against the keys are the labels
+ displayed on the form to the user and may be different from the corresponding values
+ posted back by the form. Usually such a map is supplied as reference data by the
+ controller. Any Map implementation can be used depending on required behavior. For
+ strictly sorted maps, a `SortedMap` such as a `TreeMap` with a suitable Comparator may
+ be used and for arbitrary Maps that should return values in insertion order, use a
+ `LinkedHashMap` or a `LinkedMap` from commons-collections.
+* separator: where multiple options are available as discreet elements (radio buttons or
+ checkboxes), the sequence of characters used to separate each one in the list (ie
+ " ").
+* attributes: an additional string of arbitrary tags or text to be included within the
+ HTML tag itself. This string is echoed literally by the macro. For example, in a
+ textarea field you may supply attributes as 'rows="5" cols="60"' or you could pass
+ style information such as 'style="border:1px solid silver"'.
+* classOrStyle: for the showErrors macro, the name of the CSS class that the span tag
+ wrapping each error will use. If no information is supplied (or the value is empty)
+ then the errors will be wrapped in tags.
+
+Examples of the macros are outlined below some in FTL and some in VTL. Where usage
+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"]
+----
+
+ ...
+ Name:
+ #springFormInput("command.name" "")
+ #springShowErrors(" " "")
+----
+
+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
+remains valid until a new bind occurs so the showErrors macro doesn't need to pass the
+path parameter again - it simply operates on whichever field a bind was last created for.
+
+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:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+ <@spring.formInput "command.name"/>
+ <@spring.showErrors " "/>
+----
+
+Output is shown below of the form fragment generating the name field, and displaying a
+validation error after the form was submitted with no value in the field. Validation
+occurs through Spring's Validation framework.
+
+The generated HTML looks like this:
+
+[source,jsp,indent=0]
+[subs="verbatim,quotes"]
+----
+ Name:
+
+
+ required
+
+
+----
+
+The formTextarea macro works the same way as the formInput macro and accepts the same
+parameter list. Commonly, the second parameter (attributes) will be used to pass style
+information or rows and cols attributes for the textarea.
+
+[[views-form-macros-select]]
+===== Selection Fields
+Four selection field macros can be used to generate common UI value selection inputs in
+your HTML forms.
+
+* formSingleSelect
+* formMultiSelect
+* formRadioButtons
+* formCheckboxes
+
+Each of the four macros accepts a Map of options containing the value for the form
+field, and the label corresponding to that value. The value and the label can be the
+same.
+
+An example of radio buttons in FTL is below. The form backing object specifies a default
+value of 'London' for this field and so no validation is necessary. When the form is
+rendered, the entire list of cities to choose from is supplied as reference data in the
+model under the name 'cityMap'.
+
+[source,jsp,indent=0]
+[subs="verbatim,quotes"]
+----
+ ...
+ Town:
+ <@spring.formRadioButtons "command.address.town", cityMap, "" />
+----
+
+This renders a line of radio buttons, one for each value in `cityMap` using the
+separator "". No additional attributes are supplied (the last parameter to the macro is
+missing). The cityMap uses the same String for each key-value pair in the map. The map's
+keys are what the form actually submits as POSTed request parameters, map values are the
+labels that the user sees. In the example above, given a list of three well known cities
+and a default value in the form backing object, the HTML would be
+
+[source,jsp,indent=0]
+[subs="verbatim,quotes"]
+----
+ Town:
+ London
+ Paris
+ New York
+----
+
+If your application expects to handle cities by internal codes for example, the map of
+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();
+ cityMap.put("LDN", "London");
+ cityMap.put("PRS", "Paris");
+ cityMap.put("NYC", "New York");
+
+ Map m = new HashMap();
+ m.put("cityMap", cityMap);
+ return m;
+ }
+----
+
+The code would now produce output where the radio values are the relevant codes but the
+user still sees the more user friendly city names.
+
+[source,jsp,indent=0]
+[subs="verbatim,quotes"]
+----
+ Town:
+ London
+ Paris
+ New York
+----
+
+
+[[views-form-macros-html-escaping]]
+==== HTML escaping and XHTML compliance
+Default usage of the form macros above will result in HTML tags that are HTML 4.01
+compliant and that use the default value for HTML escaping defined in your web.xml as
+used by Spring's bind support. In order to make the tags XHTML compliant or to override
+the default HTML escaping value, you can specify two variables in your template (or in
+your model where they will be visible to your templates). The advantage of specifying
+them in the templates is that they can be changed to different values later in the
+template processing to provide different behavior for different fields in your form.
+
+To switch to XHTML compliance for your tags, specify a value of 'true' for a
+model/context variable named xhtmlCompliant:
+
+[source,jsp,indent=0]
+[subs="verbatim,quotes"]
+----
+ ## for Velocity..
+ #set($springXhtmlCompliant = true)
+
+ <#-- for FreeMarker -->
+ <#assign xhtmlCompliant = true in spring>
+----
+
+Any tags generated by the Spring macros will now be XHTML compliant after processing
+this directive.
+
+In similar fashion, HTML escaping can be specified per field:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+ <#-- until this point, default HTML escaping is used -->
+
+ <#assign htmlEscape = true in spring>
+ <#-- next field will use HTML escaping -->
+ <@spring.formInput "command.name" />
+
+ <#assign htmlEscape = false in spring>
+ <#-- all future fields will be bound with HTML escaping off -->
+----
+
+
+
+
+[[view-jsp]]
+== JSP & JSTL
+Spring provides a couple of out-of-the-box solutions for JSP and JSTL views. Using JSP
+or JSTL is done using a normal view resolver defined in the `WebApplicationContext`.
+Furthermore, of course you need to write some JSPs that will actually render the view.
+
+[NOTE]
+====
+Setting up your application to use JSTL is a common source of error, mainly caused by
+confusion over the different servlet spec., JSP and JSTL version numbers, what they mean
+and how to declare the taglibs correctly. The article
+http://www.mularien.com/blog/2008/04/24/how-to-reference-and-use-jstl-in-your-web-application/[How
+to Reference and Use JSTL in your Web Application] provides a useful guide to the common
+pitfalls and how to avoid them. Note that as of Spring 3.0, the minimum supported
+servlet version is 2.4 (JSP 2.0 and JSTL 1.1), which reduces the scope for confusion
+somewhat.
+====
+
+
+
+[[view-jsp-resolver]]
+=== View resolvers
+Just as with any other view technology you're integrating with Spring, for JSPs you'll
+need a view resolver that will resolve your views. The most commonly used view resolvers
+when developing with JSPs are the `InternalResourceViewResolver` and the
+`ResourceBundleViewResolver`. Both are declared in the `WebApplicationContext`:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+
+
+
+
+
+ # And a sample properties file is uses (views.properties in WEB-INF/classes):
+ welcome.(class)=org.springframework.web.servlet.view.JstlView
+ welcome.url=/WEB-INF/jsp/welcome.jsp
+
+ productList.(class)=org.springframework.web.servlet.view.JstlView
+ productList.url=/WEB-INF/jsp/productlist.jsp
+----
+
+As you can see, the `ResourceBundleViewResolver` needs a properties file defining the
+view names mapped to 1) a class and 2) a URL. With a `ResourceBundleViewResolver` you
+can mix different types of views using only one resolver.
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+
+
+
+
+
+----
+
+The `InternalResourceBundleViewResolver` can be configured for using JSPs as described
+above. As a best practice, we strongly encourage placing your JSP files in a directory
+under the `'WEB-INF'` directory, so there can be no direct access by clients.
+
+
+
+[[view-jsp-jstl]]
+=== 'Plain-old' JSPs versus JSTL
+When using the Java Standard Tag Library you must use a special view class, the
+`JstlView`, as JSTL needs some preparation before things such as the I18N features will
+work.
+
+
+
+[[view-jsp-tags]]
+=== Additional tags facilitating development
+Spring provides data binding of request parameters to command objects as described in
+earlier chapters. To facilitate the development of JSP pages in combination with those
+data binding features, Spring provides a few tags that make things even easier. All
+Spring tags have__HTML escaping__ features to enable or disable escaping of characters.
+
+The tag library descriptor (TLD) is included in the `spring-webmvc.jar`. Further
+information about the individual tags can be found in the appendix entitled
+<>.
+
+
+
+[[view-jsp-formtaglib]]
+=== Using Spring's form tag library
+As of version 2.0, Spring provides a comprehensive set of data binding-aware tags for
+handling form elements when using JSP and Spring Web MVC. Each tag provides support for
+the set of attributes of its corresponding HTML tag counterpart, making the tags
+familiar and intuitive to use. The tag-generated HTML is HTML 4.01/XHTML 1.0 compliant.
+
+Unlike other form/input tag libraries, Spring's form tag library is integrated with
+Spring Web MVC, giving the tags access to the command object and reference data your
+controller deals with. As you will see in the following examples, the form tags make
+JSPs easier to develop, read and maintain.
+
+Let's go through the form tags and look at an example of how each tag is used. We have
+included generated HTML snippets where certain tags require further commentary.
+
+
+[[view-jsp-formtaglib-configuration]]
+==== Configuration
+The form tag library comes bundled in `spring-webmvc.jar`. The library descriptor is
+called `spring-form.tld`.
+
+To use the tags from this library, add the following directive to the top of your JSP
+page:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+ <%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %>
+----
+
+where `form` is the tag name prefix you want to use for the tags from this library.
+
+
+[[view-jsp-formtaglib-formtag]]
+==== The form tag
+
+This tag renders an HTML 'form' tag and exposes a binding path to inner tags for
+binding. It puts the command object in the `PageContext` so that the command object can
+be accessed by inner tags. __All the other tags in this library are nested tags of the
+`form` tag__.
+
+Let's assume we have a domain object called `User`. It is a JavaBean with properties
+such as `firstName` and `lastName`. We will use it as the form backing object of our
+form controller which returns `form.jsp`. Below is an example of what `form.jsp` would
+look like:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+
+
+
+
First Name:
+
+
+
+
Last Name:
+
+
+
+
+
+
+
+
+
+----
+
+The `firstName` and `lastName` values are retrieved from the command object placed in
+the `PageContext` by the page controller. Keep reading to see more complex examples of
+how inner tags are used with the `form` tag.
+
+The generated HTML looks like a standard form:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+
+----
+
+The preceding JSP assumes that the variable name of the form backing object is
+`'command'`. If you have put the form backing object into the model under another name
+(definitely a best practice), then you can bind the form to the named variable like so:
+
+[source,xml,indent=0]
+[subs="verbatim,quotes"]
+----
+
+
+
+
First Name:
+
+
+
+
Last Name:
+
+
+
@@ -743,819 +1360,484 @@ field-specific errors next to the fields:
-
-
-
-
-----
-
-The HTML would look like:
-
-[source,xml,indent=0]
-[subs="verbatim,quotes"]
-----
-