Quick start

This page describes how to create a report fast. It only considers 2 type of templates (xlsx and docx), cause doc and xls are almost similar.

Xlsx report

First of all we have to describe report structure: how to load data, how to structurize it and how to render to template.

There are 2 ways - create report object directly from java code or use xml descriptor. Let's consider the way with xml here and direct creation in next example.

Structure

The following xml describes the report structure.

<?xml version="1.0" encoding="UTF-8"?>

<report name="report">
    <templates>
        <template code="DEFAULT" documentName="incomes.xlsx" documentPath="./test/sample/incomes/incomes.xlsx" outputType="xlsx" outputNamePattern="incomes.xlsx"/>
    </templates>
    <rootBand name="Root" orientation="H">
        <bands>
            <band name="Header" orientation="H"/>
            <band name="Incomes" orientation="H">
                <queries>
                    <query name="Data_set_1" type="groovy">
                        <script>
                            return [
                              ['month':'Jan', 'profit':10000], 
                              ['month': 'Feb', 'profit': 12000], 
                              ['month': 'March', 'profit': 15000], 
                              ['month': 'Apr', 'profit': 12000]
                            ]
                        </script>
                    </query>
                </queries>
            </band>
            <band name="Footer" orientation="H"/>
            <band name="Chart" orientation="H"/>
        </bands>
        <queries/>
    </rootBand>
</report>

1. Templates tag describes set of report template, usually report has 1 template and this example as well. You need to set documentName, documentPath, outputType and outputNamePattern.
2. Root band tag describes root of bands hierarchy. Each report should have one root band. Root band contains another bands which can load data.
3. Band tag has 2 attributes: name and orientation (H or V which means Horizontally and Vertically). Also band contains list of queries and list of inner bands.
4. Queries tag contains queries for data loading.
5. Query tag contains 2 attributes: name and type (sql or groovy), and script element which contains script for data loading (obviously).

We have described report structure. Now we need to create a template.

Template

Let's create xlsx template

We have to mark certain parts of template as named regions. Each band described in xml should have matched named region (names should be equal). Region can contain a special placeholders for output fields: ${paramName}. While rendering the document, these placeholders are replaced by certain values from bands. In other words band data is rendered into named region.

Let's create Header named region

Then Incomes named region

Then Footer named region

Finally let's create Chart named region

Now data selected in Incomes band will be rendered into Incomes named region and etc.

Next, we have to create code which will run the report.

        Report report = new DefaultXmlReader()
                .parseXml(readFileToString(new File("./test/sample/incomes/incomes.xml")));

        Reporting reporting = new Reporting();
        reporting.setFormatterFactory(new DefaultFormatterFactory());
        reporting.setLoaderFactory(
                new DefaultLoaderFactory()
                        .setGroovyDataLoader(new GroovyDataLoader(new DefaultScriptingImpl())));

        ReportOutputDocument reportOutputDocument = reporting.runReport(
                new RunParams(report), new FileOutputStream("./result/sample/incomes.xlsx"));

Let's run report and see the results.

You can see the [xml] (/Haulmont/yarg/blob/master/core/test/sample/incomes/incomes.xml), [xlsx] (/Haulmont/yarg/blob/master/core/test/sample/incomes/incomes.xlsx) and java code in samples folder.

Docx report

For next report let's create report directly from java code. The following code uses implementation and builders provided by Yarg, but of course you can use your own implementations of necessary interfaces.

Structure

ReportBuilder reportBuilder = new ReportBuilder();
        ReportTemplateBuilder reportTemplateBuilder = new ReportTemplateBuilder()
                .documentPath("./test/sample/invoice/invoice.docx")
                .documentName("invoice.docx")
                .outputType(ReportOutputType.docx)
                .readFileFromPath();
        reportBuilder.template(reportTemplateBuilder.build());
        BandBuilder bandBuilder = new BandBuilder();
        ReportBand main= bandBuilder.name("Main").query("Main", "return [\n" +
                "                              [\n" +
                "                               'invoiceNumber':99987,\n" +
                "                               'client' : 'Google Inc.',\n" +
                "                               'date' : new Date(),\n" +
                "                               'addLine1': '1600 Amphitheatre Pkwy',\n" +
                "                               'addLine2': 'Mountain View, USA',\n" +
                "                               'addLine3':'CA 94043'\n" +
                "                            ]]", "groovy").build();


        bandBuilder = new BandBuilder();
        ReportBand items = bandBuilder.name("Items").query("Items", "return [\n" +
                "                                ['name':'Solar plasma', 'price' : 15000],\n" +
                "                                ['name':'Flying tables', 'price' : 13000],\n" +
                "                                ['name':'Black T-shirts', 'price' : 12000]\n" +
                "                            ]", "groovy").build();

        reportBuilder.band(main);
        reportBuilder.band(items);

        Report report = reportBuilder.build();

        Reporting reporting = new Reporting();
        reporting.setFormatterFactory(new DefaultFormatterFactory());
        reporting.setLoaderFactory(
                new DefaultLoaderFactory().setGroovyDataLoader(new GroovyDataLoader(new DefaultScriptingImpl())));

        ReportOutputDocument reportOutputDocument = reporting.runReport(
                new RunParams(report), new FileOutputStream("./result/sample/invoice.docx"));

Template