Quick start

This page contains a step-by-step guide on creating two simple reports. It only considers two types of templates (xlsx and docx), because doc and xls are almost similar.

Xlsx report

First of all we need to describe report structure, containing instructions on how to load data, structure it and render to template.

There are two ways - create report object directly from java code or use xml descriptor. Let us 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 one template, as in this example. You need to set documentName, documentPath, outputType and outputNamePattern.
2. Root band tag describes root of bands hierarchy. Each report should have a single root band. Root band contains other bands which can load data.
3. Band tag has two attributes: name and orientation (H or V which means Horizontally and Vertically). A band also contains the list of queries and the list of inner bands.
4. Queries tag contains queries for data loading.
5. Query tag contains two attributes: name and type (sql or groovy), and script element which contains script for data loading.

Now we have described report structure and next step is creating a template.

Template

Let us create xlsx template

We should mark certain parts of template as named regions. Each band described in xml should have a matching 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 us create Header named region

Then Incomes named region

Then Footer named region

Finally let us create Chart named region.

Now the data selected in Incomes band will be rendered into Incomes named region and so on.

Next, we should 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, 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 you can use your own implementations of necessary interfaces if needed.

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" +
                "                               'signature':'<html><body><b><font color='red'>Mr. Yarg</font></b></body></html>'\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);
        reportBuilder.format(new ReportFieldFormatImpl("Main.signature", "${html}"));

        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 one table.

Placeholders which are not contained within 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 the first cell of the table.

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

You can see the docx and java code in samples folder.