Tutorial iReports

From Opentaps Wiki
Revision as of 01:42, 1 March 2008 by LeonTorres (talk | contribs) (Final Report Preview)
Jump to navigationJump to search


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.

IReport Bands.png

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.

IReport BandSetup.png

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.

IReport NewStaticText.pngIReport StaticTextIcon.png

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.

IReport StaticText.png

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.

IReport EnterStaticText.png

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

IReport TextToolbar.png

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

IReport FinalStaticText.png

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,

IReport Query.png

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.

IReport FieldToBand.png

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.

IReport SelectExecute.pngIReport Build.png

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,

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.

IReport BetterLayoutDetail.png

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.

The field elements were vertically aligned using the same Align Vertical Axis toolbar item that was used to align the pageHeader. Each field element was also given a bottom border using the border selection widget in the same toolbar.

Notice also how there is almost no space left over in the details band. This band represents a row and will get repeated over and over until it spills into the next page.

Adding Column Headers

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

IReport ColumnHeaders.png

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 and moving them up or town relative to each other.

IReport MoveUp.png

Adding Page Numbers

iReport provides us with some standard variables which are listed in the Document Structure. Using the $V{PAGE_NUMBER} variable, we can insert some text to print the page numbers. To do this, drag the PAGE_NUMBER variable over to the pageFooter band and edit its properties. You can change it say Page ${PAGE_NUMBER} like so,

IReport PageNumber.png

Final Report Preview

Once all this is done, we have finished the report layout and formatting. The final report looks like this,

IReport FinalLayout.png

Here are the results in PDF.

And this is a screenshot of what the Excel output looks like.

IReport ExcelSnapshot.png

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.

Report Parameters