Tutorial iReports

Overview

In this tutorial, we will cover the use of creating a document in iReports and integrating it with opentaps. Various techniques are covered to assist in creating a report that can be served as PDF, Excel and other formats. Also covered is how to allow users to enter date ranges, product IDs and other dynamic parameters to constrain the report.

Imagine that we want to report the quantity ordered of each product in our store. This is a fairly straightforward report that involves aggregation, grouping and later on filtering by date and product.

Creating A New Report

There is a wizard to help in creating a report, but it hides important details about the anatomy of a report. Therefore, we will be covering report creation from scratch. First, create a new report using File -> New Document. You should get a blank page and some information in the Document Structure window on the left.

Report Bands

By default there are several sections on the page which are faintly labeled as title, pageHeader, columnHeader, detail, columnFooter, lastPageFooter and summary. These are called bands and they have special behavior with regards to how they print the contents on paginated formats such as PDF.

As you might have guessed, bands such as pageHeader, and footer are repeated every page. This is a good place for things that don't change much on a page by page basis, such as the title and page numbers. Usage of title, lastPageFooter and summary are for the title page and lst pages. Their use will not be covered here. For now we can hide the bands we are not going to work with by dragging on the borders and reducing the band height to 0. Alternatively, you can right click on a band and select Band Properties and reduce the size of the bands to 0 by hand.

For the purposes of this tutorial, we will be using only the pageHeader, columnHeader, detail and pageFooter bands. Collapse the other bands to size 0 until the page looks as follows.

Inserting Text

Next we're going to insert some static text for the pageHeader. To insert a static text element, either select it from the dropdown menu or click on the icon. Both are shown below.

Once you click on the desired location for the element, a re-sizable box appears. Move the box to the pageHeader band and resize it to take up the entire band. You'll notice that iReport provides snapping and hints when you're aligned with the edge. We will use these extensively when aligning data so that the output is tidy and suitable for spreadsheet output.

To change the text, you can right click the element and select Properties. Alternatively, you can double click on the element in the Document Structure window to bring up the same properties dialog. It has several tabs and allows you to specify all kinds of details from the font to the alignment details. For now let's just change the text as follows.

After closing this window, our header is now displayed. We can use the toolbar on top to change the alignment, font and other details.

Once you get it vertically and horizontally centered with a nice bold size, it should look something like this,

That is all there is to entering static text.

Creating A Query

Next let's load some data up for our report. We can use the opentaps database directly, which helps us ensure the report is correct. You can create a new data source from Data -> Connections/Data Sources. This is a standard JDBC data source setup that you might be familiar with from other tools. The key points are to select the correct JDBC driver for your database, make sure it is in the iReports classpath (or copy the driver .jar to the iReport lib/ directory), and specify the connection details from your entityengine.xml.

Once the data source is set up, you can create a query using Data -> Report Query. The tutorial query can be as follows,

At the bottom of this window you'll see that the selected fields were detected as String and Double types. If it doesn't understand the query, it will print an error instead. So when the fields are listed, you know you have a good query. This setup has the Automatically Retrieved Fields checked by default, so it will check your query as you type. Uncheck it if this is not desired.

Once the query is accepted, save the file. The query itself will be embedded in the .jrxml file. We will be looking at this later. For now, let us return to the Document Structure window on the left and examine the contents of the Fields category. These are the fields that result from the query.

We can drag a field from the Document Structure onto a band. In this case, we should drag them into the details band. The details band is the location for data output and will flow into the next page if there is more than one page of data.

Now that we've placed them on the details page, let's see how the report looks.

Previewing The Report

From the Build menu, select the JRViewer Preview. This will render the report in an iReport native way. Then we can run the report by selecting the Execute (with active connection) option either from the Build dropdown menu or from the toolbar. Both methods are shown below.

If you have some completed orders and have the tutorial report as described above, it should show your report, otherwise you get a message about no pages created. An example of the output is provided as PDF format, which was itself generated using the iReport Execute action,

• File:TutorialReport1.pdf

If you look at this report, you'll notice that the pageHeader is repeated every page and that the data is listed, but with an extreme amount of padding. We will cover how to format this better in the next section.

Formatting The Report

The excess space in the above PDF is due to the spacing around the field elements in the details band. If the report is to be tabular and published to a spreadsheet or plain text format, it is recommended to align them in a way that is even. The following screenshot shows a better alignment for the tutorial report with better margin control.

• Insert image of better layout

This was achieved by utilizing the zoom dropdown to magnify the details band to better see the alignment and work with the snapping and edge detection hints provided by iReports. It is helpful to use up the entire band when positioning the elements.

Adding Column Headers

Next we can add some headers. This is as simple as adding static text to the columnHeader band.

• Insert image with colored columns

To spice things up, a rectangle with a colored background was added as the first element in this band. You can position elements relative to each other by right clicking on the element name in the Document Struture window.

• Insert image of element moving

Final Report Preview

Once all this is done, we have finished the report layout and formatting. Here are the results in PDF and Excel format.

• Link to PDF
• Link to Excel

Report Concepts

Before we go on, there are several concepts to understand about the reports that will allow you to fully utilize all features of JasperReports and opentaps. In particular, we are going to cover the use of parameters that allow us to specify data to filter and control the appearance of the report, fields which represent our data, and variables that provide dynamic data and control to the report.