1. Introduction

JasperReports is an open source Java reporting tool that can write to a variety of targets, such as: screen, a printer, into PDF, HTML, Microsoft Excel, RTF, ODT, Comma-separated values or XML files. It can be used in Java-enabled applications, including Java EE or web applications, to generate dynamic content.

This plugin adds easy support for launching jasper reports from GSP pages. After installing, run your application and request (app-url)/jasper/demo for a demonstration and instructions.

In addition to this document, you may want to read official Jasper Reports Library Documentation here.

1.1. Features

  • The jars for executing .jasper reports (already compiled) and/or compiling them from .jrxml files, on the fly, first.

  • A GSP taglib for launching reports.

  • Corresponding controller and service logic (that can be invoked directly)

  • 32x32 icons (web-app/images/icons/*.gif) for every supported file format .

  • A demo GSP page

1.2. Issues

All issues must be reported to GitHub Issues.

1.3. Release Notes

Version 1.7

  • Update to jasperreport 5.5.0

  • Cleanup (Thanks to Burt Beckwith)

  • various bugfixes

Version 1.5 - release 12-Dec-2013

  • Update to jasperreport 4.5.0 and POI 3.7

  • Support for Images in HTML Reports (thanks to Rafael Gutierrez for the patch)

  • various bugfixes

Version 1.2 - release 9-Jan-2012

  • Update to jasperreport 4.0.0 (sounds like a new major release of the lib, but it isn’t)

Version 1.1.0 - release 7-Aug-2010

New features:

  • Update to jasperreport 3.7.4

  • generate reports with service methods (see the included demo.gsp for documentation)

Version 1.0.0 - release 08-Jul-2010

New features:

  • Support for OpenDocument and OOXML export (ODS, ODT, DOCX, XLSX, PPTX)

  • Option to disable default parameters

  • Parameter pass-through

  • Japser libraries updated to newest version (3.7.3)

  • Refactored service with the ability to create a single document form more than one jrxml/jasper file.

  • finally uses packages

Bug fixes: Changelog

Version 0.9.5 - release 23-Jan-2009

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

Version 0.9 (Thanks to Craig Jones)

(Pending release as of 16-Aug-2008, so obtain from subversion trunk)

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.

Bug fixes:

  • 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

Infrastructure changes:

  • Numerous. (See subversion log.)

Version 0.8

New features:

  • Attribute from was removed.

  • Attributes controller and 'action' was included.

  • The developer have to use the follow architecture if the developer don’t want to use SQL into reports:

Version 0.7.7 (Thanks to Achim Breunig)

New features:

  • 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.

Version 0.7.6

New features:

  • 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)

Version 0.7.5

Bug fixed:

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

1.4. Acknowledgments

Many thanks to all the users who reported issues and sent pull requests.

1.4.1. Authors and Contributors

1.5. License

This plugin is released under the Apache License, Version 2.0

2. Usage

2.1. Installation

2.1.1. For Grails 3.x

Add the following dependency under build.gradle:

compile "org.grails.plugins:jasper:2.0.0.RC1"

2.1.2. For Grails 2.x

Add the following plugin under plugins in BuildConfig.groovy:

compile "org.grails.plugins:jasper:1.11.0"

2.1.3. What is installed?

  • The jars for executing .jasper reports (already compiled) and/or compiling them from .jrxml files, on the fly, first.

  • A GSP taglib for launching reports.

  • Corresponding controller and service logic (that can be invoked directly)

  • 32x32 icons (web-app/images/icons/*.gif) for every supported file format .

  • a demo GSP page

2.2. Configuration

The default location for your report templates is /src/main/webapp/reports in your project directory. Here you can place your *.jasper or *.jrxml (jrxml files will be compiled automatically by the plugin).

Work with jrxml files if you can! They can be compiled by the plugin if a newer jasperreport version is available. This way you don’t need to manually recompile all your reports if you want to use the new version with braking changes.

You can set another report folder location with the jasper.dir.reports property in your application.yml.

application.yml
jasper:
	dir:
		reports: '../src/main/webapp/reports'

It’s possible to use different locations for different environments.

application.yml
environments:
	development:
		jasper:
			dir:
				reports: '../src/main/webapp/reports'
	production:
		jasper:
			dir:
				reports: '/home/jasper-reports'

2.3. Basic usage

2.3.1. Tags

The plugin provides a number of tags to help with the integration in your pages.

jasperReport

The jasperReport tag generates a button for every file specified file format. With a click on one of these icons you generate the report which is returned as the response.

The jasperReport tag should not be nested with a form element, as it uses a form element in its implementation, and nesting of forms is not allowed.

 
<g:jasperReport
          jasper="sample-jasper-plugin"
          format="PDF,HTML,XML,CSV,XLS,RTF,TEXT,ODT,ODS,DOCX,XLSX,PPTX"
          name="Parameter Example">

    Your name: <input type="text" name="name"/>

</g:jasperReport>

The input of the text field will be passed to the report as a parameter.

Attributes:

  • jasper - filepath, relative to your configured report folder, of the report, no file extension needed (Required)

  • format - supply the file formats you want to use in a simple list (Required)

  • name - name of the report

  • delimiter - delimiter between the icons representing the file formats.

  • delimiterBefore - delimiter in front of the icons

  • delimiterAfter - delimiter at the end of the icons

  • description - description of the report

  • buttonPosition - position of the icons (top or below)

jasperForm

The jasperForm works the same way as the jasperReport tag, but gives you more control over how the form is rendered in HTML.

The jasperForm tag should not be nested with a form element, as it uses a form element in its implementation, and nesting of forms is not allowed.

 
<g:jasperForm controller="jasper" action="exampleWithData" id="1498" jasper="w_iReport" >

    ..form contents..

    <g:jasperButton format="pdf" jasper="jasper-test" text="PDF" />

    .. other html..

</g:jasperForm>

Attributes:

  • jasper - filepath, relative to your configured report folder, of the report, no file extension needed. (Required)

  • controller - The controller the form will submit to. (Required)

  • action - The action the form will submit to. (Required)

  • id - The id attribute for the form.

  • class - Style class to use for the form. The default is "jasperReport".

jasperButton

Use the jasperButton inside a jasperForm to submit and generate the report.

 <g:jasperButton format="pdf" jasper="jasper-test" text="PDF" />

Attributes:

  • format - The name of the supported output format. ex. 'pdf' or 'PDF'. (Required)

  • class - Class of the element in addition to default.

  • text - Text to be included next to button ex. 'print'.

2.3.2. Services

From version 1.1 upwards it’s possible to generate your report, without the controller action from above, with simple service methods (so that you can generate your reports with a cron job in combination with the Quartz plugin).

The central element for this feature is a new wrapper class JasperReportDef. Instead of putting everything in the parameter map you create a simple object containing the relevant data.

def reportDef = JasperReportDef(name:'your_report.jasper', fileFormat:JasperExportFormat.PDF_FORMAT)

As you can see there are only two required attributes. Of course you need provide the name of your report and the target file format. All available file formats can be found in the <strong>JasperExportFormat</strong> enum. You just have to choose one.

JasperReportDef has the following properties:

  • name - Name of the Report. (Required)

  • fileFormat - Fileformat of the Report. Please use the JasperExportFormat Enum. (Required)

  • folder - The folder where you placed your reports. Defaults to /reports if unset and no global setting (jasper.report.dir in Config.groovy) exists.

  • reportData - Collection containing the data of your report (leave empty if you want to use a SQL query inside your report)

  • locale - Locale to use in the report generation.

  • parameters - All additional parameters as a Map.

All you need to do now is to call one of the methods provided in <strong>JasperService</strong>: * generateReport(JasperReportDef reportDef) - Generate a "normal" report. * generateReport(List<JasperReportDef> reports) - Generate a single response containing multiple reports.

Both return a ByteArrayOutputStream with which you can do everything you want.

import org.codehaus.groovy.grails.plugins.jasper.JasperExportFormat
import org.codehaus.groovy.grails.plugins.jasper.JasperReportDef

class YourClass {

	def jasperService

	public void yourMethod() {
		def reportDef = new JasperReportDef(name:'your_report.jasper', fileFormat:JasperExportFormat.PDF_FORMAT)
		FileUtils.writeByteArrayToFile(new File("/your/target/path/test.pdf"), jasperService.generateReport(reportDef).toByteArray())
	}
}

The example above uses the apache common-io FileUtils to store the response on the disc.

3. Quickstart Guide

The guide will show how to call JasperReports from Grails application

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.

3.1. Install the plugin

Edit build.gradle file from the root of the project.

Add following dependency:

compile "org.grails.plugins:jasper:2.0.0.RC1"

TBD …​