Subreport basics

...

Subreports added to the report-header, report-footer or nodata band will be executed once per lifetime of the parent report. If added to the group-header or group-footer, subreports will be executed for every instance of time the group-header and footer are going to be displayed. Subreports added to the itemband will be executed as often as there are rows in the parent report's datasource.

Data-Processing

Whenever reports are executed, the reporting engine calls the data-factory of the report to retrieve the report's data-set. The data-factory receives the query-name and the current values of all declared parameters to allow the parametrization of the data-retrieval. If a subreport is attached to a band that is printed multiple times, the subreport will query the data-factory multiple times, each time with the current values of the master-report.

Master-Reports (= reports without a parent report) receive the values for the parameters that are passed into the data-factory from the declared set of report-parameters and (the now obsolete) report-properties.

Subreports read the parameter-values from the current data-row of the master-report. Subreport only import values for the columns declared as import parameters. Import parameters can be optionally copied with a different name into the subreport (aliased) to avoid column-naming conflicts.

Parametrization strategies

Whenever multiple instances of a subreport are printed on a single parent report, the
data-factory needs additional information to return the correct dataset for the given instance of the subreport. This additional information must be passed to the subreport via parameters.

...

SELECT * FROM INVOICES WHERE INVOICE_NUMBER = ${INVOICE_NUMBER_PARAMETER}

Controlling the visibility of sub-reports

Pentaho-Reporting offers two ways to influence, whether a sub-report will be visible (and thus will be executed) during the report processing.

By setting the "visible" style-key, a sub-report can be hidden or shown while the master-report is processed. Any formula or expression on that style-key will be evaluated in the context of the parent report. Therefore all the parent's fields are available, while at the same time none of the sub-report's fields or the sub-report's status or data are available. If the sub-report is invisible the reporting engine will still execute the query of the sub-report during the data-processing stage, but will not process the sub-report during the layouting stage. During the data-processing stage, style expressions are not evaluated and thus we assume that subreports show.

The attribute "common::sub-report-active" controls the visibility of the sub-report within the data-context of the sub-report. The reporting engine will execute the sub-report's query and also initializes all expressions defined for the sub-report. When the "sub-report-active" expression evaluates to false by either returning a boolean value "false" or the string "false", the reporting engine will stop the processing of the sub-report and continue with the next report state.

The "common::sub-report-active" attribute's static value is not evaluated.