The Groups

Introduction

Groups allow you to organize the records of a report into a more organized structure. A group is defined by an expression containing fields and variables that define the criteria for inclusion in that group. JasperReports evaluates this expression and puts all the elements that meet those criteria into the group. Elements are added or removed from groups as needed when their data is updated.

Creating a New Group

To create a new group, go into the Outline view, right click on the root element (the report you have created) and select Create Group, as shown in the image below:

 

The window to create a new group appears:

From here, enter the group name and select your method for creating the new group:

  • Create group from a report object: this is a simplified way to create a group without creating an expression in the expression editor. With this option, all the fields and variables defined in the selected report object are listed, and you can choose which to use in your group. Selecting an element from this list is equivalent to create a group where the expression include only that element.
  • often the "create group from a report object" option will be sufficent to do what you want, but sometimes a more complex selection is needed. When you provide an expression for the group, JasperReport will evaluate it against each record. When the expression changes in value, a new group is created. Suppose you have the file that contains the amount of money you spent each day, and a report that get the data from this file, into the field Money_Spent. Then define a group with an expression Iike $F{Money_Spent}>150. This expression returns a boolean value, doing this the consecutive records with a value greater than 150 will be grouped toghether. If you have a variable containing that expression already, you can use the simpler method of creating a group from a report object, as described above.

In the previous example, we used the word "consecutive" for the grouped values. Suppose to spent $120 for two consecutive days, $200 the third day and $100 the fourth day. With these values three groups will be created: one with the first two elements, one with the third, and one with the fourth. This happens because the JasperReport:

  • Reads the first record and evaluates the group expression: $120 is lesser than $150, so the result of the expression is "false". But since this is the first evaluation a new group is created.
  • Reads the second value and evaluates the group expression: $120 is still lesser than $150 and the result is still false. Since it is the same value of the previous evaluation this value goes in the first group.
  • Reads the third value and evaluates the group expression: $200 is greater than $150 and the result is true. It is different from the previous evaluation, so a new group for this value is created.
  • Reads the fourth and last value and evaluates the group expression: $100 is not greater than $150 and the result is false. Even this time it is different from the previous evaluation so another group is created.

 This should clarify how the evaluation of the expression affects the creation of a group. Returning to the creation of the group, after we have selected the way how the group is evaluated we can click "Next" or "Finish". If we click next the following window will appear:

Here, you can select if you want the header and the footer of the group in the report. The group will be evaluated even without this two bands, but without any of them there aren't visually changes between a group and another (but the group can still be used for other calculations, see for example the evaluation time, reset type and the other fields in the variable section that uses the group to do some calculations). This because the bands  Header and Footer will be always created, and them are visible in the outline view, but if one of the checkbox is unchecked then the relative band will not be placed into the report (in the outline view a band not visible in the report has its name in lightgray color). If you click finish in the previous screen instead of Next both the bands of the group will be created.

Editing a Group

In the outline view are visible the bands of every group created, if the name of the band has a light gray color means that it isn't in the report. Selecting a group header band from the outline view, or directly form the design view (if the band was placed in the report), will made the group properties appear in the property tab. This is shown in the following image:

In this example there is one group named "ExampleGroup", with the header visible in the report and the footer not. The header is also selected, so in the properties tab are shown all the property of the group. Among them there are:

  • Name: the name of the group, it can be changed at anytime and all the other elements that reference that group will show the updated name;
  • Expression: the expression evaluated to choose when a new group start ;
  • Layout: define how the elements inside the group are disposed;
  • Height: the height of the header band of the group;
  • Split Type: how the band will be splitted, the possible values are:
    • Stretch: the band is allowed to split, but never within its declared height. This means the band splits only when its content stretches.
    • Prevent: prevents the band from splitting on first break attempt, on subsequent pages/columns, the band is allowed to split.
    • Immediate: the band is allowed to split anywhere, as early as needed, but not before at least one element being printed on the current page/column.
  • Min Height to Start a new page: define the minimum height of the band to start a new page;
  • Footer Position: define the positions of the footer band, if it's visible;
  • Start New Page: if checked a new page will be created for every group start;
  • Start New Column: if checked a new columnwill be created for every group start. If there is only one column in the report this is equivalent to "Start New Page";
  • Reprint the header on each page: if the header is visible it will be printed on each page even if they contains elements of the same group;
  • Reset Page Number: when the group change the number of page will be resetted;

This are the properties of the group header band, the group footer hasn't the "Group Properties" section (that contains the attribute name and the expression). The "Group Bands Properties" section are visible but shared with the one from the same group header band. So a change in the footer of this property will be reflected also in the header.

A group can even have more than one header\footer band in the designer, for example to add an header to a group it's sufficent right click  on the header element in the outline view (it dosen't matter if it has black color or lightgray because at the moment there aren't other headers) and select the option "Create Band". A new header band will be created and placed in the designer, and the addition will be reflected even into the outline view in one of these two way:

  1. If before the creation the header of the group in the outline view was light gray then it will become black because now it represents the group and also the header band in the designer of the group. If this band is deleted then the name of the group will be displayed light gray again;
  2. If before the creation the header of the group in the outline view was in black color a new header element will be added to the outline view. This element represent the new band in the designer and the original group. If the band is removed will be removed also the element added in the outline view during the creation, but not the group.

Deleting the Group

On a group we can perform two type of deleting operations: deleting of the footer\header band of the group and deleting of the entire group. These operations are really different and especially the second one could be very dangerous. This two operations can be accessed by right click on the group header or footer band in the outline view, or by right clicking on the corresponding bands in the designer if they are visible. Note that the option to delete the band is visible only if there is a band of that type on the designer. In the following image there is an example:

Deleting the Band

Deleting the band remove it from the report and delete all the elements inside it, anyway the group will be manteined, it will be accessible and it can be used in the expressions. A group without bands is shown, as said before, with the name in light gray color instead of black.

Deleting the Group

Deleting the group will remove all the bands associated with that group and the group itself. If there are more than one band associated to a single group, selecting the option to remove the group, will also remove all the other bands related. The group will no more usable from other elements and because of this it is a dangerous operation. Infact every element that is using the group will keep a reference to it. If the group is deleted while some element use it and then the report is saved, it can't be reopened in the designer, because when the project is loaded are found references to a missing group and this return an error.

Fix the error of a group was deleted while used

If a group is deleted while used is not more possible to load the project into the designer, and only the XML code of the project is visible. There is a way to fix it by removing from the XML all the references of the deleted group. Search all the occurences of the group using the find tool (CTRL+F) with string to search the name of the deleted group. Probably you will find a string composed as follow: AnyString="Group" AnyString="GroupName", where AnyString could be any string, and GroupName is the name of the group we are searching for. To fix the problem we have to remove every occurence of this string. Let's see an example:

In this case the name of the removed group is "ExampleGroup" and the search reported only two occurrences, visible in the image highlighted in red. These two strings are:

  1. evaluationTime="Group" evaluationGroup="ExampleGroup
  2. evaluationTime="Group" evaluationGroup="ExampleGroup"

They match the pattern written before and after deleting this two string (pay attention to not delete something before of after) and saving project file, the report can be opened again in the design tab.

 

Feedback