root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

Polishing the MVC sections of the reference manual. 

git-svn-id: https://src.springframework.org/svn/spring-framework/trunk@2168 50f2f4bb-b051-0410-bef5-90022cba6387
This commit is contained in:
Sam Brannen 2009-10-22 12:53:03 +00:00
parent 0cc8236112
commit 936ef59796
1 changed files with 84 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
spring-framework-reference/src/view.xml
View File

@ -231,7 +231,6 @@ productList.url=/WEB-INF/jsp/productlist.jsp</programlisting>
<para>Let's assume our <classname>User</classname> has preferences <para>Let's assume our <classname>User</classname> has preferences
such as newsletter subscription and a list of hobbies. Below is an such as newsletter subscription and a list of hobbies. Below is an
example of the <classname>Preferences</classname> class:</para> example of the <classname>Preferences</classname> class:</para>
</section>
<programlisting language="java">public class Preferences { <programlisting language="java">public class Preferences {
@ -297,7 +296,9 @@ productList.url=/WEB-INF/jsp/productlist.jsp</programlisting>
&lt;/form:form&gt;</programlisting> &lt;/form:form&gt;</programlisting>
<para>There are 3 approaches to the <literal>checkbox</literal> tag <para>There are 3 approaches to the <literal>checkbox</literal> tag
which should meet all your checkbox needs. <itemizedlist> which should meet all your checkbox needs.</para>
<itemizedlist>
<listitem> <listitem>
<para>Approach One - When the bound value is of type <para>Approach One - When the bound value is of type
<literal>java.lang.Boolean</literal>, the <literal>java.lang.Boolean</literal>, the
@ -323,7 +324,7 @@ productList.url=/WEB-INF/jsp/productlist.jsp</programlisting>
configured <literal>setValue(Object)</literal> is equal to the configured <literal>setValue(Object)</literal> is equal to the
bound value.</para> bound value.</para>
</listitem> </listitem>
</itemizedlist></para> </itemizedlist>
<para>Note that regardless of the approach, the same HTML structure is <para>Note that regardless of the approach, the same HTML structure is
generated. Below is an HTML snippet of some checkboxes:</para> generated. Below is an HTML snippet of some checkboxes:</para>
@ -354,6 +355,7 @@ productList.url=/WEB-INF/jsp/productlist.jsp</programlisting>
to which the form data will be bound to reflect the state of the to which the form data will be bound to reflect the state of the
checkbox no matter what</emphasis> checkbox no matter what</emphasis>
</quote>.</para> </quote>.</para>
</section>
<section id="view-jsp-formtaglib-checkboxestag"> <section id="view-jsp-formtaglib-checkboxestag">
<title>The <literal>checkboxes</literal> tag</title> <title>The <literal>checkboxes</literal> tag</title>
@ -372,7 +374,6 @@ productList.url=/WEB-INF/jsp/productlist.jsp</programlisting>
"items" property. Typically the bound property is a collection so it "items" property. Typically the bound property is a collection so it
can hold multiple values selected by the user. Below is an example of can hold multiple values selected by the user. Below is an example of
the JSP using this tag:</para> the JSP using this tag:</para>
</section>
<programlisting language="xml">&lt;form:form&gt; <programlisting language="xml">&lt;form:form&gt;
&lt;table&gt; &lt;table&gt;
@ -393,6 +394,7 @@ productList.url=/WEB-INF/jsp/productlist.jsp</programlisting>
value will be used as the label to be displayed. You can also use a 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 custom object where you can provide the property names for the value
using "itemValue" and the label using "itemLabel".</para> using "itemValue" and the label using "itemLabel".</para>
</section>
<section id="view-jsp-formtaglib-radiobuttontag"> <section id="view-jsp-formtaglib-radiobuttontag">
<title>The <literal>radiobutton</literal> tag</title> <title>The <literal>radiobutton</literal> tag</title>
@ -1878,8 +1880,7 @@ home.root=words</programlisting>
spreadsheet or PDF viewer application in response.</para> spreadsheet or PDF viewer application in response.</para>
<para>In order to use Excel views, you need to add the 'poi' library to <para>In order to use Excel views, you need to add the 'poi' library to
your classpath, and for PDF generation, the iText.jar. Both are included your classpath, and for PDF generation, the iText library.</para>
in the main Spring distribution.</para>
</section> </section>
<section id="view-document-config"> <section id="view-document-config">
@ -1895,17 +1896,21 @@ home.root=words</programlisting>
<section id="view-document-configviews"> <section id="view-document-configviews">
<title>Document view definitions</title> <title>Document view definitions</title>
<para>Firstly, let's amend the views.properties file (or xml <para>First, let's amend the views.properties file (or xml
equivalent) and add a simple view definition for both document types. equivalent) and add a simple view definition for both document types.
The entire file now looks like this with the XSLT view shown from The entire file now looks like this with the XSLT view shown from
earlier.. <programlisting>home.class=xslt.HomePage earlier:</para>
<programlisting>home.class=xslt.HomePage
home.stylesheetLocation=/WEB-INF/xsl/home.xslt home.stylesheetLocation=/WEB-INF/xsl/home.xslt
home.root=words home.root=words
xl.class=excel.HomePage xl.class=excel.HomePage
pdf.class=pdf.HomePage</programlisting> <emphasis>If you want to start with a pdf.class=pdf.HomePage</programlisting>
template spreadsheet to add your model data to, specify the location
<para><emphasis>If you want to start with a
template spreadsheet or a fillable PDF form to add your model data to, specify the location
as the 'url' property in the view definition</emphasis></para> as the 'url' property in the view definition</emphasis></para>
</section> </section>
@ -1928,12 +1933,14 @@ pdf.class=pdf.HomePage</programlisting> <emphasis>If you want to start with a
<literal>org.springframework.web.servlet.view.document.AbstractExcelView</literal> <literal>org.springframework.web.servlet.view.document.AbstractExcelView</literal>
(for Excel files generated by POI) or (for Excel files generated by POI) or
<literal>org.springframework.web.servlet.view.document.AbstractJExcelView</literal> <literal>org.springframework.web.servlet.view.document.AbstractJExcelView</literal>
(for JExcelApi-generated Excel files). and implementing the (for JExcelApi-generated Excel files) and implementing the
<literal>buildExcelDocument</literal></para> <literal>buildExcelDocument()</literal> method.</para>
<para>Here's the complete listing for our POI Excel view which <para>Here's the complete listing for our POI Excel view which
displays the word list from the model map in consecutive rows of the displays the word list from the model map in consecutive rows of the
first column of a new spreadsheet.. <programlisting language="java">package excel; first column of a new spreadsheet:</para>
<programlisting language="java">package excel;
// imports omitted for brevity // imports omitted for brevity
@ -1967,10 +1974,12 @@ public class HomePage extends AbstractExcelView {
} }
} }
}</programlisting></para> }</programlisting>
<para>And this a view generating the same Excel file, now using <para>And the following is a view generating the same Excel file, now using
JExcelApi: <programlisting language="java">package excel; JExcelApi:</para>
<programlisting language="java">package excel;
// imports omitted for brevity // imports omitted for brevity
@ -1991,13 +2000,12 @@ public class HomePage extends AbstractExcelView {
sheet.addCell(new Label(2+i, 0, (String)words.get(i)); sheet.addCell(new Label(2+i, 0, (String)words.get(i));
} }
} }
} }</programlisting>
</programlisting></para>
<para>Note the differences between the APIs. We've found that the <para>Note the differences between the APIs. We've found that the
JExcelApi is somewhat more intuitive and furthermore, JExcelApi has a JExcelApi is somewhat more intuitive, and furthermore, JExcelApi has
bit better image-handling capabilities. There have been memory slightly better image-handling capabilities. There have been memory
problems with large Excel file when using JExcelApi however.</para> problems with large Excel files when using JExcelApi however.</para>
<para>If you now amend the controller such that it returns <para>If you now amend the controller such that it returns
<literal>xl</literal> as the name of the view (<literal>return new <literal>xl</literal> as the name of the view (<literal>return new
@ -2013,7 +2021,9 @@ public class HomePage extends AbstractExcelView {
class extends class extends
<literal>org.springframework.web.servlet.view.document.AbstractPdfView</literal> <literal>org.springframework.web.servlet.view.document.AbstractPdfView</literal>
and implements the <literal>buildPdfDocument()</literal> method as and implements the <literal>buildPdfDocument()</literal> method as
follows.. <programlisting language="java">package pdf; follows:</para>
<programlisting language="java">package pdf;
// imports omitted for brevity // imports omitted for brevity
@ -2033,9 +2043,11 @@ public class PDFPage extends AbstractPdfView {
doc.add( new Paragraph((String) words.get(i))); doc.add( new Paragraph((String) words.get(i)));
} }
}</programlisting> Once again, amend the controller to return the }</programlisting>
<literal>pdf</literal> view with a <literal>return new
ModelAndView("pdf", map);</literal> and reload the URL in your <para>Once again, amend the controller to return the
<literal>pdf</literal> view with <literal>return new
ModelAndView("pdf", map);</literal>, and reload the URL in your
application. This time a PDF document should appear listing each of application. This time a PDF document should appear listing each of
the words in the model map.</para> the words in the model map.</para>
</section> </section>
@ -2049,7 +2061,7 @@ public class PDFPage extends AbstractPdfView {
url="http://jasperreports.sourceforge.net"></ulink>) is a powerful url="http://jasperreports.sourceforge.net"></ulink>) is a powerful
open-source reporting engine that supports the creation of report designs open-source reporting engine that supports the creation of report designs
using an easily understood XML file format. JasperReports is capable of using an easily understood XML file format. JasperReports is capable of
rendering reports output into four different formats: CSV, Excel, HTML and rendering reports in four different formats: CSV, Excel, HTML and
PDF.</para> PDF.</para>
<section id="view-jasper-reports-dependencies"> <section id="view-jasper-reports-dependencies">
@ -2183,7 +2195,7 @@ public class PDFPage extends AbstractPdfView {
</table> </table>
<para>Mapping one of these classes to a view name and a report file is <para>Mapping one of these classes to a view name and a report file is
a matter of adding the appropriate entries into the resource bundle a matter of adding the appropriate entries in the resource bundle
configured in the previous section as shown here:</para> configured in the previous section as shown here:</para>
<programlisting>simpleReport.class=org.springframework.web.servlet.view.jasperreports.JasperReportsPdfView <programlisting>simpleReport.class=org.springframework.web.servlet.view.jasperreports.JasperReportsPdfView
@ -2211,7 +2223,7 @@ simpleReport.url=/WEB-INF/reports/DataSourceReport.jasper</programlisting>
compiling the <literal>.jrxml</literal> file on the fly for you. You compiling the <literal>.jrxml</literal> file on the fly for you. You
should note that after a <literal>.jrxml</literal> file is compiled by should note that after a <literal>.jrxml</literal> file is compiled by
the Spring Framework, the compiled report is cached for the lifetime the Spring Framework, the compiled report is cached for the lifetime
of the application. To make changes to the file you will need to of the application. Thus, to make changes to the file you will need to
restart your application.</para> restart your application.</para>
</section> </section>
@ -2220,7 +2232,7 @@ simpleReport.url=/WEB-INF/reports/DataSourceReport.jasper</programlisting>
<classname>JasperReportsMultiFormatView</classname></title> <classname>JasperReportsMultiFormatView</classname></title>
<para>The <classname>JasperReportsMultiFormatView</classname> allows <para>The <classname>JasperReportsMultiFormatView</classname> allows
for report format to be specified at runtime. The actual rendering of for the report format to be specified at runtime. The actual rendering of
the report is delegated to one of the other JasperReports view classes the report is delegated to one of the other JasperReports view classes
- the <classname>JasperReportsMultiFormatView</classname> class simply - the <classname>JasperReportsMultiFormatView</classname> class simply
adds a wrapper layer that allows for the exact implementation to be adds a wrapper layer that allows for the exact implementation to be
@ -2229,9 +2241,9 @@ simpleReport.url=/WEB-INF/reports/DataSourceReport.jasper</programlisting>
<para>The <classname>JasperReportsMultiFormatView</classname> class <para>The <classname>JasperReportsMultiFormatView</classname> class
introduces two concepts: the format key and the discriminator key. The introduces two concepts: the format key and the discriminator key. The
<classname>JasperReportsMultiFormatView</classname> class uses the <classname>JasperReportsMultiFormatView</classname> class uses the
mapping key to lookup the actual view implementation class and uses mapping key to look up the actual view implementation class, and it uses
the format key to lookup up the mapping key. From a coding perspective the format key to lookup up the mapping key. From a coding perspective
you add an entry to your model with the formay key as the key and the you add an entry to your model with the format key as the key and the
mapping key as the value, for example:</para> mapping key as the value, for example:</para>
<programlisting language="java">public ModelAndView handleSimpleReportMulti(HttpServletRequest request, <programlisting language="java">public ModelAndView handleSimpleReportMulti(HttpServletRequest request,
@ -2316,7 +2328,7 @@ HttpServletResponse response) throws Exception {
chosen, you must supply Spring with all of the data needed to populate chosen, you must supply Spring with all of the data needed to populate
your report. For JasperReports this means you must pass in all report your report. For JasperReports this means you must pass in all report
parameters along with the report datasource. Report parameters are parameters along with the report datasource. Report parameters are
simple name/value pairs and can be added be to the simple name/value pairs and can be added to the
<interfacename>Map</interfacename> for your model as you would add any <interfacename>Map</interfacename> for your model as you would add any
name/value pair.</para> name/value pair.</para>
@ -2339,7 +2351,7 @@ HttpServletResponse response) throws Exception {
<literal>JRDataSource</literal> or <literal>Collection</literal> under a <literal>JRDataSource</literal> or <literal>Collection</literal> under a
specific key and then configure this key using the specific key and then configure this key using the
<literal>reportDataKey</literal> property of the view class. In both <literal>reportDataKey</literal> property of the view class. In both
cases Spring will instances of <literal>Collection</literal> in a cases Spring will wrap instances of <literal>Collection</literal> in a
<literal>JRBeanCollectionDataSource</literal> instance. For <literal>JRBeanCollectionDataSource</literal> instance. For
example:</para> example:</para>
@ -2364,7 +2376,7 @@ simpleReport.reportDataKey=myBeanData</programlisting>
first instance of <literal>JRDataSource</literal> or first instance of <literal>JRDataSource</literal> or
<literal>Collection</literal> that it encounters. If you need to place <literal>Collection</literal> that it encounters. If you need to place
multiple instances of <literal>JRDataSource</literal> or multiple instances of <literal>JRDataSource</literal> or
<literal>Collection</literal> into the model then you need to use the <literal>Collection</literal> into the model you need to use the
second approach.</para> second approach.</para>
</section> </section>
@ -2375,10 +2387,10 @@ simpleReport.reportDataKey=myBeanData</programlisting>
your master report files. There are a wide variety of mechanisms for your master report files. There are a wide variety of mechanisms for
including sub-reports in your report files. The easiest way is to hard including sub-reports in your report files. The easiest way is to hard
code the report path and the SQL query for the sub report into your code the report path and the SQL query for the sub report into your
design files. The drawback of this approach is obvious - the values are design files. The drawback of this approach is obvious: the values are
hard-coded into your report files reducing reusability and making it hard-coded into your report files reducing reusability and making it
harder to modify and update report designs. To overcome this you can harder to modify and update report designs. To overcome this you can
configure sub-reports declaratively and you can include additional data configure sub-reports declaratively, and you can include additional data
for these sub-reports directly from your controllers.</para> for these sub-reports directly from your controllers.</para>
<section id="view-jasper-reports-subreports-config-reports"> <section id="view-jasper-reports-subreports-config-reports">
@ -2410,7 +2422,7 @@ simpleReport.reportDataKey=myBeanData</programlisting>
<literal>net.sf.jasperreports.engine.JasperReports</literal> under the <literal>net.sf.jasperreports.engine.JasperReports</literal> under the
parameter <literal>ProductsSubReport</literal>. When configuring your parameter <literal>ProductsSubReport</literal>. When configuring your
Jasper view class, you can instruct Spring to load a report file and Jasper view class, you can instruct Spring to load a report file and
pass into the JasperReports engine as a sub-report using the pass it into the JasperReports engine as a sub-report using the
<literal>subReportUrls</literal> property:</para> <literal>subReportUrls</literal> property:</para>
<programlisting language="xml">&lt;property name="subReportUrls"&gt; <programlisting language="xml">&lt;property name="subReportUrls"&gt;
@ -2420,42 +2432,44 @@ simpleReport.reportDataKey=myBeanData</programlisting>
&lt;/property&gt;</programlisting> &lt;/property&gt;</programlisting>
<para>Here, the key of the <interfacename>Map</interfacename> <para>Here, the key of the <interfacename>Map</interfacename>
corresponds to the name of the sub-report parameter in th report corresponds to the name of the sub-report parameter in the report
design file, and the entry is the URL of the report file. Spring will design file, and the entry is the URL of the report file. Spring will
load this report file, compiling it if necessary, and will pass into load this report file, compiling it if necessary, and pass it into
the JasperReports engine under the given key.</para> the JasperReports engine under the given key.</para>
</section> </section>
<section id="view-jasper-reports-subreports-config-datasources"> <section id="view-jasper-reports-subreports-config-datasources">
<title>Configuring Sub-Report Data Sources</title> <title>Configuring Sub-Report Data Sources</title>
<para>This step is entirely optional when using Spring configure your <para>This step is entirely optional when using Spring to configure your
sub-reports. If you wish, you can still configure the data source for sub-reports. If you wish, you can still configure the data source for
your sub-reports using static queries. However, if you want Spring to your sub-reports using static queries. However, if you want Spring to
convert data returned in your <literal>ModelAndView</literal> into convert data returned in your <literal>ModelAndView</literal> into
instances of <literal>JRDataSource</literal> then you need to specify instances of <literal>JRDataSource</literal> then you need to specify
which of the parameters in your <literal>ModelAndView</literal> Spring which of the parameters in your <literal>ModelAndView</literal> Spring
should convert. To do this configure the list of parameter names using should convert. To do this, configure the list of parameter names using
the <literal>subReportDataKeys</literal> property of the your chosen the <literal>subReportDataKeys</literal> property of your chosen
view class: <programlisting language="xml">&lt;property name="subReportDataKeys" view class:</para>
value="SubReportData"/&gt;</programlisting> Here, the key you supply MUST
correspond to both the key used in your <programlisting language="xml">&lt;property name="subReportDataKeys" value="SubReportData"/&gt;</programlisting>
<literal>ModelAndView</literal> and the key used in your report design
file.</para> <para>Here, the key you supply <emphasis role="bold">must</emphasis>
correspond to both the key used in your <literal>ModelAndView</literal>
and the key used in your report design file.</para>
</section> </section>
</section> </section>
<section id="view-jasper-reports-exporter-parameters"> <section id="view-jasper-reports-exporter-parameters">
<title>Configuring Exporter Parameters</title> <title>Configuring Exporter Parameters</title>
<para>If you have special requirements for exporter configuration - <para>If you have special requirements for exporter configuration --
perhaps you want a specific page size for your PDF report, then you can perhaps you want a specific page size for your PDF report -- you can
configure these exporter parameters declaratively in your Spring configure these exporter parameters declaratively in your Spring
configuration file using the <literal>exporterParameters</literal> configuration file using the <literal>exporterParameters</literal>
property of the view class. The <literal>exporterParameters</literal> property of the view class. The <literal>exporterParameters</literal>
property is typed as <interfacename>Map</interfacename> and in your property is typed as a <interfacename>Map</interfacename>. In your
configuration the key of an entry should be the fully-qualified name of configuration the key of an entry should be the fully-qualified name of
a static field that contains the exporter parameter definition and the a static field that contains the exporter parameter definition, and the
value of an entry should be the value you want to assign to the value of an entry should be the value you want to assign to the
parameter. An example of this is shown below:</para> parameter. An example of this is shown below:</para>
@ -2474,7 +2488,7 @@ simpleReport.reportDataKey=myBeanData</programlisting>
&lt;/bean&gt;</programlisting> &lt;/bean&gt;</programlisting>
<para>Here you can see that the <para>Here you can see that the
<classname>JasperReportsHtmlView</classname> is being configured with an <classname>JasperReportsHtmlView</classname> is configured with an
exporter parameter for exporter parameter for
<literal>net.sf.jasperreports.engine.export.JRHtmlExporterParameter.HTML_FOOTER</literal> <literal>net.sf.jasperreports.engine.export.JRHtmlExporterParameter.HTML_FOOTER</literal>
which will output a footer in the resulting HTML.</para> which will output a footer in the resulting HTML.</para>
@ -2493,9 +2507,9 @@ simpleReport.reportDataKey=myBeanData</programlisting>
<literal>org.springframework.web.servlet.view.feed</literal>.</para> <literal>org.springframework.web.servlet.view.feed</literal>.</para>
<para><classname>AbstractAtomFeedView</classname> requires you to <para><classname>AbstractAtomFeedView</classname> requires you to
implement the <methodname>buildFeedEntries</methodname> method and implement the <methodname>buildFeedEntries()</methodname> method and
optionally override the <methodname>buildFeedMetadata</methodname> method optionally override the <methodname>buildFeedMetadata()</methodname> method
(the default implementation is empty), as shown below</para> (the default implementation is empty), as shown below.</para>
<programlisting language="java">public class SampleContentAtomView extends AbstractAtomFeedView { <programlisting language="java">public class SampleContentAtomView extends AbstractAtomFeedView {
@ -2507,15 +2521,15 @@ simpleReport.reportDataKey=myBeanData</programlisting>
@Override @Override
protected List&lt;Entry&gt; buildFeedEntries(Map&lt;String, Object&gt; model, protected List&lt;Entry&gt; buildFeedEntries(Map&lt;String, Object&gt; model,
HttpServletRequest request, HttpServletRequest request, HttpServletResponse response)
HttpServletResponse response) throws Exception { throws Exception {
// implementation omitted // implementation omitted
} }
}</programlisting> }</programlisting>
<para>Similar requirements apply for implementing <para>Similar requirements apply for implementing
<classname>AbstractRssFeedView</classname>, as shown below</para> <classname>AbstractRssFeedView</classname>, as shown below.</para>
<programlisting language="java">public class SampleContentAtomView extends AbstractRssFeedView { <programlisting language="java">public class SampleContentAtomView extends AbstractRssFeedView {
@ -2527,25 +2541,25 @@ simpleReport.reportDataKey=myBeanData</programlisting>
@Override @Override
protected List&lt;Item&gt; buildFeedItems(Map&lt;String, Object&gt; model, protected List&lt;Item&gt; buildFeedItems(Map&lt;String, Object&gt; model,
HttpServletRequest request, HttpServletRequest request, HttpServletResponse response)
HttpServletResponse response) throws Exception { throws Exception {
// implementation omitted // implementation omitted
} }
}</programlisting> }</programlisting>
<para>The <methodname>buildFeedItems</methodname> and <para>The <methodname>buildFeedItems()</methodname> and
<methodname>buildFeedEntires</methodname> pass in the HTTP request in case <methodname>buildFeedEntires()</methodname> methods pass in the HTTP request in case
you need to access the Locale. The HTTP response is passed in only for the you need to access the Locale. The HTTP response is passed in only for the
setting of cookies or other HTTP headers. The feed will automatically be setting of cookies or other HTTP headers. The feed will automatically be
written to the response object after the method returns.</para> written to the response object after the method returns.</para>
<para>For an example of creating a Atom view please refer to Alef <para>For an example of creating an Atom view please refer to Alef
Arendsen's SpringSource Team Blog <ulink Arendsen's SpringSource Team Blog <ulink
url="http://blog.springsource.com/2009/03/16/adding-an-atom-view-to-an-application-using-springs-rest-support/">entry</ulink>.</para> url="http://blog.springsource.com/2009/03/16/adding-an-atom-view-to-an-application-using-springs-rest-support/">entry</ulink>.</para>
</section> </section>
<section> <section id="view-xml-marshalling">
<title>XML Marshalling View</title> <title>XML Marshalling View</title>
<para>The <classname>MarhsallingView</classname> uses a XML <para>The <classname>MarhsallingView</classname> uses a XML
@ -2561,4 +2575,5 @@ simpleReport.reportDataKey=myBeanData</programlisting>
chapter <link linkend="oxm">Marshalling XML using O/X chapter <link linkend="oxm">Marshalling XML using O/X
Mappers</link>.</para> Mappers</link>.</para>
</section> </section>
</chapter> </chapter>