<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id="view"

xmlns="http://docbook.org/ns/docbook" version="5.0"

xmlns:xl="http://www.w3.org/1999/xlink"

xmlns:xi="http://www.w3.org/2001/XInclude"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="

http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd">

<title>View technologies</title>

<section xml:id="view-introduction">

<title>Introduction</title>

<para>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 <xref linkend="mvc-viewresolver" />

which covers the basics of how views in general are coupled to the MVC

framework.</para>

</section>

<section xml:id="view-jsp">

<title>JSP &amp; JSTL</title>

<para>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 <interfacename>WebApplicationContext</interfacename>. Furthermore,

of course you need to write some JSPs that will actually render the

view.</para>

<note>

<para>

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

<link xl:href="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</link> 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.

</para>

</note>

<section xml:id="view-jsp-resolver">

<title>View resolvers</title>

<para>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 <classname>InternalResourceViewResolver</classname> and the

<classname>ResourceBundleViewResolver</classname>. Both are declared in

the <interfacename>WebApplicationContext</interfacename>:</para>

<programlisting language="xml"><lineannotation>&lt;!-- the ResourceBundleViewResolver --&gt;</lineannotation>

&lt;bean id="viewResolver" class="org.springframework.web.servlet.view.ResourceBundleViewResolver"&gt;

&lt;property name="basename" value="views"/&gt;

&lt;/bean&gt;

<lineannotation># And a sample properties file is uses (views.properties in WEB-INF/classes):</lineannotation>

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</programlisting>

<para>As you can see, the

<classname>ResourceBundleViewResolver</classname> needs a properties

file defining the view names mapped to 1) a class and 2) a URL. With a

<classname>ResourceBundleViewResolver</classname> you can mix different

types of views using only one resolver.</para>

<programlisting language="xml">&lt;bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver"&gt;

&lt;property name="viewClass" value="org.springframework.web.servlet.view.JstlView"/&gt;

&lt;property name="prefix" value="/WEB-INF/jsp/"/&gt;

&lt;property name="suffix" value=".jsp"/&gt;

&lt;/bean&gt;</programlisting>

<para>The <classname>InternalResourceBundleViewResolver</classname> 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

<filename class="directory">'WEB-INF'</filename> directory, so there can

be no direct access by clients.</para>

</section>

<section xml:id="view-jsp-jstl">

<title>'Plain-old' JSPs versus JSTL</title>

<para>When using the Java Standard Tag Library you must use a special

view class, the <classname>JstlView</classname>, as JSTL needs some

preparation before things such as the I18N features will work.</para>

</section>

<section xml:id="view-jsp-tags">

<title>Additional tags facilitating development</title>

<para>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

<emphasis>HTML escaping</emphasis> features to enable or disable

escaping of characters.</para>

<para>The tag library descriptor (TLD) is included in the <filename

class="libraryfile">spring-webmvc.jar</filename>.

Further information about the individual tags can be found in

the appendix entitled <xref linkend="spring.tld" />.</para>

</section>

<section xml:id="view-jsp-formtaglib">

<title>Using Spring's form tag library</title>

<para>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.</para>

<para>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.</para>

<para>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.</para>

<section xml:id="view-jsp-formtaglib-configuration">

<title>Configuration</title>

<para>The form tag library comes bundled in

<literal>spring-webmvc.jar</literal>.

The library descriptor is called

<literal>spring-form.tld</literal>.</para>

<para>To use the tags from this library, add the following directive

to the top of your JSP page:</para>

<programlisting language="xml">&lt;%@ taglib prefix="form" uri="http://www.springframework.org/tags/form" %&gt;</programlisting>

<para>... where <literal>form</literal> is the tag name prefix you

want to use for the tags from this library.</para>

</section>

<section xml:id="view-jsp-formtaglib-formtag">

<title>The <literal>form</literal> tag</title>

<para>This tag renders an HTML 'form' tag and exposes a binding path

to inner tags for binding. It puts the command object in the

<literal>PageContext</literal> so that the command object can be

accessed by inner tags. <emphasis>All the other tags in this library

are nested tags of the <literal>form</literal> tag</emphasis>.</para>

<para>Let's assume we have a domain object called

<classname>User</classname>. It is a JavaBean with properties such as

<literal>firstName</literal> and <literal>lastName</literal>. We will

use it as the form backing object of our form controller which returns

<literal>form.jsp</literal>. Below is an example of what

<literal>form.jsp</literal> would look like:</para>

<programlisting language="xml">&lt;form:form&gt;

&lt;table&gt;

&lt;tr&gt;

&lt;td&gt;First Name:&lt;/td&gt;

&lt;td&gt;&lt;form:input path="firstName" /&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;Last Name:&lt;/td&gt;

&lt;td&gt;&lt;form:input path="lastName" /&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td colspan="2"&gt;

&lt;input type="submit" value="Save Changes" /&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;/table&gt;

&lt;/form:form&gt;</programlisting>

<para>The <literal>firstName</literal> and <literal>lastName</literal>

values are retrieved from the command object placed in the

<interfacename>PageContext</interfacename> by the page controller.

Keep reading to see more complex examples of how inner tags are used

with the <literal>form</literal> tag.</para>

<para>The generated HTML looks like a standard form:</para>

<programlisting language="xml">&lt;form method="POST"&gt;

&lt;table&gt;

&lt;tr&gt;

&lt;td&gt;First Name:&lt;/td&gt;

&lt;td&gt;&lt;input name="firstName" type="text" value="Harry"/&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;Last Name:&lt;/td&gt;

&lt;td&gt;&lt;input name="lastName" type="text" value="Potter"/&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td colspan="2"&gt;

&lt;input type="submit" value="Save Changes" /&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;/table&gt;

&lt;/form&gt;</programlisting>

<para>The preceding JSP assumes that the variable name of the form

backing object is <literal>'command'</literal>. 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:</para>

<programlisting language="xml">&lt;form:form commandName="user"&gt;

&lt;table&gt;

&lt;tr&gt;

&lt;td&gt;First Name:&lt;/td&gt;

&lt;td&gt;&lt;form:input path="firstName" /&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;Last Name:&lt;/td&gt;

&lt;td&gt;&lt;form:input path="lastName" /&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td colspan="2"&gt;

&lt;input type="submit" value="Save Changes" /&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;/table&gt;

&lt;/form:form&gt;</programlisting>

</section>

<section xml:id="view-jsp-formtaglib-inputtag">

<title>The <literal>input</literal> tag</title>

<para>This tag renders an HTML 'input' tag using the bound value

and type='text' by default. For an example of this tag, see <xref

linkend="view-jsp-formtaglib-formtag" />. Starting with Spring 3.1

you can use other types such HTML5-specific types like 'email',

'tel', 'date', and others.</para>

</section>

<section xml:id="view-jsp-formtaglib-checkboxtag">

<title>The <literal>checkbox</literal> tag</title>

<para>This tag renders an HTML 'input' tag with type

'checkbox'.</para>

<para>Let's assume our <classname>User</classname> has preferences

such as newsletter subscription and a list of hobbies. Below is an

example of the <classname>Preferences</classname> class:</para>

<programlisting language="java">public class Preferences {

private boolean receiveNewsletter;

private String[] interests;

private String favouriteWord;

public boolean isReceiveNewsletter() {

return receiveNewsletter;

}

public void setReceiveNewsletter(boolean receiveNewsletter) {

this.receiveNewsletter = receiveNewsletter;

}

public String[] getInterests() {

return interests;

}

public void setInterests(String[] interests) {

this.interests = interests;

}

public String getFavouriteWord() {

return favouriteWord;

}

public void setFavouriteWord(String favouriteWord) {

this.favouriteWord = favouriteWord;

}

}</programlisting>

<para>The <literal>form.jsp</literal> would look like:</para>

<programlisting language="xml">&lt;form:form&gt;

&lt;table&gt;

&lt;tr&gt;

&lt;td&gt;Subscribe to newsletter?:&lt;/td&gt;

<lineannotation>&lt;%-- Approach 1: Property is of type java.lang.Boolean --%&gt;</lineannotation>

&lt;td&gt;&lt;form:checkbox path="preferences.receiveNewsletter"/&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;Interests:&lt;/td&gt;

&lt;td&gt;

<lineannotation>&lt;%-- Approach 2: Property is of an array or of type java.util.Collection --%&gt;</lineannotation>

Quidditch: &lt;form:checkbox path="preferences.interests" value="Quidditch"/&gt;

Herbology: &lt;form:checkbox path="preferences.interests" value="Herbology"/&gt;

Defence Against the Dark Arts: &lt;form:checkbox path="preferences.interests"

value="Defence Against the Dark Arts"/&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;Favourite Word:&lt;/td&gt;

&lt;td&gt;

<lineannotation>&lt;%-- Approach 3: Property is of type java.lang.Object --%&gt;</lineannotation>

Magic: &lt;form:checkbox path="preferences.favouriteWord" value="Magic"/&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;/table&gt;

&lt;/form:form&gt;</programlisting>

<para>There are 3 approaches to the <literal>checkbox</literal> tag

which should meet all your checkbox needs.</para>

<itemizedlist>

<listitem>

<para>Approach One - When the bound value is of type

<literal>java.lang.Boolean</literal>, the

<literal>input(checkbox)</literal> is marked as 'checked' if the

bound value is <literal>true</literal>. The

<literal>value</literal> attribute corresponds to the resolved

value of the <literal>setValue(Object)</literal> value

property.</para>

</listitem>

<listitem>

<para>Approach Two - When the bound value is of type

<literal>array</literal> or

<interfacename>java.util.Collection</interfacename>, the

<literal>input(checkbox)</literal> is marked as 'checked' if the

configured <literal>setValue(Object)</literal> value is present in

the bound <interfacename>Collection</interfacename>.</para>

</listitem>

<listitem>

<para>Approach Three - For any other bound value type, the

<literal>input(checkbox)</literal> is marked as 'checked' if the

configured <literal>setValue(Object)</literal> is equal to the

bound value.</para>

</listitem>

</itemizedlist>

<para>Note that regardless of the approach, the same HTML structure is

generated. Below is an HTML snippet of some checkboxes:</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Interests:&lt;/td&gt;

&lt;td&gt;

Quidditch: &lt;input name="preferences.interests" type="checkbox" value="Quidditch"/&gt;

&lt;input type="hidden" value="1" name="_preferences.interests"/&gt;

Herbology: &lt;input name="preferences.interests" type="checkbox" value="Herbology"/&gt;

&lt;input type="hidden" value="1" name="_preferences.interests"/&gt;

Defence Against the Dark Arts: &lt;input name="preferences.interests" type="checkbox"

value="Defence Against the Dark Arts"/&gt;

&lt;input type="hidden" value="1" name="_preferences.interests"/&gt;

&lt;/td&gt;

&lt;/tr&gt;</programlisting>

<para>What you might not expect to see is the additional hidden field

after each checkbox. When a checkbox in an HTML page is

<emphasis>not</emphasis> checked, its value will not be sent to the

server as part of the HTTP request parameters once the form is

submitted, so we need a workaround for this quirk in HTML in order for

Spring form data binding to work. The <literal>checkbox</literal> tag

follows the existing Spring convention of including a hidden parameter

prefixed by an underscore ("_") for each checkbox. By doing this, you

are effectively telling Spring that <quote>

<emphasis>the checkbox was visible in the form and I want my object

to which the form data will be bound to reflect the state of the

checkbox no matter what</emphasis>

</quote>.</para>

</section>

<section xml:id="view-jsp-formtaglib-checkboxestag">

<title>The <literal>checkboxes</literal> tag</title>

<para>This tag renders multiple HTML 'input' tags with type

'checkbox'.</para>

<para>Building on the example from the previous

<classname>checkbox</classname> tag section. Sometimes you prefer not

to have to list all the possible hobbies in your JSP page. You would

rather provide a list at runtime of the available options and pass

that in to the tag. That is the purpose of the

<classname>checkboxes</classname> tag. You pass in an

<classname>Array</classname>, a <classname>List</classname> or a

<classname>Map</classname> containing the available options in the

"items" property. Typically the bound property is a collection so it

can hold multiple values selected by the user. Below is an example of

the JSP using this tag:</para>

<programlisting language="xml">&lt;form:form&gt;

&lt;table&gt;

&lt;tr&gt;

&lt;td&gt;Interests:&lt;/td&gt;

&lt;td&gt;

<lineannotation>&lt;%-- Property is of an array or of type java.util.Collection --%&gt;</lineannotation>

&lt;form:checkboxes path="preferences.interests" items="${interestList}"/&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;/table&gt;

&lt;/form:form&gt;</programlisting>

<para>This example assumes that the "interestList" is a

<classname>List</classname> available as a model attribute containing

strings of the values to be selected from. In the case where you use a

Map, the map entry key will be used as the value and the map entry's

value will be used as the label to be displayed. You can also use a

custom object where you can provide the property names for the value

using "itemValue" and the label using "itemLabel".</para>

</section>

<section xml:id="view-jsp-formtaglib-radiobuttontag">

<title>The <literal>radiobutton</literal> tag</title>

<para>This tag renders an HTML 'input' tag with type 'radio'.</para>

<para>A typical usage pattern will involve multiple tag instances

bound to the same property but with different values.</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Sex:&lt;/td&gt;

&lt;td&gt;Male: &lt;form:radiobutton path="sex" value="M"/&gt; &lt;br/&gt;

Female: &lt;form:radiobutton path="sex" value="F"/&gt; &lt;/td&gt;

&lt;/tr&gt;</programlisting>

</section>

<section xml:id="view-jsp-formtaglib-radiobuttonstag">

<title>The <literal>radiobuttons</literal> tag</title>

<para>This tag renders multiple HTML 'input' tags with type

'radio'.</para>

<para>Just like the <classname>checkboxes</classname> tag above, you

might want to pass in the available options as a runtime variable. For

this usage you would use the <classname>radiobuttons</classname> tag.

You pass in an <classname>Array</classname>, a

<classname>List</classname> or a <classname>Map</classname> containing

the available options in the "items" property. In the case where you

use a Map, the map entry key will be used as the value and the map

entry's value will be used as the label to be displayed. You can also

use a custom object where you can provide the property names for the

value using "itemValue" and the label using "itemLabel".</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Sex:&lt;/td&gt;

&lt;td&gt;&lt;form:radiobuttons path="sex" items="${sexOptions}"/&gt;&lt;/td&gt;

&lt;/tr&gt;</programlisting>

</section>

<section xml:id="view-jsp-formtaglib-passwordtag">

<title>The <literal>password</literal> tag</title>

<para>This tag renders an HTML 'input' tag with type 'password' using

the bound value.</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Password:&lt;/td&gt;

&lt;td&gt;

&lt;form:password path="password" /&gt;

&lt;/td&gt;

&lt;/tr&gt;</programlisting>

<para>Please note that by default, the password value is

<emphasis>not</emphasis> shown. If you do want the password value to

be shown, then set the value of the <literal>'showPassword'</literal>

attribute to true, like so.</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Password:&lt;/td&gt;

&lt;td&gt;

&lt;form:password path="password" value="^76525bvHGq" showPassword="true" /&gt;

&lt;/td&gt;

&lt;/tr&gt;</programlisting>

</section>

<section xml:id="view-jsp-formtaglib-selecttag">

<title>The <literal>select</literal> tag</title>

<para>This tag renders an HTML 'select' element. It supports data

binding to the selected option as well as the use of nested

<literal>option</literal> and <literal>options</literal> tags.</para>

<para>Let's assume a <classname>User</classname> has a list of

skills.</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Skills:&lt;/td&gt;

&lt;td&gt;&lt;form:select path="skills" items="${skills}"/&gt;&lt;/td&gt;

&lt;/tr&gt;</programlisting>

<para>If the <literal>User's</literal> skill were in Herbology, the

HTML source of the 'Skills' row would look like:</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Skills:&lt;/td&gt;

&lt;td&gt;&lt;select name="skills" multiple="true"&gt;

&lt;option value="Potions"&gt;Potions&lt;/option&gt;

&lt;option value="Herbology" selected="selected"&gt;Herbology&lt;/option&gt;

&lt;option value="Quidditch"&gt;Quidditch&lt;/option&gt;&lt;/select&gt;

&lt;/td&gt;

&lt;/tr&gt;</programlisting>

</section>

<section xml:id="view-jsp-formtaglib-optiontag">

<title>The <literal>option</literal> tag</title>

<para>This tag renders an HTML 'option'. It sets 'selected' as

appropriate based on the bound value.</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;House:&lt;/td&gt;

&lt;td&gt;

&lt;form:select path="house"&gt;

&lt;form:option value="Gryffindor"/&gt;

&lt;form:option value="Hufflepuff"/&gt;

&lt;form:option value="Ravenclaw"/&gt;

&lt;form:option value="Slytherin"/&gt;

&lt;/form:select&gt;

&lt;/td&gt;

&lt;/tr&gt;</programlisting>

<para>If the <literal>User's</literal> house was in Gryffindor, the

HTML source of the 'House' row would look like:</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;House:&lt;/td&gt;

&lt;td&gt;

&lt;select name="house"&gt;

&lt;option value="Gryffindor" selected="selected"&gt;Gryffindor&lt;/option&gt;

&lt;option value="Hufflepuff"&gt;Hufflepuff&lt;/option&gt;

&lt;option value="Ravenclaw"&gt;Ravenclaw&lt;/option&gt;

&lt;option value="Slytherin"&gt;Slytherin&lt;/option&gt;

&lt;/select&gt;

&lt;/td&gt;

&lt;/tr&gt;</programlisting>

</section>

<section xml:id="view-jsp-formtaglib-optionstag">

<title>The <literal>options</literal> tag</title>

<para>This tag renders a list of HTML 'option' tags. It sets the

'selected' attribute as appropriate based on the bound value.</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Country:&lt;/td&gt;

&lt;td&gt;

&lt;form:select path="country"&gt;

&lt;form:option value="-" label="--Please Select"/&gt;

&lt;form:options items="${countryList}" itemValue="code" itemLabel="name"/&gt;

&lt;/form:select&gt;

&lt;/td&gt;

&lt;/tr&gt;</programlisting>

<para>If the <classname>User</classname> lived in the UK, the HTML

source of the 'Country' row would look like:</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Country:&lt;/td&gt;

&lt;td&gt;

&lt;select name="country"&gt;

&lt;option value="-"&gt;--Please Select&lt;/option&gt;

&lt;option value="AT"&gt;Austria&lt;/option&gt;

&lt;option value="UK" selected="selected"&gt;United Kingdom&lt;/option&gt;

&lt;option value="US"&gt;United States&lt;/option&gt;

&lt;/select&gt;

&lt;/td&gt;

&lt;/tr&gt;</programlisting>

<para>As the example shows, the combined usage of an

<literal>option</literal> tag with the <literal>options</literal> tag

generates the same standard HTML, but allows you to explicitly specify

a value in the JSP that is for display only (where it belongs) such as

the default string in the example: "-- Please Select".</para>

<para>The <literal>items</literal> attribute is typically populated

with a collection or array of item objects.

<literal>itemValue</literal> and <literal>itemLabel</literal> simply

refer to bean properties of those item objects, if specified;

otherwise, the item objects themselves will be stringified.

Alternatively, you may specify a <literal>Map</literal> of items, in

which case the map keys are interpreted as option values and the map

values correspond to option labels. If <literal>itemValue</literal>

and/or <literal>itemLabel</literal> happen to be specified as well,

the item value property will apply to the map key and the item label

property will apply to the map value.</para>

</section>

<section xml:id="view-jsp-formtaglib-textAreatag">

<title>The <literal>textarea</literal> tag</title>

<para>This tag renders an HTML 'textarea'.</para>

<programlisting language="xml">&lt;tr&gt;

&lt;td&gt;Notes:&lt;/td&gt;

&lt;td&gt;&lt;form:textarea path="notes" rows="3" cols="20" /&gt;&lt;/td&gt;

&lt;td&gt;&lt;form:errors path="notes" /&gt;&lt;/td&gt;

&lt;/tr&gt;</programlisting>

</section>

<section xml:id="view-jsp-formtaglib-hiddeninputtag">

<title>The <literal>hidden</literal> tag</title>

<para>This tag renders an HTML 'input' tag with type 'hidden' using

the bound value. To submit an unbound hidden value, use the HTML

<literal>input</literal> tag with type 'hidden'.</para>

<programlisting language="xml">&lt;form:hidden path="house" /&gt;

</programlisting>

<para>If we choose to submit the 'house' value as a hidden one, the

HTML would look like:</para>

<programlisting language="xml">&lt;input name="house" type="hidden" value="Gryffindor"/&gt;

</programlisting>

</section>

<section xml:id="view-jsp-formtaglib-errorstag">

<title>The <literal>errors</literal> tag</title>

<para>This tag renders field errors in an HTML 'span' tag. It provides

access to the errors created in your controller or those that were

created by any validators associated with your controller.</para>

<para>Let's assume we want to display all error messages for the

<literal>firstName</literal> and <literal>lastName</literal> fields

once we submit the form. We have a validator for instances of the

<classname>User</classname> class called

<classname>UserValidator</classname>.</para>

<programlisting language="java">public class UserValidator implements Validator {

public boolean supports(Class candidate) {

return User.class.isAssignableFrom(candidate);

}

public void validate(Object obj, Errors errors) {

ValidationUtils.rejectIfEmptyOrWhitespace(errors, "firstName", "required", "Field is required.");

ValidationUtils.rejectIfEmptyOrWhitespace(errors, "lastName", "required", "Field is required.");

}

}</programlisting>

<para>The <literal>form.jsp</literal> would look like:</para>

<programlisting language="xml">&lt;form:form&gt;

&lt;table&gt;

&lt;tr&gt;

&lt;td&gt;First Name:&lt;/td&gt;

&lt;td&gt;&lt;form:input path="firstName" /&gt;&lt;/td&gt;

<lineannotation>&lt;%-- Show errors for firstName field --%&gt;</lineannotation>

&lt;td&gt;&lt;form:errors path="firstName" /&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;Last Name:&lt;/td&gt;

&lt;td&gt;&lt;form:input path="lastName" /&gt;&lt;/td&gt;

<lineannotation>&lt;%-- Show errors for lastName field --%&gt;</lineannotation>

&lt;td&gt;&lt;form:errors path="lastName" /&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td colspan="3"&gt;

&lt;input type="submit" value="Save Changes" /&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;/table&gt;

&lt;/form:form&gt;</programlisting>

<para>If we submit a form with empty values in the

<literal>firstName</literal> and <literal>lastName</literal> fields,

this is what the HTML would look like:</para>

<programlisting language="xml">&lt;form method="POST"&gt;

&lt;table&gt;

&lt;tr&gt;

&lt;td&gt;First Name:&lt;/td&gt;

&lt;td&gt;&lt;input name="firstName" type="text" value=""/&gt;&lt;/td&gt;

<lineannotation>&lt;%-- Associated errors to firstName field displayed --%&gt;</lineannotation>

&lt;td&gt;&lt;span name="firstName.errors"&gt;Field is required.&lt;/span&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;Last Name:&lt;/td&gt;

&lt;td&gt;&lt;input name="lastName" type="text" value=""/&gt;&lt;/td&gt;

<lineannotation>&lt;%-- Associated errors to lastName field displayed --%&gt;</lineannotation>

&lt;td&gt;&lt;span name="lastName.errors"&gt;Field is required.&lt;/span&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td colspan="3"&gt;

&lt;input type="submit" value="Save Changes" /&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;/table&gt;

&lt;/form&gt;</programlisting>

<para>What if we want to display the entire list of errors for a given

page? The example below shows that the <literal>errors</literal> tag

also supports some basic wildcarding functionality.</para>

<itemizedlist>

<listitem>

<para><literal>path="*"</literal> - displays all errors</para>

</listitem>

<listitem>

<para><literal>path="lastName"</literal> - displays all errors

associated with the <literal>lastName</literal> field</para>

</listitem>

<listitem>

<para>if <literal>path</literal> is omitted - object errors only are displayed</para>

</listitem>

</itemizedlist>

<para>The example below will display a list of errors at the top of

the page, followed by field-specific errors next to the fields:</para>

<programlisting language="xml">&lt;form:form&gt;

&lt;form:errors path="*" cssClass="errorBox" /&gt;

&lt;table&gt;

&lt;tr&gt;

&lt;td&gt;First Name:&lt;/td&gt;

&lt;td&gt;&lt;form:input path="firstName" /&gt;&lt;/td&gt;

&lt;td&gt;&lt;form:errors path="firstName" /&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;Last Name:&lt;/td&gt;

&lt;td&gt;&lt;form:input path="lastName" /&gt;&lt;/td&gt;

&lt;td&gt;&lt;form:errors path="lastName" /&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td colspan="3"&gt;

&lt;input type="submit" value="Save Changes" /&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;/table&gt;

&lt;/form:form&gt;</programlisting>

<para>The HTML would look like:</para>

<programlisting language="xml">&lt;form method="POST"&gt;

&lt;span name="*.errors" class="errorBox"&gt;Field is required.&lt;br/&gt;Field is required.&lt;/span&gt;

&lt;table&gt;

&lt;tr&gt;

&lt;td&gt;First Name:&lt;/td&gt;

&lt;td&gt;&lt;input name="firstName" type="text" value=""/&gt;&lt;/td&gt;

&lt;td&gt;&lt;span name="firstName.errors"&gt;Field is required.&lt;/span&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td&gt;Last Name:&lt;/td&gt;

&lt;td&gt;&lt;input name="lastName" type="text" value=""/&gt;&lt;/td&gt;

&lt;td&gt;&lt;span name="lastName.errors"&gt;Field is required.&lt;/span&gt;&lt;/td&gt;

&lt;/tr&gt;

&lt;tr&gt;

&lt;td colspan="3"&gt;

&lt;input type="submit" value="Save Changes" /&gt;

&lt;/td&gt;

&lt;/tr&gt;

&lt;/form&gt;</programlisting>

</section>

<section xml:id="rest-method-conversion">

<title>HTTP Method Conversion</title>

<para>A key principle of REST is the use of the Uniform Interface.

This means that all resources (URLs) can be manipulated using the same

four HTTP methods: GET, PUT, POST, and DELETE. For each method, the

HTTP specification defines the exact semantics. For instance, a GET

should always be a safe operation, meaning that is has no side

effects, and a PUT or DELETE should be idempotent, meaning that you

can repeat these operations over and over again, but the end result

should be the same. While HTTP defines these four methods, HTML only

supports two: GET and POST. Fortunately, there are two possible

workarounds: you can either use JavaScript to do your PUT or DELETE,

or simply do a POST with the 'real' method as an additional parameter

(modeled as a hidden input field in an HTML form). This latter trick

is what Spring's <classname>HiddenHttpMethodFilter</classname> does.

This filter is a plain Servlet Filter and therefore it can be used in

combination with any web framework (not just Spring MVC). Simply add

this filter to your web.xml, and a POST with a hidden _method

parameter will be converted into the corresponding HTTP method

request.</para>

<para>To support HTTP method conversion the Spring MVC form tag was

updated to support setting the HTTP method. For example, the following

snippet taken from the updated Petclinic sample</para>

<programlisting language="xml">&lt;form:form method="delete"&gt;

&lt;p class="submit"&gt;&lt;input type="submit" value="Delete Pet"/&gt;&lt;/p&gt;

&lt;/form:form&gt;</programlisting>

<para>This will actually perform an HTTP POST, with the 'real' DELETE

method hidden behind a request parameter, to be picked up by the

<classname>HiddenHttpMethodFilter</classname>, as defined in web.xml:</para>

<programlisting language="java">&lt;filter&gt;

&lt;filter-name&gt;httpMethodFilter&lt;/filter-name&gt;

&lt;filter-class&gt;org.springframework.web.filter.HiddenHttpMethodFilter&lt;/filter-class&gt;

&lt;/filter&gt;

&lt;filter-mapping&gt;

&lt;filter-name&gt;httpMethodFilter&lt;/filter-name&gt;

&lt;servlet-name&gt;petclinic&lt;/servlet-name&gt;

&lt;/filter-mapping&gt;</programlisting><para>The corresponding @Controller method

is shown below:</para>

<programlisting language="java">@RequestMapping(method = RequestMethod.DELETE)

public String deletePet(@PathVariable int ownerId, @PathVariable int petId) {

this.clinic.deletePet(petId);

return "redirect:/owners/" + ownerId;

}</programlisting>

</section>

<section xml:id="view-jsp-formtaglib-html5">

<title>HTML5 Tags</title>

<para>Starting with Spring 3, the Spring form tag library allows entering

dynamic attributes, which means you can enter any HTML5 specific attributes.

</para>

<para>In Spring 3.1, the form input tag supports entering a type attribute

other than 'text'. This is intended to allow rendering new HTML5 specific

input types such as 'email', 'date', 'range', and others. Note that

entering type='text' is not required since 'text' is the default type.

</para>

</section>

</section>

</section>

<section xml:id="view-tiles">

<title>Tiles</title>

<para>It is possible to integrate Tiles - just as any other view

technology - in web applications using Spring. The following describes in

a broad way how to do this.</para>

<para><emphasis>NOTE:</emphasis> This section focuses on Spring's support

for Tiles 2 (the standalone version of Tiles, requiring Java 5+) in the

<literal>org.springframework.web.servlet.view.tiles2</literal> package as

as well as Tiles 3 in the

<literal>org.springframework.web.servlet.view.tiles3</literal> package.

Spring also continues to support Tiles 1.x (a.k.a. "Struts Tiles", as

shipped with Struts 1.1+; compatible with Java 1.4) in the original

<literal>org.springframework.web.servlet.view.tiles</literal>

package.</para>

<section xml:id="view-tiles-dependencies">

<title>Dependencies</title>

<para>To be able to use Tiles you have to have a couple of additional

dependencies included in your project. The following is the list of

dependencies you need.</para>

<itemizedlist spacing="compact">

<listitem>

<para><literal>Tiles version 2.1.2 or higher</literal></para>

</listitem>

<listitem>

<para><literal>Commons BeanUtils</literal></para>

</listitem>

<listitem>

<para><literal>Commons Digester</literal></para>

</listitem>

<listitem>

<para><literal>Commons Logging</literal></para>

</listitem>

</itemizedlist>

</section>

<section xml:id="view-tiles-integrate">

<title>How to integrate Tiles</title>

<para>To be able to use Tiles, you have to configure it using files

containing definitions (for basic information on definitions and other

Tiles concepts, please have a look at <link

xl:href="http://tiles.apache.org" />). In Spring this is done using the

<classname>TilesConfigurer</classname>. Have a look at the following

piece of example ApplicationContext configuration:</para>

<programlisting language="xml">&lt;bean id="tilesConfigurer" class="org.springframework.web.servlet.view.tiles2.TilesConfigurer"&gt;

&lt;property name="definitions"&gt;

&lt;list&gt;

&lt;value&gt;/WEB-INF/defs/general.xml&lt;/value&gt;

&lt;value&gt;/WEB-INF/defs/widgets.xml&lt;/value&gt;

&lt;value&gt;/WEB-INF/defs/administrator.xml&lt;/value&gt;

&lt;value&gt;/WEB-INF/defs/customer.xml&lt;/value&gt;

&lt;value&gt;/WEB-INF/defs/templates.xml&lt;/value&gt;

&lt;/list&gt;

&lt;/property&gt;

&lt;/bean&gt;</programlisting>

<para>As you can see, there are five files containing definitions, which

are all located in the <filename

class="directory">'WEB-INF/defs'</filename> directory. At initialization

of the <interfacename>WebApplicationContext</interfacename>, the files

will be loaded and the definitions factory will be initialized. After

that has been done, the Tiles includes in the definition files can be

used as views within your Spring web application. To be able to use the

views you have to have a <interfacename>ViewResolver</interfacename>

just as with any other view technology used with Spring. Below you can

find two possibilities, the <classname>UrlBasedViewResolver</classname>

and the <classname>ResourceBundleViewResolver</classname>.</para>

<section xml:id="view-tiles-url">

<title>

<classname>UrlBasedViewResolver</classname>

</title>

<para>The <classname>UrlBasedViewResolver</classname> instantiates the

given <literal>viewClass</literal> for each view it has to

resolve.</para>

<programlisting language="xml">&lt;bean id="viewResolver" class="org.springframework.web.servlet.view.UrlBasedViewResolver"&gt;

&lt;property name="viewClass" value="org.springframework.web.servlet.view.tiles2.TilesView"/&gt;

&lt;/bean&gt;</programlisting>

</section>

<section xml:id="view-tiles-resource">

<title>

<classname>ResourceBundleViewResolver</classname>

</title>

<para>The <classname>ResourceBundleViewResolver</classname> has to be

provided with a property file containing viewnames and viewclasses the

resolver can use:</para>

<programlisting language="xml">&lt;bean id="viewResolver" class="org.springframework.web.servlet.view.ResourceBundleViewResolver"&gt;

&lt;property name="basename" value="views"/&gt;

&lt;/bean&gt;</programlisting>

<programlisting language="java">...

welcomeView.(class)=org.springframework.web.servlet.view.tiles2.TilesView

welcomeView.url=welcome <lineannotation>(this is the name of a Tiles definition)</lineannotation>

vetsView.(class)=org.springframework.web.servlet.view.tiles2.TilesView

vetsView.url=vetsView <lineannotation>(again, this is the name of a Tiles definition)</lineannotation>

findOwnersForm.(class)=org.springframework.web.servlet.view.JstlView

findOwnersForm.url=/WEB-INF/jsp/findOwners.jsp

...</programlisting>

<para>As you can see, when using the

<classname>ResourceBundleViewResolver</classname>, you can easily mix

different view technologies.</para>

<para>Note that the <classname>TilesView</classname> class for Tiles 2

supports JSTL (the JSP Standard Tag Library) out of the box, whereas

there is a separate <classname>TilesJstlView</classname> subclass in the

Tiles 1.x support.</para>

</section>

<section xml:id="view-tiles-preparer">

<title><classname>SimpleSpringPreparerFactory</classname> and

<classname>SpringBeanPreparerFactory</classname></title>

<para>As an advanced feature, Spring also supports two special Tiles 2

<interfacename>PreparerFactory</interfacename> implementations. Check

out the Tiles documentation for details on how to use

<interfacename>ViewPreparer</interfacename> references in your Tiles

definition files.</para>

<para>Specify <classname>SimpleSpringPreparerFactory</classname> to

autowire ViewPreparer instances based on specified preparer classes,

applying Spring's container callbacks as well as applying configured

Spring BeanPostProcessors. If Spring's context-wide annotation-config

has been activated, annotations in ViewPreparer classes will be

automatically detected and applied. Note that this expects preparer

<emphasis>classes</emphasis> in the Tiles definition files, just like

the default <classname>PreparerFactory</classname> does.</para>

<para>Specify <classname>SpringBeanPreparerFactory</classname> to

operate on specified preparer <emphasis>names</emphasis> instead of

classes, obtaining the corresponding Spring bean from the

DispatcherServlet's application context. The full bean creation

process will be in the control of the Spring application context in

this case, allowing for the use of explicit dependency injection

configuration, scoped beans etc. Note that you need to define one

Spring bean definition per preparer name (as used in your Tiles

definitions).</para>

<programlisting language="xml">&lt;bean id="tilesConfigurer" class="org.springframework.web.servlet.view.tiles2.TilesConfigurer"&gt;

&lt;property name="definitions"&gt;

&lt;list&gt;

&lt;value&gt;/WEB-INF/defs/general.xml&lt;/value&gt;

&lt;value&gt;/WEB-INF/defs/widgets.xml&lt;/value&gt;

&lt;value&gt;/WEB-INF/defs/administrator.xml&lt;/value&gt;

&lt;value&gt;/WEB-INF/defs/customer.xml&lt;/value&gt;

&lt;value&gt;/WEB-INF/defs/templates.xml&lt;/value&gt;

&lt;/list&gt;