Jasper Plugin Instructions/Demo Page

This Jasper Plugin allows you to launch reports built using Jasperreports from within a Grails application. This is done by making available a new GSP tag called <g:jasperReport>.

Basically, this tag renders as a sequence of icons representing the various output formats handled by Jasper (PDF, RTF, XML, etc.) See the examples in sections 3 and 4, below. When the user clicks on the icon, the corresponding report is generated. There are numerous options to control the rendering, including which of the seven possible formats to offer and how to accompany the icons with input fields for report parameters, text labels, icon delimiters, etc.

If the <g:jasperReport> has a body, then the rendered HTML will be a <form> that includes that body. It is assumed that the body contains input tags which will be used to provide input parameters to the report. (The name of the input tag must match the name of the input parameter expected by the report.)

If the <g:jasperReport> does not have a body, then the rendered HTML will be just a series of one or more <a> tags.

1. Installation

Just execute the following from your application directory:

grails install-plugin jasper

What is installed:

2. Configuration

Option One: Create a web-app/reports folder and place your *.jasper (and/or *.jrxml) files there. That's the default location. If you follow this convention, then there is nothing more to configure.

Option Two: In Config.groovy, set jasper.dir.reports to the location of your *.jasper files. If that location is already nested within the web-app folder, then your reports will automatically be included in the war when you deploy to test or production. In that case, you'll only have to set jasper.dir.reports universally. If not, then you'll probably need to set it separately for each environment (development, test, production), and you'll likely need to define grails.war.resources as well (with a closure containing GANT commands to copy the *.jasper files into the staging dir so that they'll be included in the war).

Something like this:

    grails.war.resources = {stagingDir ->
    mkdir(dir: "$stagingDir/web-app/reports")
    copy(todir: "$stagingDir/web-app/reports") {fileset(dir:"src/reports",includes:"*.jasper")}
    }
    environments {
    development {
    // relative to web-app
    jasper.dir.reports = '../src/reports'
    }
    production {
    // relative to web-app
    jasper.dir.reports = 'reports'
    }
    }

3. Test Your Install

Type in your name and then click on any of the icons below to test your plugin installation and see a report of that type produced.

Parameter Example Your name:

  PDF HTML XML CSV XLS RTF TEXT ODT ODS DOCX XLSX PPTX

4. Some Other Examples

All Default Values

| PDF | HTML | XML | CSV | XLS | RTF | TEXT | ODT | ODS | DOCX | XLSX | PPTX | Parameter Example Your name: 
    <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>

Some Layout and Presentation Options

Your name:

 ((( PDF * HTML * XLS * RTF * TEXT * ODT * ODS * DOCX * XLSX * PPTX )))
    <g:jasperReport
    jasper="sample-jasper-plugin"
    format="pdf, html, xls, rtf, text,odt,ods,docx,xlsx,pptx"
    name="Report Name for Jasper Only]"
    inline="true"
    buttonPosition="bottom"
    description=" "
    delimiter="*"
    delimiterBefore="((("
    delimiterAfter=")))">
    Your name: <input type="text" name="name" />
    <br/><br/>
    </g:jasperReport>

Grails-Supplied Domain Data

The following data should appear in report form when you click on any of the icon buttons below.
Person's NameE-Mail Address
Amyamy@example.com
Bradbrad@example.com
Charliecharlie@example.com
Dianediane@example.com
Edwardedward@example.com
PDF HTML XML CSV XLS RTF TEXT ODT ODS DOCX XLSX PPTX 
    <g:jasperReport
    jasper="sample-list-domain-classes"
    action="exampleWithData"
    format="pdf, html, xml, csv, xls, rtf, text,odt,ods,docx,xlsx,pptx"
    name="GORM Example"
    description=" "
    delimiter=" " />
You can also use more specific tags to gain greater control over more complicated forms.
Person's NameE-Mail Address
Amyamy@example.com
Bradbrad@example.com
Charliecharlie@example.com
Dianediane@example.com
Edwardedward@example.com
PDF 
    <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>
You can also use more complex parameters in the report.
PDF HTML XML CSV XLS RTF TEXT ODT ODS DOCX XLSX PPTX   Born between and

Report with graphs (JFreeChart support)

Graph support is a common and useful feature used in reports. In Jasper/IReport the default chart library is JFreeChart.
The Grails Jasper Plugin supports JFreeChart reports. The link below shows an example of chart usage in Jasper reports.
PDF HTML XML CSV XLS RTF TEXT ODT ODS DOCX XLSX PPTX 
    <g:jasperReport
    jasper="sample-list-domain-classes-3-chart"
    action="exampleWithDataChart"
    format="pdf, html, xml, csv, xls, rtf, text,odt,ods,docx,xlsx,pptx"
    name="GORM chart Example"
    description=" "
    delimiter=" " />


Additional parameters, which are supported for some file formats, can be passed through (see jasperreport documentation for details). Use the HTML_HEADER parameter to apply a custom html header to your output:



 | HTML |
    <g:jasperReport
    jasper="sample-jasper-plugin"
    format="html"
    inline="true"
    buttonPosition="bottom">
    <input type="hidden" name="HTML_HEADER" value="<h2>-----------Header-----------</h2>" />
    </g:jasperReport>

This plugin sets some default values for a bunch of these parameters. You can disable these defaults by submitting "useDefaultParameters" (Boolean values, defaults to true). 
    <g:jasperReport
    jasper="sample-jasper-plugin"
    format="html"
    inline="true"
    buttonPosition="bottom">
    <input type="hidden" name="useDefaultParameters" value="false" />
    </g:jasperReport>

5. Tag Reference

<g:jasperReport>

The jasperReport tag creates a link to a jasper report defined by the developer. By default, the report must either reside in the "%PROJECT_HOME%/web-app/reports/" folder, or the path must be defined in the Config.groovy file, in the variable jasper.dir.reports.

The following attributes can be defined in the tag:

New Tags:

<g:jasperForm>


Much the same as the jasperReport tag, but gives you more control over how a form is rendered in HTML

<g:jasperButton>


The buttons that will submit a jasperForm when clicked. title can be any one of the types of reports that Jasper can output.

6. Controller Action Chaining

Here is the controller code that sets up the data for the Grails-supplied data example, above. As you can see, it then chains to the jasper/index action which handles everything else. 
    def exampleWithData = {
    List people = [
    new ExamplePersonForReport(name: 'Amy', email: 'amy@example.com'),
    new ExamplePersonForReport(name: 'Brad', email: 'brad@example.com'),
    new ExamplePersonForReport(name: 'Charlie', email: 'charlie@example.com')]

    chain(controller:'jasper',action:'index',model:[data:people],params:params)
    }
In the real world, this would be a GORM method call. Something like: List people = ExamplePersonForReport.findAll()

7. Generate report with a service call

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 anything 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 JasperExportFormat enum. You just have to choose one.

Additional attributes are: All you need to do now is to call one of the methods provided in JasperService: Both return a ByteArrayOutputStream with which you can do everything you want.

Full example: 
    class YourClass {
    def jasperService
    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())
    }
    }

8. Known Issues