JasperReports in Portofino

Heads up! These docs are for Portofino 3, which is a legacy product. Check out Portofino 4!

Posted by Angelo Lupo
on May 6th, 2009

Introduction

This tutorial explains how to integrate a JasperReports report with an application created in ManyDesigns Portofino.
The ticket tracker you find in the one-click-start distribution will be our example application.

Usually you will create the report definition (e.g., myreport.jrxml) outside Portofino, then compile it (e.g. to myreport.jasper) and finally copy it to Portofino's classpath. To ease the report definition you can use a tool like iReport.

Portofino can handle files both in xml format (with extension .jrxml) and in compiled form (with extension .jasper). Jrxml files can be read and modified by humans - .jasper files load faster. Whichever you choose, you must copy your JasperReports file to the WEB-INF/classes directory of your application.

Please notice that Portofino version 3.1.x uses JasperReports 3.5.0. If you use iReport to create reports, for compatibility, make sure you download iReport 3.5.0 or 3.5.1.

Types of report

In Portofino there are two types of report:

System-wide reports: reports over large amounts of data, e.g. a sales report.
Object reports: reports focused on a single object or a small group of related objects, e.g., an invoice or a purchase order. This type of report frequently results in a printed document.

Example 1: a system-wide report

This example report shows the projects available inside the ticket tracker. You can download the report definition here.

Open the projects.jrxml file in a text editor and notice the query:

<queryString><![CDATA[
SELECT "name","code","url" 
FROM "$P!{schema1}"."project"
]]></queryString>

This query simply extracts the name, code and url for all the projects in the system.

Notice that $P!{schema1} is a parameter that Portofino provides at runtime based on the value of the configuration parameter model.schema.

The use of a parameter is confirmed by another section of the jrxml file:

<parameter name="schema1" isForPrompting="false" class="java.lang.String"> 
<defaultValueExpression ><![CDATA["model"]]></defaultValueExpression> 
</parameter>

We could have hardwired the schema name "model" inside the query. However, parameters are quite common in JasperReports so it is a good idea to become familiar with them. Also, in example 2, we'll elaborate on this concept.

To run the report, first copy projects.jrxml to $CATALINA_HOME/webapps/tt/WEB-INF/classes.
Then go to the webapp homepage http://localhost:8080/tt. Downstairs log in as angelo/angelo. Then go upstairs and log in as admin/admin.

After the login, find the JasperReports tab and click on it. Then click on "Create". In the form that appears, enter the following information:

Class: Leave this blank. This makes the report system-wide, i.e., not bound to a specific object.
Name: The report's name. Enter "Projects".
Location: Enter the name of the report file: "projects.jrxml"
Description: Leave this blank.
Attachment: check this to make the report downloadable by deafult. Leave unchecked to make it viewable inside the browser.
Csv, html, pdf, etc.: The output format(s) for the report. Select pdf.

The following picture shows the form.

Go back downstairs. At the top-right corner of the page there is a Report link, which wasn't available before. Click on it.

The page that appears will show our "Projects" report as available. Click on the link to run and view the Report!!

Example 2: an object report

This example illustrates a report that shows all the versions for a given project. Running the report for a ProjectX will produce different results from running the report for ProjectY. Compare this behavior with the previous system-wide report where only one report "instance" could be run.

Download the report definition here.

Open projectVersions.jrxml in an editor and examine the SQL query:

<queryString><![CDATA[
SELECT p."name" as "projName", t."name" AS "verName",t."description"
FROM "$P!{schema1}"."project" p<
JOIN "$P!{schema1}"."version" t ON t."project" = p."id"
and p."id" = $P{id}
]]></queryString>

This time there are two parameters - $P!{schema1} and $P{id} - as confirmed by the following lines:

<parameter name="schema1" isForPrompting="false" class="java.lang.String">
     <defaultValueExpression ><![CDATA["model"]]></defaultValueExpression>
</parameter>
<parameter name="id" isForPrompting="true" class="java.lang.Integer"/>

You should already be familiar with the "schema1" parameter. The new "id" parameter is typical of object reports. In fact, it represents the id of the object (a project in our case) for which you're running the report.

To start, copy projectVersions.jrxml to $CATALINA_HOME/webapps/tt/WEB-INF/classes.
Go upstairs. Click on the JasperReports tab and then on Create. In the form, enter the following information:

Class: Select "Project" to bind the report to this class.
Name: Enter "Versions".
Location: Enter "projectVersions.jrxml"
Description: Leave this blank.
Attachment: Check this.
Csv, html, pdf, etc.: Select pdf.

Go downstairs. Go to the search page for projects and select a project, for example "Erp".

In addition to the usual 'update' and 'delete' buttons you can see a new button called 'Versions'. Click on it to run and view the report.

More information

For more information the Reports section in the reference manual provides more details on the parameters and configuration of JasperReports in Portofino.