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.