Subreports
A report that is inserted into a report is referred to as the subreport. Subreports are inserted and managed just like a component in a primary report, but a subreport itself is created and managed just like a primary report. You can specify relationships between the primary report and the subreport as well as have JReport pass values to the primary report or the subreport. A primary report can have more than one subreport.
A subreport can be inserted in the report areas listed in Component placement.
To insert a subreport into a report:
- Open the primary report.
- Position the mouse pointer at the destination where you want to insert the subreport, then click Insert > Subreport on the menu bar, or the Insert Subreport button
on the Insert toolbar. Then,
- If the destination is the report body or a tabular cell, the Subreport dialog appears.
- If the destination is a banded panel, click the mouse button in the panel to open the Subreport dialog.
- In the Subreport dialog, click the Browse button to select the report which contains the report tab you want to use as the subreport. This report must belong to the same catalog as the primary report.
- Select the required report tab as the subreport from the Report Tab drop-down list, where the names of all the report tabs in the specified report are displayed.
- In the Field tab, click the Add button beside the Component in Report Tab box. In the Choose Component dialog, add the components in the subreport you want to be interlinked with the primary report with conditions. If the required components use different datasets, you need to add them respectively, however, as long as the components are based on the same dataset, you can add them all at a time.
- Select a component from the Component in Report Tab box and set up links between the primary report and the component as required. Repeat this to define the link condition between other components in the subreport and the primary report.
- If the subreport has parameters and you do not want to enter values for them at runtime, click the Parameter tab to assign values to the parameters.
- If you want the subreport to return certain values to the primary report, click the Return Value tab and specify the settings according to your requirements.
- Click OK to insert the subreport.
When a subreport is inserted into a report, you can further format the subreport settings if required. To do this, right-click the subreport and click Format Subreport on the shortcut menu. In the Subreport dialog, edit the settings according to your requirements. Moreover, when a report has been inserted into another report as a subreport, if you later modify this report, it is suggested that you go to the primary report and use the Format Subreport command to save the subreport settings again.
You can also customize the appearance and behavior of a subreport by setting properties in the Report Inspector, which can be saved as a CSS style for future use (for details, see Creating a CSS style).
Creating sublinks
A sublink is a way to connect the primary report and the subreport. When you define a sublink, JReport will match the records with equal relationships within the subreport and the primary report. You can apply one or more links to make the subreport and the primary report interlinked.
The following example explains the use of sublinks in detail.
Assume that you have two reports in the same catalog: one contains a customer report tab which has a banded object inside and displays information of customer ID, country, city and phone, and the other contains an order report tab which contains a crosstab showing information of customer ID, product name and quantity. Now, you want to insert the order report tab as subreport into the customer report tab, and set up a link between them, so that when the end users views the customer report tab, a subreport will be built for each customer based on the order report tab, showing order records for only the specified customer.
To achieve this, take the following steps:
- Open the report that contains the customer report tab in JReport Designer.
- Select the detail panel of the banded object and click the Insert Subreport button on the Insert toolbar. A box is then attached to the mouse pointer to indicate it is ready to place the subreport.
- Click in the panel and the Subreport dialog is displayed.
- Click the Browse button to select the report that contains the order report tab as the subreport.
- In the Field tab, click the Add button.
- Check CTCrossTab in the Choose Component dialog, then click OK. The component is listed in the Component in Report Tab box.
- Add the Customers_CustomerID field in the customer report tab to the Field box, a link is then automatically set up as follows:
| Fields(Primary) |
OP |
Fields(Subreport) |
| Customers_Customer ID |
= |
CUSTOMERS_CUSTOMERS ID |
- Click OK to apply the settings.
- Preview the customer report tab. You will find that a crosstab is generated for each customer based on the customer ID.
Setting up parameter links
If a subreport contains parameters, the values must be supplied at runtime. You can map the subreport parameters to DBFields, formulas or parameters which are contained in the dataset of the component where the subreport is inserted in the primary report, and are of the same data types as the subreport parameters.
The following example shows how to set up parameter links between a primary report and a subreport.
Assume that you have two reports in the same catalog: Report A (with Report Tab A in it) and Report B (with Report Tab B in it). Report Tab B has a parameter PToday (Date type). Then, you insert Report Tab B as subreport into Report Tab A. When you view Report Tab A, you will be prompted to enter value for its subreport parameter PToday. However, you do not want to enter the value each time you run Report Tab A and instead want to give it a fixed value. To achieve this, follow the steps below:
- Right-click the inserted subreport in Report Tab A and select Format Subreport.
- In the Subreport dialog, click the Parameters tab (this tab is disabled if the subreport does not contain any parameters).
- In the Parameters column, you can see PToday is listed there and a same parameter is assigned to it by default in the Value column.
- Click the value drop-down list where all the DBFields, formulas and parameters of Data type in the dataset of Report Tab A are listed. Here, we select MYTODAY which is a predefined formula and returns a value ToDate(2006,01,01).
- Click OK to apply the settings.
- View Report Tab A, and no parameter dialog will be displayed prompting you to enter the value since the formula value is passed to PToday.
Returning values to the primary report
You can make values of the subreport return to the primary report. To do this:
- Right-click the subreport and select Format Subreport from the shortcut menu.
- In the Subreport dialog, click the Return Value tab.
- In the Component in Report Tab box, check the component in the subreport, the fields of which you want to use to return value to parameters of the primary report, then the Field in Subreport box will list all available fields used by the selected component.
- Select the field that you want to assign to a parameter in the primary report, click
, and a parameter in the primary report of the same data type will be displayed in the Parameters column of the Return Value box. If the automatically assigned parameter is not what you need, select the required one from the parameter drop-down list.
- If required, select another component in the Component in Report Tab box and set more mapping fields for parameters in the primary report.
- When done, click OK to apply the settings.
Notes:
- When inserting subreports, you need to avoid link loop. For example, if you have inserted report B into report A as its subreport, then you cannot insert report A into report B as its subreport again. It is the same case when creating sublinks, for example, if you set the links between the primary report A and subreport B (report A -> report B), you cannot set the link back to report A (report A -> report B -> report A).
- If a subreport parameter is mapped to another parameter, you will still be prompted to input the value at runtime. In the Enter Parameter Values dialog, the parameter name you see is that of the mapping parameter.
- If a subreport parameter is mapped to a formula, the parameter will obtain value automatically from the mapping formula.
- When passing values between the subreport and the primary report, you should pay attention to avoiding parameter loop, which may occur as this case: parameter A of the primary report is assigned to parameter B of the subreport in the Parameters tab, while in the Return Value tab, B is assigned to A. In this case, the values of A and B will depend on the default values and the position relationship between the two parameters.
- When you insert the subreport, you should insert it before the parameter, or the parameter will not be the expected value.
- To use the return value parameter in a formula, you need to add PageNumber in the first line in the formula. For more information, see Formula levels.
For example, all the formulas which referenced the return value parameter should be like:
pagenumber;
... ... ...
... ... ...
- If the subreport will cross page, the result of the formula may not be the expected value because the return value will only be calculated when finishing laying out the subreport.
- You can use the option "Show real view of subreport" in the General category of the Options dialog (File > Options > General) to specify whether or not to show the detailed subreport structure in the primary report in design mode. However,
- For subreport with multiple pages, only the report body in the first page will be shown in the primary report.
- For cascading subreport, only the first layer of the subreport will be shown in the primary report.
See an example: The SampleComponents catalog, included with JReport Designer, contains reports that have examples of how each component type could be used in a report. For the subreport examples, open <install_root>\Demo\Reports\SampleComponents\Subreport_*.cls.