Subreport basics

A Subreport is a report that is executed inside of a another report. Subreports are always attached to bands and are executed and printed whenever the band will be printed.

Subreports can only be added as direct or indirect child to any the following root-level band types:

• "report-header"
• "report-footer"
• "group-header"
• "group-footer"
• "itemband"
• "nodata-band"

Pentaho-Reporting has two types of subreports. A banded subreport is attached to the root-level band itself and is always printed below the band to where it is attached. A inline subreport can be added to any band on any position and is printed at the given location.

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 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 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.

Usually a parent report's datasource contains a column with one or many foreign keys. Common cases for such keys are customer-numbers or invoice-numbers. Any information that allows the data-factory to identify a subreport instance during the report-processing can be used as key.

With SQL, MQL or MDX queries, the key almost always is used as a filter-argument in the query.

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 not execute the query or any of the expressions of the sub-report.

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.