2 Tutorial

Reports Tutorial

This tutorial shows how to create a report using the plugin.

The sample application that uses the plugin is under

test/projects/tutorial-reports

The goal of the tutorial is to generate a simple report with database records, in this case will be a list of users.

Create grails-app

grails create-app tutorial-reports

Add the plugin to BuildConfig.groovy to the plugins list

The plugin is not in the grails repositories yet, so a grails maven-install is needed. (See @instalation)

plugins {
        runtime ":hibernate:$grailsVersion"
        runtime ":jquery:1.8.3"
        runtime ":resources:1.2"
        build ":tomcat:$grailsVersion"
        runtime ":database-migration:1.3.2"
        compile ':cache:1.0.1'
        compile("org.grails.plugins:reports:0.3.2")
    }

Config.groovy

Add the url of your server:

grails.serverURL = "http://localhost:8080/${appName}"

The grails.serverURL will later be used to go to the plugin reports user interface.

BootStrap.groovy

The next step is to add the report processing to the start of the application, so when we restart the application, the new reports created will be copied to the database.

When the application is started the plugin will search for the web-app/reports/ folder.

import org.grails.plugins.reports.ReportUtils
class BootStrap {
    def grailsApplication
    def init = { servletContext ->
        initReports(servletContext)
    }
    private void initReports(def servletContext) {
        log.debug ("init reports")
        def reports = [
            [name: "usersReport", title: "List of Users"]
        ]
        ReportUtils.updateReportsFromResources(servletContext, reports)
    }

    def destroy = {
        // nothing to destroy
    }
}

Sample domain

Since this tutorial's goal is to create a report with a list of users, we have to create the User domain with the command:

grails create-domain-class User

Now add fields to the domain (just a sample):

package tutorial.reports
class User {
    static constraints = {
        name nullable: false
    }
    String name
    String address
    String city
}

Add test data (too BootStrap.groovy)

def init = { servletContext ->
    …
    initUsers()
}
private void initUsers() {
    log.debug("creating users")
    User u1 = new User(name: "Hugo Monteiro", address: "Street 33", city: "Sintra")
    User u2 = new User(name: "Bruno Félix", address: "Street 6", city: "Almada")
    User u3 = new User(name: "Nuno Luís", address: "Street 1", city: "Porto")
    u1.save()
    u2.save()
    u3.save()
}

Create the report files

Since the name of the report is userReport the name of the template will be usersReport.groovy and the binding will be usersReport.groovy. You can create an extra file called userReport.params.groovy - this file passes arguments to the binding: id of a user for instance.

The binding is a simple way to inject values to your report, just to see if the data is there and in the right place.

Edit usersReport.groovy to get a list of users and pass it to the report:

import tutorial.reports.User
List<User> users = User.list()
[users: users]

Edit usersReport.gsp to show the list of users. This html will be converted to PDF. You can add external css or image files, but don't forget to add the relative: true parameter.

…
<h1>List of users</h1>
<table>
    <g:each in="${users}" var="user">
        <tr>
            <td>${user.name}</td>
            <td>${user.address}</td>
            <td>${user.city}</td>
        </tr>
    </g:each>
</table>

Run the application

grails run-app

The report created is available at http://localhost:8080/tutorial-reports/reports/

Create a controller

First, create a controller named Index

grails create-controller Index

Now in the download() method return the file to the user

…
    def reportService // from the reports plugin
    def index() {
        Report reportInstance = Report.get("usersReport")
        def binding = reportInstance.evalBinding() // the binding and params file will be used
        reportService.renderReport(reportInstance, binding, response, null, false)
    }

Run the application to download the new report

grails run-app

Access the url http://localhost:8080/tutorial-reports/index/download to download the report you just created.

Editing the report at Runtime

The reports can be changed at http://localhost:8080/tutorial-reports/reports in runtime. When you click save the template/binding/params are saved in the database, so it is better to save those files locally in the web-app/reports folder.