From 936ef59796fce48ecba528f7d998e35e5233a148 Mon Sep 17 00:00:00 2001 From: Sam Brannen Date: Thu, 22 Oct 2009 12:53:03 +0000 Subject: [PATCH] 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 --- spring-framework-reference/src/view.xml | 153 +++++++++++++----------- 1 file changed, 84 insertions(+), 69 deletions(-) diff --git a/spring-framework-reference/src/view.xml b/spring-framework-reference/src/view.xml index c63142656cd..fe791313965 100644 --- a/spring-framework-reference/src/view.xml +++ b/spring-framework-reference/src/view.xml @@ -231,7 +231,6 @@ productList.url=/WEB-INF/jsp/productlist.jsp Let's assume our User has preferences such as newsletter subscription and a list of hobbies. Below is an example of the Preferences class: - public class Preferences { @@ -297,7 +296,9 @@ productList.url=/WEB-INF/jsp/productlist.jsp </form:form> There are 3 approaches to the checkbox tag - which should meet all your checkbox needs. + which should meet all your checkbox needs. + + Approach One - When the bound value is of type java.lang.Boolean, the @@ -323,7 +324,7 @@ productList.url=/WEB-INF/jsp/productlist.jsp configured setValue(Object) is equal to the bound value. - + Note that regardless of the approach, the same HTML structure is generated. Below is an HTML snippet of some checkboxes: @@ -354,6 +355,7 @@ productList.url=/WEB-INF/jsp/productlist.jsp to which the form data will be bound to reflect the state of the checkbox no matter what . +
The <literal>checkboxes</literal> tag @@ -372,7 +374,6 @@ productList.url=/WEB-INF/jsp/productlist.jsp "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: -
<form:form> <table> @@ -393,6 +394,7 @@ productList.url=/WEB-INF/jsp/productlist.jsp 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". +
The <literal>radiobutton</literal> tag @@ -1878,8 +1880,7 @@ home.root=words spreadsheet or PDF viewer application in response. 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 - in the main Spring distribution. + your classpath, and for PDF generation, the iText library.
@@ -1895,17 +1896,21 @@ home.root=words
Document view definitions - Firstly, let's amend the views.properties file (or xml + First, let's amend the views.properties file (or xml equivalent) and add a simple view definition for both document types. The entire file now looks like this with the XSLT view shown from - earlier.. home.class=xslt.HomePage + earlier: + + home.class=xslt.HomePage home.stylesheetLocation=/WEB-INF/xsl/home.xslt home.root=words xl.class=excel.HomePage -pdf.class=pdf.HomePage If you want to start with a - template spreadsheet to add your model data to, specify the location +pdf.class=pdf.HomePage + + 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
@@ -1928,12 +1933,14 @@ pdf.class=pdf.HomePage If you want to start with a org.springframework.web.servlet.view.document.AbstractExcelView (for Excel files generated by POI) or org.springframework.web.servlet.view.document.AbstractJExcelView - (for JExcelApi-generated Excel files). and implementing the - buildExcelDocument + (for JExcelApi-generated Excel files) and implementing the + buildExcelDocument() method. Here's the complete listing for our POI Excel view which displays the word list from the model map in consecutive rows of the - first column of a new spreadsheet.. package excel; + first column of a new spreadsheet: + + package excel; // imports omitted for brevity @@ -1967,11 +1974,13 @@ public class HomePage extends AbstractExcelView { } } -} +} + + And the following is a view generating the same Excel file, now using + JExcelApi: + + package excel; - And this a view generating the same Excel file, now using - JExcelApi: package excel; - // imports omitted for brevity public class HomePage extends AbstractExcelView { @@ -1991,13 +2000,12 @@ public class HomePage extends AbstractExcelView { sheet.addCell(new Label(2+i, 0, (String)words.get(i)); } } -} - +} Note the differences between the APIs. We've found that the - JExcelApi is somewhat more intuitive and furthermore, JExcelApi has a - bit better image-handling capabilities. There have been memory - problems with large Excel file when using JExcelApi however. + JExcelApi is somewhat more intuitive, and furthermore, JExcelApi has + slightly better image-handling capabilities. There have been memory + problems with large Excel files when using JExcelApi however. If you now amend the controller such that it returns xl as the name of the view (return new @@ -2013,7 +2021,9 @@ public class HomePage extends AbstractExcelView { class extends org.springframework.web.servlet.view.document.AbstractPdfView and implements the buildPdfDocument() method as - follows.. package pdf; + follows: + + package pdf; // imports omitted for brevity @@ -2033,9 +2043,11 @@ public class PDFPage extends AbstractPdfView { doc.add( new Paragraph((String) words.get(i))); } -} Once again, amend the controller to return the - pdf view with a return new - ModelAndView("pdf", map); and reload the URL in your +} + + Once again, amend the controller to return the + pdf view with return new + ModelAndView("pdf", map);, and reload the URL in your application. This time a PDF document should appear listing each of the words in the model map.
@@ -2049,7 +2061,7 @@ public class PDFPage extends AbstractPdfView { url="http://jasperreports.sourceforge.net">) is a powerful open-source reporting engine that supports the creation of report designs 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.
@@ -2183,7 +2195,7 @@ public class PDFPage extends AbstractPdfView { 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: simpleReport.class=org.springframework.web.servlet.view.jasperreports.JasperReportsPdfView @@ -2211,7 +2223,7 @@ simpleReport.url=/WEB-INF/reports/DataSourceReport.jasper compiling the .jrxml file on the fly for you. You should note that after a .jrxml file is compiled by 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.
@@ -2220,7 +2232,7 @@ simpleReport.url=/WEB-INF/reports/DataSourceReport.jasper JasperReportsMultiFormatView The JasperReportsMultiFormatView 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 JasperReportsMultiFormatView class simply adds a wrapper layer that allows for the exact implementation to be @@ -2229,9 +2241,9 @@ simpleReport.url=/WEB-INF/reports/DataSourceReport.jasper The JasperReportsMultiFormatView class introduces two concepts: the format key and the discriminator key. The JasperReportsMultiFormatView 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 - 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: 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 your report. For JasperReports this means you must pass in all report 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 Map for your model as you would add any name/value pair. @@ -2339,7 +2351,7 @@ HttpServletResponse response) throws Exception { JRDataSource or Collection under a specific key and then configure this key using the reportDataKey property of the view class. In both - cases Spring will instances of Collection in a + cases Spring will wrap instances of Collection in a JRBeanCollectionDataSource instance. For example: @@ -2364,7 +2376,7 @@ simpleReport.reportDataKey=myBeanData first instance of JRDataSource or Collection that it encounters. If you need to place multiple instances of JRDataSource or - Collection into the model then you need to use the + Collection into the model you need to use the second approach. @@ -2375,10 +2387,10 @@ simpleReport.reportDataKey=myBeanData 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 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 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.
@@ -2410,7 +2422,7 @@ simpleReport.reportDataKey=myBeanData net.sf.jasperreports.engine.JasperReports under the parameter ProductsSubReport. When configuring your 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 subReportUrls property: <property name="subReportUrls"> @@ -2420,42 +2432,44 @@ simpleReport.reportDataKey=myBeanData </property> Here, the key of the Map - 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 - 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.
Configuring Sub-Report Data Sources - This step is entirely optional when using Spring configure your + This step is entirely optional when using Spring to configure your 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 convert data returned in your ModelAndView into instances of JRDataSource then you need to specify which of the parameters in your ModelAndView Spring - should convert. To do this configure the list of parameter names using - the subReportDataKeys property of the your chosen - view class: <property name="subReportDataKeys" - value="SubReportData"/> Here, the key you supply MUST - correspond to both the key used in your - ModelAndView and the key used in your report design - file. + should convert. To do this, configure the list of parameter names using + the subReportDataKeys property of your chosen + view class: + + <property name="subReportDataKeys" value="SubReportData"/> + + Here, the key you supply must + correspond to both the key used in your ModelAndView + and the key used in your report design file.
Configuring Exporter Parameters - If you have special requirements for exporter configuration - - perhaps you want a specific page size for your PDF report, then you can + If you have special requirements for exporter configuration -- + perhaps you want a specific page size for your PDF report -- you can configure these exporter parameters declaratively in your Spring configuration file using the exporterParameters property of the view class. The exporterParameters - property is typed as Map and in your + property is typed as a Map. In your 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 parameter. An example of this is shown below: @@ -2474,7 +2488,7 @@ simpleReport.reportDataKey=myBeanData </bean> Here you can see that the - JasperReportsHtmlView is being configured with an + JasperReportsHtmlView is configured with an exporter parameter for net.sf.jasperreports.engine.export.JRHtmlExporterParameter.HTML_FOOTER which will output a footer in the resulting HTML. @@ -2493,29 +2507,29 @@ simpleReport.reportDataKey=myBeanData org.springframework.web.servlet.view.feed. AbstractAtomFeedView requires you to - implement the buildFeedEntries method and - optionally override the buildFeedMetadata method - (the default implementation is empty), as shown below + implement the buildFeedEntries() method and + optionally override the buildFeedMetadata() method + (the default implementation is empty), as shown below. public class SampleContentAtomView extends AbstractAtomFeedView { @Override protected void buildFeedMetadata(Map<String, Object> model, Feed feed, - HttpServletRequest request) { - // implementation omitted + HttpServletRequest request) { + // implementation omitted } @Override protected List<Entry> buildFeedEntries(Map<String, Object> model, - HttpServletRequest request, - HttpServletResponse response) throws Exception { + HttpServletRequest request, HttpServletResponse response) + throws Exception { - // implementation omitted + // implementation omitted } } Similar requirements apply for implementing - AbstractRssFeedView, as shown below + AbstractRssFeedView, as shown below. public class SampleContentAtomView extends AbstractRssFeedView { @@ -2527,25 +2541,25 @@ simpleReport.reportDataKey=myBeanData @Override protected List<Item> buildFeedItems(Map<String, Object> model, - HttpServletRequest request, - HttpServletResponse response) throws Exception { + HttpServletRequest request, HttpServletResponse response) + throws Exception { // implementation omitted } } - The buildFeedItems and - buildFeedEntires pass in the HTTP request in case + The buildFeedItems() and + buildFeedEntires() methods pass in the HTTP request in case 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 written to the response object after the method returns. - For an example of creating a Atom view please refer to Alef - Arendsen's SpringSource TeamBlog For an example of creating an Atom view please refer to Alef + Arendsen's SpringSource Team Blog entry.
-
+
XML Marshalling View The MarhsallingView uses a XML @@ -2561,4 +2575,5 @@ simpleReport.reportDataKey=myBeanData chapter Marshalling XML using O/X Mappers.
+