struts-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From lukaszlen...@apache.org
Subject [struts-site] branch master updated: Exports JasperReport tutorial
Date Thu, 05 Oct 2017 08:20:06 GMT
This is an automated email from the ASF dual-hosted git repository.

lukaszlenart pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/struts-site.git


The following commit(s) were added to refs/heads/master by this push:
     new 5011b84  Exports JasperReport tutorial
5011b84 is described below

commit 5011b848105a839012edcaf727fcd4c7d27e169f
Author: Lukasz Lenart <lukaszlenart@apache.org>
AuthorDate: Thu Oct 5 10:20:00 2017 +0200

    Exports JasperReport tutorial
---
 pom.xml                                           |   4 +-
 source/core-developers/result-types.md            |   2 +-
 source/getting-started/index.md                   |   4 +
 source/getting-started/jasper-reports-tutorial.md | 327 ++++++++++++++++++++++
 4 files changed, 334 insertions(+), 3 deletions(-)

diff --git a/pom.xml b/pom.xml
index 5fa240b..67aa903 100644
--- a/pom.xml
+++ b/pom.xml
@@ -94,14 +94,14 @@
                                         <argument>-a</argument>
                                         <argument>${project.build.directory}/md/attachments</argument>
                                         <argument>-o</argument>
-                                        <argument>${project.build.directory}/md/plugin-developers.md</argument>
+                                        <argument>${project.build.directory}/md/jasper-reports-tutorial.md</argument>
                                         <argument>-u</argument>
                                         <argument>${confluence.user}:${confluence.password}</argument>
                                         <argument>-server</argument>
                                         <argument>https://cwiki.apache.org/confluence</argument>
                                         <argument>+gfm</argument>
                                         <argument>true</argument>
-                                        <argument>44163</argument>
+                                        <argument>13906</argument>
                                     </arguments>
                                 </configuration>
                             </execution>
diff --git a/source/core-developers/result-types.md b/source/core-developers/result-types.md
index a9d348e..7d27911 100644
--- a/source/core-developers/result-types.md
+++ b/source/core-developers/result-types.md
@@ -31,7 +31,7 @@ own applications.
 
 ## Optional
 
-|[JasperReports Plugin]|Used for [JasperReports Tutorial](../plugins/jasperreports/) integration|Optional,
third-party plugin|
+|[JasperReports Plugin](../plugins/jasperreports/)|Used for [JasperReports Tutorial](../getting-started/jasper-reports-tutorial.html)
integration|Optional, third-party plugin|
 
 Additional Result Types can be created and plugged into an application by implementing the
`com.opensymphony.xwork2.Result`
 interface. Custom Result Types might include generating an email or JMS message, generating
images, and so forth.
diff --git a/source/getting-started/index.md b/source/getting-started/index.md
index 66cb1d7..8343a93 100644
--- a/source/getting-started/index.md
+++ b/source/getting-started/index.md
@@ -62,3 +62,7 @@ The example projects use Maven to manage the artifact dependencies and to
build
 [Preparable Interface](preperable-interface.html)
 
 [Exclude Parameters](exclude-parameters.html)
+
+## Extra tutorials
+
+[JasperReports Tutorial](jasper-reports-tutorial.html)
diff --git a/source/getting-started/jasper-reports-tutorial.md b/source/getting-started/jasper-reports-tutorial.md
new file mode 100644
index 0000000..8c5bf86
--- /dev/null
+++ b/source/getting-started/jasper-reports-tutorial.md
@@ -0,0 +1,327 @@
+---
+layout: default
+title: Getting started
+parent:
+    title: Getting started
+    url: index.html
+---
+
+# JasperReports Tutorial
+
+The Struts 2 JasperReports plugin is a bridge from Struts 2 to JasperReports and does not
include JasperReports itself, 
+which must be downloaded separately.
+
+[JasperReports](http://jasperreports.sourceforge.net) is one of the leading open-source Java
reporting libraries. 
+It compiles `.jrxml` (XML source) to `.jasper` (compiled) files, which in turn can be transformed
into several output 
+types including PDF, HTML, CSV, and XLS.
+
+In the following example, we will use the framework to create a PDF with a list of persons.
Our action will be used 
+to create a List with `Person` objects, and our JasperReports Result will use this list to
fill our template, and return 
+the PDF.
+
+## Our Person class
+
+We start by defining a simple `Person` POJO class.
+
+**com.acme.test.Person.java**
+
+```java
+package com.acme.test;
+
+public class Person {
+
+    private Long id;
+
+    private String name;
+
+    private String lastName;
+
+    public Person() {
+    }
+
+    public Person(String name, String lastName) {
+        this.name = name;
+        this.lastName = lastName;
+    }
+
+    public Person(Long id, String name, String lastName) {
+        this.id = id;
+        this.name = name;
+        this.lastName = lastName;
+    }
+
+    public Long getId() {
+        return id;
+    }
+
+    public void setId(Long id) {
+        this.id = id;
+    }
+
+    public String getLastName() {
+        return lastName;
+    }
+
+    public void setLastName(String lastName) {
+        this.lastName = lastName;
+    }
+
+    public String getName() {
+        return name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+}
+```
+
+## JasperReports libraries
+
+Before we can continue, we need to add the JR libraries to our classpath. You can download
the JR project here: 
+[http://www.sourceforge.net/projects/jasperreports](http://www.sourceforge.net/projects/jasperreports)
+
+Save the `jasperreports-X-project.zip` to your harddisk, and extract the files.
+
+We need the following files:
+
+- dist/jasperreports-X.jar
+- lib/commons-\*.jar (all the commons - except maybe for commons-logging)
+- lib/itext-X.jar
+- lib/jdt-compiler.jar
+
+Copy these jars over to your `S2_WABAPP/WEB-INF/lib` directory, and add them to your classpath.
+
+# Creating the Action
+
+**com.acme.test.action.JasperAction**
+
+```java
+package com.acme.test.action;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import net.sf.jasperreports.engine.JasperCompileManager;
+
+import com.acme.test.Person;
+import com.opensymphony.xwork.ActionSupport;
+
+public class JasperAction extends ActionSupport {
+
+    /** List to use as our JasperReports dataSource. */
+    private List<Person> myList;
+
+    public String execute() throws Exception {
+
+        // Create some imaginary persons.
+        Person p1 = new Person(new Long(1), "Patrick", "Lightbuddie");
+        Person p2 = new Person(new Long(2), "Jason", "Carrora");
+        Person p3 = new Person(new Long(3), "Alexandru", "Papesco");
+        Person p4 = new Person(new Long(4), "Jay", "Boss");
+
+        // Store people in our dataSource list (normally they would come from a database).
+        myList = new ArrayList<Person>();
+        myList.add(p1);
+        myList.add(p2);
+        myList.add(p3);
+        myList.add(p4);
+
+        // Normally we would provide a pre-compiled .jrxml file
+        // or check to make sure we don't compile on every request.
+        try {
+            JasperCompileManager.compileReportToFile(
+                    "S2_WEBAPP/jasper/our_jasper_template.jrxml",
+                    "S2_WEBAPP/jasper/our_compiled_template.jasper");
+        } catch (Exception e) {
+            e.printStackTrace();
+            return ERROR;
+        }
+
+        return SUCCESS;
+    }
+
+    public List<Person> getMyList() {
+        return myList;
+    }
+}
+```
+
+Our JasperAction creates a list of several People. The JasperCompileManager compiles the
jrxml template to a .jasper file.
+
+> Again, don't use this in production code. You should of course either provide compiled
templates, or do some sort 
+> of checking to avoid compiling the template on every request. But for our demonstration,
or development, this suits 
+> our needs just fine.
+
+# Our Jasper template
+
+JR uses XML configuration to define templates which are compiled to .jasper files. These
templates define the resulting 
+report. This is a handwritten version - for more complex versions I seriously suggest taking
a look a the various GUI designers.
+
+**our_jasper_template.jrxml**
+
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE jasperReport PUBLIC "-//JasperReports//DTD Report Design//EN" "http://jasperreports.sourceforge.net/dtds/jasperreport.dtd">
+<jasperReport name="jasper_test">
+  <!-- Our fields from the Person class. -->
+  <field name="name" class="java.lang.String"/>
+  <field name="lastName" class="java.lang.String"/>
+  <title>
+    <band height="50">
+      <staticText>
+        <reportElement x="0" y="0" width="180" height="15"/>
+        <textElement/>
+        <text><![CDATA[Struts 2 JasperReports Sample]]></text>
+      </staticText>
+    </band>
+  </title>
+  <pageHeader>
+    <band/>
+  </pageHeader>
+  <columnHeader>
+    <band height="20">
+      <staticText>
+        <reportElement x="180" y="0" width="180" height="20"/>
+        <textElement>
+          <font isUnderline="true"/>
+        </textElement>
+        <text><![CDATA[NAME]]></text>
+      </staticText>
+      <staticText>
+        <reportElement x="360" y="0" width="180" height="20"/>
+        <textElement>
+          <font isUnderline="true"/>
+        </textElement>
+        <text><![CDATA[LASTNAME]]></text>
+      </staticText>
+    </band>
+  </columnHeader>
+  <detail>
+    <band height="20">
+      <textField>
+        <reportElement x="180" y="0" width="180" height="15"/>
+        <textElement/>
+        <textFieldExpression><![CDATA[$F{name}]]></textFieldExpression>
+      </textField>
+      <textField>
+        <reportElement x="360" y="0" width="180" height="15"/>
+        <textElement/>
+        <textFieldExpression><![CDATA[$F{lastName}]]></textFieldExpression>
+      </textField>
+    </band>
+  </detail>
+  <columnFooter>
+    <band/>
+  </columnFooter>
+  <pageFooter>
+    <band height="15">
+      <staticText>
+        <reportElement x="0" y="0" width="40" height="15"/>
+        <textElement/>
+        <text><![CDATA[Page:]]></text>
+      </staticText>
+      <textField>
+        <reportElement x="40" y="0" width="100" height="15"/>
+        <textElement/>
+        <textFieldExpression class="java.lang.Integer"><![CDATA[$V{PAGE_NUMBER}]]></textFieldExpression>
+      </textField>
+    </band>
+  </pageFooter>
+  <summary>
+    <band/>
+  </summary>
+</jasperReport>
+```
+
+Save this file in `S2_WEBAPP/jasper/` as `our_jasper_template.jrxml`.
+
+Most important: we declared the fields name and lastName (two properties from our `Person`
class). This means we will 
+now be able to use these fields in our Jasper template.
+
+We define two columnheaders (NAME and LASTNAME), and then add our fields to the detail band
(for a better explanation, 
+look at the JR tutorial). This 'detail' band will iterate over our List of People. This is
the default behaviour of JR - 
+so if you want to display more information from the Person, add them to this band.
+
+In the detail band we use the `$F{name}` expression. JasperReports will ask Struts to retrieve
the `name` field value 
+from a `Person` object; the `lastName` field is handled the same way.
+
+The rest is markup to define the layout.
+
+> Use a logger (commons-logging, log4j, ...) to watch `org.apache.struts2.views.jasperreports`
in debug mode, 
+> if you have any troubles.
+
+## Registering the Action
+
+Using the JasperReports plugin requires adding the JasperReports result type as well as normal
action configuration.
+
+**struts.xml**
+
+```xml
+<package name="default" namespace="/" extends="jasperreports-default">
+    <action name="myJasperTest" class="com.acme.test.action.JasperAction">
+        <result name="success" type="jasper">
+            <param name="location">/jasper/our_compiled_template.jasper</param>
+            <param name="dataSource">myList</param>
+            <param name="format">PDF</param>
+        </result>
+    </action>
+    ...
+</package>
+```
+
+To use the JasperReports result type we must either (a) extend the `jasperreports-default`
package that defines it 
+or (b) manually define the JasperReport `jasper` result type ourselves.
+
+In the above example we extend the `jasperreports-default` package; we can define the `jasper`
result type manually 
+by defining it the same way the JasperReport plugin does:
+
+**Manually defining the "jasper" result type**
+
+```xml
+<result-types>
+    <result-type name="jasper" class="org.apache.struts2.views.jasperreports.JasperReportsResult"/>
+</result-types>
+```
+
+We configure our JasperAction with the name `myJasperTest` - this means that we can execute
this Action by sending 
+a request to `myJasperTest.action` in our browser.
+
+```xml
+<action name="myJasperTest" class="com.acme.test.action.JasperAction">
+```
+
+When our JasperAction executes correctly, we will use the Result type registered with the
name `jasper`. As discussed 
+above the `jasper` result type is available from either extending the `jasperreports-default`
package or by defining 
+the result type manually.
+
+```xml
+<result name="success" type="jasper">
+```
+
+The `location` parameter defines the location of the compiled jasper file, which will be
filled by Struts 2 with our dataSource:
+
+```xml
+<param name="location">/jasper/our_compiled_template.jasper</param>
+```
+
+The `dataSource` parameter defines the action property containing the collection of objects
to use in our report. 
+In this case it's the `myList` property which we manually filled with some `Person` objects.
+
+```xml
+<param name="dataSource">myList</param>
+```
+
+The `format` parameter specifies the output format of the report. Possible values include
PDF, CSV, XLS and HTML.
+
+```xml
+<param name="format">PDF</param>
+```
+
+## Conclusion
+
+You should now be able to execute [http://localhost:8080/YOUR_WEBAPP/myJasperTest.action](http://localhost:8080/YOUR_WEBAPP/myJasperTest.action)

+- and you should see a nice list of names.
+
+Struts provides probably the most elegant way to deal with JasperReport files; specify the
location of the .jasper file, 
+specify what dataSource you want to use, and there you go.

-- 
To stop receiving notification emails like this one, please contact
['"commits@struts.apache.org" <commits@struts.apache.org>'].

Mime
View raw message