1. Quick Start

This chapter shows how to create a simple report and explains the minimal background of the underlying reporting model. When you want a more thorough description of the individual parts, you can use the supplied links to the full description.

System Requirements

• Windows XP Professional, Mac OSX 10.4.6, Linux SUSE, RedHat Linux

• Requires the 1.5.0_06 Java Runtime Environment (JRE)

Downloading the Binary Distribution

The latest distribution for Report Designer can be found on SourceFourge: http://sourceforge.net/project/showfiles.php?group_id=140317&package_id=192362

After downloading the zip file, you are ready to install the software.

Installation

1. To install, extract contents of the zip file into a folder.
2. In the ReportDesigner folder that is created, click the startdesigner.* file that is appropriate for your operating system.

The Report Designer

When you start the Report Designer you are presented with the default workspace divided into five main sections. In the middle of the screen there is a large white area which represents the main working area where the report will be composed.

On the left side, there is a panel called "Palette" where all the report graphical elements are listed. On the right side, you will find two panels: the top panel is called "Structure" and it allows you to see a hierarchical representation of the report.  The bottom panel, "Properties", is where you can adjust the settings of the currently available selection. There is also a panel called "Messages", which shows useful information, hints, warnings and most importantly, errors that apply to your current report definition.

The Data Model

A report usually consist of data supplied by a database in the form of a table and a report definiton which defines how the report should be formatted or printed.

The columns can by identified by an unique column name with a certain datatype. In the above sample, FIRST_NAME is a column identifier and String is the datatype of this column.
For simplicity, there is a database embedded in the Report Designer that contains some useful data to test with.

We are now going to configure the sample dataset. If you have not yet started the Report Designer, please do so now.

Adding the Sample Dataset

In the Structure panel, right-click"Data Sets" and select "Add Pentaho Dataset"

A window is opened where you can configure the query used in the dataset. Select "SampleData" and click the "Query Designer" button.  Make sure your Hypersonic database is running before doing so.

Select "PUBLIC" from the "Choose Schema" dropdown box.  A SQLeonardo window will be lodaded.  From this window, you can select the tables/views to be included in the dataset.  For now, we're selecting the "Products" table.  Clicking on the "Preview" button allows you to quickly visualize the data currently in the table.

Close both windows by pressing "OK."

The dataset is added to the report. The Properties toolwindow shows the available columns and the datatype of each column. You can press the Configure button to change the configuration of a dataset.

The dataset is now setup and installed correctly, we can now go on and define how the report should look like.

The Report Definition

The report definiton is what you compose in the main area of the graphical Report Designer. This definition tells the reporting engine where to place each field on the report. The report definition consist of several sections called bands, such bands may include a report header, a page header, the item band and others.
The following image represents a schematic report as it may appear on screen:

The standard bands available in all reports are marked with different colors in the following image.

• Red: the page header band. This band is usually printed at the top of each page
• Green: the report header band. This band is printed once when the report starts
• Blue: the item band. This band is printed for each row available in the data table
• Turquoise: the report footer band. This band is printed once at the end of the report
• Orange: the page footer band. This band is printed once at the bottom of each page

The same bands are marked with the same color in the Report Designer. Note that the bands have a label on the left side describing what this band is used for.

Tip

If you adjusted a band to be really small, chances are high that you can not read the descriptive label anymore. In this case you can hover with the mouse over the label and a tooltip appears with the text.

Note

There can also be multiple group header and group footer bands.

Creating the Report Definition

To start, we are going to add a static title label to our report which should be printed once on the first page of the report. To accomplish that, we are going to add this label to the report header band. This label does not depend on the data delivered by our sample dataset, hence it's also called a static label.

Select the "Label" report element from the Palette toolwindow by pressing the mousebutton, dragging the label to the report header band and releasing the mouse button.

The label is automatically selected after it was added to the report header band. You can move the label around using the mouse or resize the label by dragging one of the handles.

You can use the Properties toolwindow to adjust the text and font in use. Change the text to "Sales Report" and the font to "Dialog 24 Bold".

If you did not considerably change the size of the label, there will probably appear a warning in the Messages toolwindow telling you that the label is not big enough to show the text. Use the mouse and resize the label until there's enough space for the label to print the contents. Note that the warning message is immediatly removed as soon as the label has a good size.

The report header band should now look roughly as shown in the screenshot below.

Now the report definition is already valid although minimal and can be previewed. Just press the Preview button on the bottom of the report definition area.

After the reporting engine has been started up, you are presented with a preview that looks the same as the final report, but is limited to a certain amount of data rows you can configure in the dataset. The booting process is only done once, subsequent invocations of the preview are almost instantaneous. You can go back to the design view by pressing the Design button.

Now we are going to add textfields that will finally contain data from our sample dataset. Report elements which are dynamically filled with data will have the suffix field.
Drag&drop four Text Fields from the palette to the item band. The report definition should look like the following screenshot:

The Messages toolwindow now shows several warnings about undefined fields. Each textfield should display a column from our sample dataset hence we need to set each textfields "Field Name" property in the Properties toolwindow to match a column from the dataset.

You can now preview the report and customize the report definition by using different fonts, background colors, lines and additional static labels as you like.

The following section will show you how to create the total sum of all sales by introducing functions.

Functions

A function is a custom program that can return a value depending on other values available in the report. A function can use values available in a dataset or use the value returned by another function. This can be used to calculate a total sum, average, minimum, maximum or can be used to hide a label or to hide a rectangle for every second line. Functions can also collect values used to create charts or to format/convert a value from a dataset into another datatype. Functions are very flexible and make almost everything possible.

In the following section, we show you how to calculate the total sum of all sold items.

Adding the Total Sum

Functions can be added through the Structure panel by selecting the "Reporting Functions" node. All available functions are listed in the Properties toolwindow with a short description in a tooltip.

Since we want to calculate the sum of all price items in the report we select the "ItemSumFunction" and press the Add Function to Report button.

First we have to tell the function what field should be used to calculate the sum for and as a second property we must set the name of the function. This is very important, since the value of the sum will be accessible by this name. Note that an error is displayed in the messages toolwindow until you set the name. It won't be possible to preview a report as long as an error is shown in this toolwindow.
We set PRICE as the Field to use to calculate the sum and we use PRICE_SUM as the name of the function. Don't change the values of the Dependency Level and the Group.

We now just have to show this value somewhere on the report. For this purpose we will add a Text Field to the report footer band and set the Field Name property of the Text Field to PRICE_SUM (the functions name).

You can now preview the report and it should look something like the screenshot shown below.

The sum is printed after the last item is printed. As usual you can adjust the report definition as you like.

Report Groups

The structure of the report definition we have so far is perfectly fine, but we might want to merge the items for each customer and calculate the sum for each customer separately. This can by achieved by a concept called grouping. In the following section we show you how to group the data by customer.

Adding the Customer Group

Groups can be added in the Structure toolwindow by selecting the "Groups" node and opening the popup menu. Select "Add Group" from the menu.

A group merges or groups all consecutive items with the same values in a group. Each time a new group starts, the group header band of this group is printed. Whenever a group ends, the group footer band is printed.

When you take a look at the preview of our current report, we would like a group to start for the first item of "Erik Brown". The group should be finished after the last entry of "Erik Brown" and a new group should start for "Hans Meiser" etc.

For this to happen we have to tell the group to apply to the fields FIRST_NAME and LAST_NAME. (FIRST_NAME only won't be sufficient because there is a "Hans Meiser" and a "Hans Müller"). Therefore we set Group Fields of the group as shown in the next screenshot:

In addition it's always a good idea to give the group a meaningful name. In this sample we will use CUSTOMER_GROUP as the name.

When you expand the group in the Structure toolwindow you can see that there is also a group header band and a group footer band available. These bands do not yet appear in the graphical report definition area. To make them appear just select both bands in the Structure toolwindow and turn the Show In Layout GUI property on:

You can now see the the group header band above the item band and the group footer baand below the item band. This is also the direction how they are printed.

To effectively make the group take visually effect, we move the FIRST_NAME and LAST_NAME Text Fields to the group header. To do this you can either delete the existing fields and create new ones  in the group header or you can cut/paste them. You can achieve this by selecting both fields, either in the graphical view or in the Structure toolwindow, by holding the CTRL button on your keyboard and selecting the fields with the mouse.

Now you can right click into the group header band and select paste:

The bands should look like this now:

Adding the total sum for each group is almost identical as before:
•    Select the Report Functions node in the Structure toolwindow
•    Choose the ItemSumFunction and add it to the report
•    Enter PRICE as the Field, CUSTOMER_GROUP as the group and CUSTOMER_PRICE_SUM as the function name
• Add a Text Field to the group footer band, and set the Field Name to CUSTOMER_PRICE_SUM.

That's all! You now have a report that sums the total sales and calculates the total sum for each customer. You can now start to visually enhance the report definition as you like.
After some adjustments, additional labels and a few lines here and there there resulting report looks as follows:

Tip

If you want to achieve almost the same thing with just a few clicks the chapter about the wizard is for you.