JasperGrails Tutorial

Author : Marcos Fábio Pereira (marcos [dot] at [dot] embedded.ufcg.edu.br)
Contributers : Egon Jensen, João Paulo, Vinícius Cavalcanti, Craig Jones, Aaron Eischeid

Index

• Releases
• Step-by-step guide
• FAQ
• Issues

Releases

New features:

• New tags which allow for greater control of JasperForms layout and button placement, and unobtrusive JS and CSS. see demo.gsp for documentation
• Icons rendered via CSS and new small PDF icon included
• Can now use latest iReport to edit reports thanks to updated Jasper libraries

New features:

• Added many new attributes to <g:jasperReport> that control the rendering (see demo.gsp)
• Now, if the g:jasperReport tag does not have a body, then the rendered HTML will be just a series of one or more <A> tags (no form and no javascript for submitting said form).
• Combined the redundant admin.gsp and howto.gsp into a single demo.gsp.
• Added lots more documentation and examples to demo.gsp.

• The Format attribute is now tolerant of lower case format values (pdf vs. PDF) and spaces between values.
• The tag validation code now checks for the two required attributes: jasper and format
• Rendering now uses &nbsp; and <strong> (rather than nothing and <b>) in places
• No longer renders the word "null" when the name attribute is left blank

• Numerous. (See subversion log.)

• Attribute 'from' was removed.
• Attributes 'controller' and 'action' was included.

• Attribute 'inline=<boolean>' was included in jasperReport tag. Now, pdf-files can be shown inline in the web-browser.
• Bug fixed:
• Solved problem that the 'format'-attribute did not accept spaces.
• Solved problem that sometimes the from-parameter was not found.
• The default locale of the report is the request locale.
• The default subreport folder is the same of the report.

• The user can to retrieve data report from domain classes:
• Attribute 'from' was included in jasperReport tag.
• XLS parameters were improved: (Thanks to Sebastian Esch)
• One page per sheet;
• Auto detect cell type;
• Remove empty space between rows;
• White page background is disabled.
• Bug fixed:
• Plugin didn't work on Linux (File separator was wrong). (Thanks to Sebastian Esch)

• Bug fixed:
• Bug in JasperService.groovy that can cause connection leaks, connection is never closed. (Thanks to Pass F. B. Travis)
  

Step-by-step guide;

Don't worry; JasperReports can do that, and it is easy to use in Grails.

To follow this tutorial, you first have to create the Racetrack application from Getting Started with Grails. But of course you can use your own application, just remember to do the necessary changes as you follow along.

First you have to install JasperGrails

grails install-plugin jasper

[...]
<div class="paginateButtons">
<g:paginate total="${Race.count()}" />
</div>
<g:jasperReport jasper="all-races" format="PDF" name="All Races" />
</div>
</body>
</html>

Now start the application

grails run-app

Logon and below the Race List, you'll now find a PDF icon.

">

Press the icon, and ...

Ups!

We forgot the JasperReports file :-(

As you can see in the error message, we are supposed to create and save "all-races.jasper" (a good tool to do this is IReport -- but only the version 2.x) in "racetrack/web-app/reports/". After doing that, use the browsers back button and try the PDF icon again. This time it works better.

Open the file and you get a beautiful report with all the races.

OK, I admit it, JasperReports (and iReports) is not my strong side.
Besides, this is a tutorial for JasperGrails, not for JasperReports :-)

Let's try another example.

This time we will export all the registrations for a given race to Excel. Again we start with modifying the view: "racetrack/grails-app/views/race/show.gsp"

[...]
<div class="buttons">
<g:form>
<input type="hidden" name="id" value="${race?.id}" />
<span class="button"><g:actionSubmit class="edit" value="Edit" /></span>
<span class="button"><g:actionSubmit class="delete" onclick="return warnBeforeRaceDelete();" value="Delete" /></span>
</g:form>
</div>
<g:jasperReport jasper="registrations" format="XLS" name="Registrations">
<input type="hidden" name="race_id" value="${race.id}" />
</g:jasperReport>
</div>
</body>
</html>

This time we will try with the jrxml format. Thus we save "registrations.jrxml" in "racetrack/web-app/plugins/jasper-0.8/reports/".

Remember to include the following in "registrations.jrxml", to accept the argument we send from "show.gsp":

<parameter name="race_id" isForPrompting="false" class="java.lang.String">
<defaultValueExpression><![CDATA["<parameter error>"]]></defaultValueExpression>
</parameter>
<queryString><![CDATA[select * from registration where race_id = $P{race_id}]]></queryString>

Press the icon and open the resulting file.

FAQ

Can i get the report data from domain classes, instead of a sql query?

Yes, the user can retrieve data to the report directly from domain classes, without using SQL queries in the .jrxml file. It's only necessary to set the 'controller' and 'action' attributes in jasperReport tag, like showed bellow:

<g:jasperReport controller="my-controller" action="my-action" jasper="all-races" format="PDF" name="All Races" />

In the action "my-controller/my-action", the developer has to get all data from model using the line bellow and updating <MODEL_DATA> string:

<MODEL_DATA> = Domain-Class.list() or
<MODEL_DATA> = ['field1':value1,'field2':value2] or
<MODEL_DATA> = anything you want that returns a map or a list of map...

chain(controller:'jasper',action:'index',model:[data:<MODEL_DATA>],params:params)

Now, the .jrxml file can be defined without a datasource. The only thing you have to remember is to set the name of all fields in the report with the same name of the attributes in the <MODEL_DATA> object.

You can also do some groovy drilling down on the objects you pass into the report. For example if you passed in a list of races from your controller like:

def races = Race.getAll(23,25,26)
races.each{
  println it.sposor.address
}
chain(controller:'jasper',action:'index',model:[data:races],params:params)

(grails 1.0.4 does something different with lazy fetching and the println is just a dirty work around for getting the GORM to load the objects.)

You could reference them in the jrxml file like:

<field name="sponsor.address.city" class="java.lang.String"/>
…
…
<textFieldExpression class="java.lang.String">
  <![CDATA[$F{sponsor.address.city}]]>
</textFieldExpression>

remember to set the language of your report to Groovy instead of Java

<jasperReport … language="groovy" … >

Can i use sub reports with Jasper Plugin?

Yes, if you put the sub report file in the same folder of the parent report file "APP-FOLDER/web-app/plugins/jasper-x.x/reports/" then it should work fine.

But, if you want to put the sub report file in another folder, you've to add the SUBREPORT_DIR as a parameter to your jasperReport tag.

Thanks to Achim Breunig.

note: subreports have proven to be quite troublesome for some users, and we are working on ironing these issues out for the next release. in the meantime here is some random stuff that might be helpful.

<parameter name="SUBREPORT_DIR" class="java.lang.String" isForPrompting="false"/>
…
<field name="races" class="java.util.Collection"/>

<subreport isUsingCache="true">
  <reportElement key="subreport-1" x="17" y="362" width="387" height="89"/>
  <dataSourceExpression>
    <![CDATA[new JRBeanCollectionDataSource($F{races})]]>
  </dataSourceExpression>
  <subreportExpression class="java.lang.String">
    <![CDATA[$P{SUBREPORT_DIR} + "/jasper-test_subreport1.jasper"]]>
  </subreportExpression>
</subreport>

where you have to put the subreports seems to differ for differet OS's:

Windows and Mac users can usually get away with putting the reports in the web-app/reports dir, but not always...

If this isn't working try using the compiled reports, and/or moving things into WEB-INF/reports.

Sub Report Work arounds

// For Local Grails Server
File folder = new File(".");
String folderString = folder.getAbsolutePath().toString();
folderString = folderString.substring(0, folderString.length()-2);
// For Tomcat Deployment
if (folderString.endsWith("/bin")) {
	folderString = folderString.substring(0, folderString.length()-4)
		+ "/webapps/{APP_NAME}"
}
// Reset SUBREPORT_DIR
parameters.SUBREPORT_DIR = folderString + "/WEB-INF/" + parameters.SUBREPORT_DIR;

Can i use JFree Chart with Jasper Plugin?

Yes, if you put the needed jars in the library folder of your grails installation. The needed jars are "jcommon-1.0.14.jar" and "jfreechart-1.0.11.jar".

Thanks to Srimal Jayawardena, he has posted an entry with this solution [here].

Issues

• New tags require Prototype library
• Deviations from default URL mapping cause problems (fixed for next release)
• Sub-reports use is buggy/ inconsistent