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: ${fieldName}. 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 implementations 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

Let's create a docx template, containing placeholders and 1 table.

Placeholders which don't lie into tables linked with bands should have band name before field name: ${BandName.fieldName}

If you want to create a table which will be filled by band data, you should link it with certain band. To do this you need to create ##band=BandName marker (where BandName is certain band's name) in first cell of table the table.

Now let's see the results of running this code.

You can see the [docx] (/Haulmont/yarg/blob/master/core/test/sample/invoice/invoice.docx) and java code in samples folder.