Creating a custom template with Jaspersoft Studio

Overview

When the user creates a new report, 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. NOTE: All the files used and generated in this tutorial are attached.

Think the Structure

It's important to have in mind a generic idea of the structure we need to have for the reports generated with the new template. So we need to think where to place images, fields, format and margins of the page and so on. Let's say that we want a report with the title in the center, a logo image on the left of the title, the records one after another and separated by a black line. The page must be in A4 format with a watermark in its center, and also the page number in the bottom-center of every page.

Create the Structure

Essentially a template is nothing more than a standard report where some elements have a precise and fixed name that is used by the Jaspersoft Studio engine to understood where to place every element.

The first thing to do is to create a new report from File -> New -> Jasper Report. We can start with a blank report or also by selecting one of the other templates as starting point. For wath we want to do the Blank A4 is sufficent, so select this template and hit Next.

In the next steps define the folder and the name of your report and as data adapter select One Empty Record since we don't need any data for our purpose. Complete the wizard to get your empty report.

Now in the new report create a group: right click on the report root node in the outline and select Create Group. In the dialog that will popup leave the default name for the group and hit Finish. At the end you should have something like this:

Now we can start to put the elements in the bands but first lets explain how this elements are used by Jaspersoft Studio:

Every band will have the same size in the template and in the report generated from the template. For example, if your template has the Detail with height 100 pixels and the Summary with heigth to 0 pixels then every report generated with this template will have by default a Detail height of 100 pixels and a Summary height of 0 pixels.
The consideration above is valid also for the page format, if your template is for example an A4 without margins even the report generated with this will be A4 without margins.
The content of the bands Summary, Background, Title, Page Header and Page Footer is static. This means that every element that is placed in this bands inside the template will be replicated in every report generated using this template.
In the Column Header band there should be only a Static Text element, and its text content must be "Label". The appearance, font and the other attributes of this label will be used to create every label that is inserted in this band.
In the Group Header band there should be only a Text Field with a textual expression equal to "GroupField" (with the double quotes since it's the expression of a String). As with the Column Header this will be taken as example to generate every field that goes in this band.
In the Detail band there should be only a Text Filed with the text "Field" (remember the double quotes) and as above the appearance of this field will be used as sample.

Now we know everything we need to generate the report, and now we can place the elements to create our layout. Follow this steps:

Place a Static text in the center of the Detail band and an image of your prefecene on the left. Then double click on the band to set it size in a way to fit exactly its content. Work a little on the Static Text font and color to obtain something nice.
Delete the Page Header, Group Footer and the Summary band.
Set the size of the Background band to 800 pixels, place inside it an Image element and choose an image. Make this element reasonably big (lets say width and height over 400 pixels) and place it in the center and in the middle of the Summary band.
In the Page Footer band put a Page Number element, place it in the center of the band and then double click on the band to resize it and avoid waste of space. You can change the graphical attributes to make it looks better.
Place in the Column Footer band a Line element and set it height to 1 pixel and for the width fit the band. As usual double click on the band to resize.
Place in the Column Header a Label element with the text "Label" (without the double quote) and optionally change its appearance, like the text color or element borders.
Place a Text Field in the Group Header and in the Detail. Set the text of the first Text Field to "GroupField" and for the second one use "Field" (both with the double quotes) and optionally change their look.

At the end you should have something like this:

Now switch to the Preview mode and look if the result is what you want (even without data you can see how the layout will look) and if it is allright you can continue with the export operation.

Export the Template

To start the export wizard select click File -> Export as Report Template. In the first dialog you will see all the resources that will be exported. Between these resources you can fine the template and other files used by it, in our example you will see the two used images. In this step you will need also to select the destination folder, where the template and all his resources will be placed.

When you have finished press Next. This following step is really important, here you can define the categories where your template will be visible inside the New Report Wizard. You can select any number of categories, between the embedded one or your own personal category. To define a custom category you need only to type its name inside the text area on the bottom and press the Add button. Then your category will be added to Selected Categories list. To move an element from the Selected Categories list to the Available Categories list and viceversa simply double-click on the element.

At this point you need to select the correct type of report, for example if it is a Tabular Report or a standard one. It is importanto to select the correct type for the report you have designed, so in our exaple select the Standar Report item and you can proceed to the next step.

At this point you can see two different steps:

The first one, and the one that should appear follwoing this tutorial, is a congratulations step. It means that the template you designed is valid for the report type you have selected in the previous step.
The second one is a list of error messages if the template you designed is not valid for the selected type because of some design errors. For example for a template with Tabular type is expected a table in the summary band. If this table is not found it's probably a design error. In this step all the design errors found are listed so you can look to what is wrong and fix it.

In both this cases you can export your report template and all it's resources by clicking finish. But if you are in the second case maybe your template could not work well when it is used to generate the report. Remember that if you edit the report you must save it before to start the export as template wizard. Otherwise any unsaved change will not be taken from the wizard because it read the report file from your disk, not the one in your editor

Generate the Preview Picture

Optionally you can also generate the thumbnail for your Template, in the Preview view hit the export image button and save it in the same directory of the Template and with the same name.

The thumbnail is not mandatory, the new template will be displayed anyway in the Template Selection dialog, with a default image as preview. Anyway it's better to have it, because in this way we could suppose how our report will looks like before to create it.

Add the Templates location to Studio

Now you have to put your custom template for studio. From Jaspersoft Studio hit Window -> Preferences and in the dialog that will appear expand the category Jaspersoft Studio and hit Template Loactions. Here press New and select the folder where you have put the template (MyTemplate), as in the following image

Test the new template

At this point everytime you have to select a Template for a report Jaspersoft Studio will from all the custom folder every JRXML files inside them and try to use these files as report template.

We can try this by creating a new report and in the template selection step of the wizard we will see our new template with the preview image:

Select your template and hit Next. When you have to select the data adapter use the Sample DB and use the query "select * from orders" and hit Next. Add to the report some fields and hit Next, then another time Next without creating any group and complete the wizard. The new report will be something like this:

Switch to preview to see your report:

Since now you have a much significative page for the sample image of the Template you can repeat the procedure to save thumbnail from here, and when you will need to select the location, just overwrite the old image.