DynamicJasper Tutorial

Author: Alejandro Gomez (alejandro [dot] gomez [at] fdvsolutions [dot] com) Contributors : Dario Garcia (dario [dot] garcia [at] fdvsolutions [dot] com)

You can post any feedback (feature requests, questions, comments, bugs) at our forum.

Changes

Version 0.6 Fixed path px.gif in controller. Added new property to report config to specify whether to use images to align html report or no (isUsingImagesToAlign, by default true) DynamicJasper updated to 3.0.6 Tested against Grails 1.0.5 and 1.1.1

Version 0.5 Minor bug fixes. DynamicJasper updated to 3.0.5 Works against Grails 1.1 RC2

Version 0.4 Domain class configuration is now based on one property. Added multiple columns groups and multiple footer variables on group breaks. Added auto texts.

Version 0.3 The controller has been renamed to DjReportController to avoid potential name collisions in your existing projects. Added named reports.

Your first report

First you need to install the plugin:

grails install-plugin dynamic-jasper

Then in those model classes you want to generate reports you have to add the following property:

[...]
static reportable = [:]
[...]

With this 2 easy steps you can start your application:

grails run-app

and point your browser to: http://localhost:8080/<yourAppName>/djReport/?entity=<yourModelClass>

yourModelClass is the artifact name, so the first letter should be lower case.

The previous URL will return you a PDF listing all the instances of yourModelClass.

The columns shown in the report are all the properties in the class except for id and version.

If you desire to customize which columns appear in the report, or their order, just add this to the reportable property:

static reportable = [columns: ['name', 'author.lastName', 'ISBN', 'dateWritten', 'country', 'score']]

You can also override this setting by passing a parameter in the query string: http://localhost:8080/<yourAppName>/djReport/?entity=book&reportColumns=id,name,author,ISBN,dateWritten

If your entity is related to another entity then the result of toString() will be shown in the report. For instance, in the previous example, the column author will show author.toString()

Besides, you can change the output format adding the parameter reportFormat, for example: http://localhost:8080/<yourAppName>/djReport/?entity=book&reportFormat=CSV

The styles are defined in a file named DynamicJasperConfig. This file is merged with DefaultDynamicJasperConfig (provided with the plugin). If you want to override any style setting defined in the default config file just declare it in DynamicJasperConfig under the conf folder.

Defining your report style

Styles are defined in the file DefaultDynamicJasperConfig which is provided by the plugin and merged with DynamicJasperConfig, which you should place under the conf directory.

In this file you define some properties:

• useFullPageWidth: defines if the report will use the full page width
• page: page size and orientation
• intPattern: the pattern to use with integer numbers
• floatPattern: the pattern to use with floating point numbers
• datePattern: the pattern to use with dates
• titleStyle: the style to use for the report title
• subtitleStyle: the style to use for the report subtitle
• headerStyle: the style to use for the columns header
• detailStyle: the style to use for the data cells
• isUsingImagesToAlign: whether to use px.gif to align html reports, default value is true.

Entity based reports configuration

Inside your existing domain classes you can add the reportable property. This property is a map and inside it you can add the following keys:

• fileName: if defined the report will be send as attachment using this as the filename suffixed by the corresponding extension according to the report type
• title: the title to show in the report. The default value is "entity natural name Report"
• columns: a list containing those columns you want in the report. The default are all except id and version
• patterns: a map defining the pattern for the columns. Columns not included will use the pattern defined for their type.
• columnTitles: a map defining the titles for the columns. Columns not included will use the natural name of the property.
• groupColumns: list of columns to use for grouping data in the report
• groupFooterColumns: list of columns to operate on after every group breaks
• groupOperations: the operations to apply on the previous columns
• dataSource: this is a closure that gets the session and the params passed. Here you hook if you need more complex queries to retrieve data, i.e. based on request parameters or the logged user in the session, or just to integrate with your services or other plugins like Filter Plugin
• autoTexts: list of auto texts, i.e. page number, page x of y, created on xxxx, etc.
• useFullPageWidth: overrides useFullPageWidth defined in DynamicJasperConfig
• page: overrides page defined in DynamicJasperConfig
• intPattern: overrides intPattern defined in DynamicJasperConfig
• floatPattern: overrides floatPattern defined in DynamicJasperConfig
• datePattern: overrides datePattern defined in DynamicJasperConfig
• titleStyle: overrides titleStyle defined in DynamicJasperConfig
• subtitleStyle: overrides subtitleStyle defined in DynamicJasperConfig
• headerStyle: overrides headerStyle defined in DynamicJasperConfig
• detailStyle: overrides detailStyle defined in DynamicJasperConfig
• isUsingImagesToAlign: overrides isUsingImagesToAlign defined in DynamicJasperConfig

import ar.com.fdvs.dj.domain.AutoText
import ar.com.fdvs.dj.core.layout.HorizontalBandAlignment
class Sale {
    static reportable = [
            columns: ['branch.state', 'branch.name', 'product.name', 'quantity', 'amount'],
            columnTitles: ['branch.state': 'State', 'branch.name': 'Branch', 'product.name': 'Product'],
            groupColumns: ['branch.state', 'branch.name'],
            groupFooterColumns: ['quantity', 'amount'],
            groupOperations: ['AVERAGE', 'SUM'],
            autoTexts: [new AutoText(AutoText.AUTOTEXT_PAGE_X_OF_Y, AutoText.POSITION_FOOTER, HorizontalBandAlignment.buildAligment(AutoText.ALIGMENT_CENTER), (byte)0, 200, 200)]
    ]
    Branch branch
    Product product
    int quantity
    float amount
}

Named reports configuration

In the DynamicJasperConfig file you can define other reports giving them a name. The properties you can specify for every report are:

• entity: the domain class on which your report is based
• fileName: if defined the report will be send as attachment using this as the filename suffixed by the corresponding extension according to the report type
• title: the title to show in the report. The default value is "entity natural name Report"
• columns: a list containing those columns you want in the report. The default are all except id and version
• patterns: a map defining the pattern for the columns. Columns not included will use the pattern defined for their type.
• columnTitles: a map defining the titles for the columns. Columns not included will use the natural name of the property.
• groupColumns: list of columns to use for grouping data in the report
• groupFooterColumns: list of columns to operate on after every group breaks
• groupOperations: the operations to apply on the previous columns
• dataSource: this is a closure that gets the session and the params passed. Here you hook if you need more complex queries to retrieve data, i.e. based on request parameters or the logged user in the session, or just to integrate with your services or other plugins like Filter Plugin
• autoTexts: list of auto texts, i.e. page number, page x of y, created on xxxx, etc.
• useFullPageWidth: overrides useFullPageWidth defined in DynamicJasperConfig
• page: overrides page defined in DynamicJasperConfig
• intPattern: overrides intPattern defined in DynamicJasperConfig
• floatPattern: overrides floatPattern defined in DynamicJasperConfig
• datePattern: overrides datePattern defined in DynamicJasperConfig
• titleStyle: overrides titleStyle defined in DynamicJasperConfig
• subtitleStyle: overrides subtitleStyle defined in DynamicJasperConfig
• headerStyle: overrides headerStyle defined in DynamicJasperConfig
• detailStyle: overrides detailStyle defined in DynamicJasperConfig
• isUsingImagesToAlign: overrides isUsingImagesToAlign defined in DynamicJasperConfig

dynamicJasper {
    allSales {
        entity = 'sale'
        title = 'All the sales report'
        columns = ['branch.state', 'branch.name', 'product.name', 'quantity', 'amount']
        patterns = ['quantity': '#0', 'amount': '$ #0.00']
        columnTitles = ['branch.state': 'State', 'branch.name': 'Branch', 'product.name': 'Product']
        autoTexts = [new AutoText(AutoText.AUTOTEXT_PAGE_X_OF_Y, AutoText.POSITION_FOOTER, HorizontalBandAlignment.buildAligment(AutoText.ALIGMENT_CENTER), (byte)0, 200, 200)]
        fileName = 'sales'
        detailStyle {
            textColor = Color.blue
        }
    }
    salesByBranch {
        entity = 'sale'
        title = 'Sales by branch report'
        columns = ['branch.state', 'branch.name', 'product.name', 'quantity', 'amount']
        patterns = ['quantity': '#0', 'amount': '$ #0.00']
        columnTitles = ['branch.state': 'State', 'branch.name': 'Branch', 'product.name': 'Product']
        groupColumns = ['branch.state', 'branch.name']
        groupFooterColumns = ['quantity', 'amount']
        groupOperations = ['AVERAGE', 'SUM']
        autoTexts = [new AutoText(AutoText.AUTOTEXT_PAGE_X_OF_Y, AutoText.POSITION_FOOTER, HorizontalBandAlignment.buildAligment(AutoText.ALIGMENT_CENTER), (byte)0, 200, 200)]
        fileName = 'salesByBranch'
    }
    salesByState {
        entity = 'sale'
        title = 'Sales by state report'
        columns = ['branch.state', 'branch.name', 'product.name', 'quantity', 'amount']
        patterns = ['quantity': '#0', 'amount': '$ #0.00']
        columnTitles = ['branch.state': 'State', 'branch.name': 'Branch', 'product.name': 'Product']
        groupColumns = ['branch.name']
        groupFooterColumns = ['quantity', 'amount']
        groupOperations = ['AVERAGE', 'SUM']
        autoTexts = [new AutoText(AutoText.AUTOTEXT_PAGE_X_OF_Y, AutoText.POSITION_FOOTER, HorizontalBandAlignment.buildAligment(AutoText.ALIGMENT_CENTER), (byte)0, 200, 200)]
        fileName = 'salesByState'
        dataSource = { session, params ->
            Sale.findAll('from Sale as s where s.branch.state = ? order by branch.name', [params.state])
        }
        headerStyle {
            backgroundColor = Color.red
        }
    }
}

To view these reports you need to access this URL:

http://localhost:8080/<yourAppName>/djReport/?report=<your report name>

Considerations

If you provide the list of items to show in the report defining the dataSource and also define groups, your data should be ordered according to the groups definition.