Creating a custom template

by Giulio Toffoli

When the user creates a new port, the template chooser proposes several ready to use documents to choose from.

These documents can be taken as they are, or can be used with the wizard to create proper textfields, labels and groups starting from an SQL query or another data source.

In this tutorial we will see how to create a custom template and add it to the template chooser.

All the templates shown in the template chooser are simple JRXML files. We can start with a blank report and add some elements to create the template we have in mind.
Almost all the templates in iReport use A4 as page format.

To change it, click Format → Page format and set the page size you prefer.

When the report is ready, add it to the list of templates from Tools → Options → iReport → Wizard Templates. Here you can add a single jrxml or an entire directory. All the jrxml files present in the directory will be loaded and proposed as templates. If you plan to use images in your template, save the images in the same location as the report, and reference the image in the report just with the image name (i.e. use as image expression "my_logo.png" instead of referencing a complete path). In this way, when the template will be used, iReport will create a copy of the image for the new report.

To create a thumbnail to be used in the templates chooser, preview your report and click the button displaying a chack (see figure 4). This will allows to save an image of the first page of the report.

Save the image in the same directory and with the same name (except for the extension) as your report.
Creating a new file, you will find your new template in the template chooser.

Using the template with the report wizard

The report wizard can leverage a template file by populating it with fields and labels. In particular, when the user choose a set of fields by using the report wizard, a label and a textfield can be created automatically. A similar automatism is available to generate groups when the user choses to group data.

By default the report wizard creates a tabular layout (see figure 6), where in the column header band are placed a set of labels for each field, and the fields are printed all in a single line like in a table.

By setting the report property template.type to columnar, the report generator creates a columnar layout.

Based on the type of the layout the wizards looks for a static text (a label) in the column header band (for tabular layout) or in the detail band (for columnar layout). The label must have as value the string Label.

In the grouping step of the wizard, the user can define up to four groups. The templates can define all of them (the name is not actually important, but the wizard will look first for groups named Group1, Group2, etc...). In the group header band of each group it is possible to place a label with the text Label and a textfield with the expression "Field". If present the first will be replaced with the name of the field used to group data, while the second with the value of that field.

The following layout is a sample of a typical tabular template. Note the label element in the column header and the textfield and detail band.

Executing the report wizard using this template and choosing two groups, it will be possible to create a report like the one below.