Batch Report Mode

Batch report mode enables running multiple reports into a single output. The member reports are joined in a specified order and run one after another as if they were one report: the result is a single print job, a single PDF file, or a single preview document. Each member report keeps its own report definition, so the reports may use completely different data sources, sections, and layouts.

Typical use cases:

  • Printing documents that belong together in one step, for example an invoice, a delivery note, and a cover letter.

  • Creating one PDF file from several independent reports.

  • Combining a summary report with one or more detailed reports.

How batch mode works

Batch mode is enabled as soon as at least one report is added to the batch of an NCReport object (isBatchMode() returns true in this case). When the report is run, the engine processes the reports of the batch one by one, in the order they were added, using the same output object. The output is initialized when the first report starts and finalized when the last report ends; the reports in between are rendered into the same output.

  • By default, every report starts on a new page. Call setBatchModePageBreakBetweenPages(false) to disable the page break between the reports.

  • Page numbering restarts for every member report: the pageno system variable shows the page number within the current report.

  • The gpageno system variable returns the global page number, counted across all the reports of the batch.

  • The reportno system variable returns the number of the current report in the batch (starting from 1), and the reportcount system variable returns the total number of reports in the batch.

When the QPrinter-based PDF output (NCReportPdfOutput) is used, batch mode is supported only if all reports have the same page settings; otherwise the result is incorrect.

Batch mode API

The batch-related functions of the NCReport class are the following:

addReportToBatch( const QString& reportXML )

Adds a report to the batch. The string is either a report definition XML string or a report file name. A string that ends with .xml or .ncr is treated as a file name.

addReportToBatch( const QString& reportXML, const QHash<QString,QVariant>& parameters )

Adds a report to the batch together with the parameters that are added to the report when it runs.

addReportToBatch( NCReport* report )

Adds an already configured NCReport object to the batch. When this report runs, its report source, parameters, item models, string lists, and data sources are used.

setReportBatch( const QStringList& )

Sets the whole batch at once from a list of report file names or XML strings.

clearBatch()

Removes all reports from the batch.

isBatchMode()

Returns true if the batch contains at least one report.

setBatchModePageBreakBetweenPages( bool )

Specifies whether a page break is inserted between the reports. The default is true.

batchReportRunning( int reportNumber )

Signal emitted before each report of a string-based (file name or XML) batch starts.

Don’t mix the two kinds of batches. If any NCReport object has been added to the batch with addReportToBatch( NCReport* ), only the object batch is run, and the reports added as file names or XML strings are ignored.

Example

The following example runs three report files into one PDF file. The second report gets its own parameter. For further details, see the Batch report mode section in the "Using the NCReport API" chapter.

NCReport *report = new NCReport();

report->clearBatch();
report->addReportToBatch( "/home/anywhere/report1.xml" );

QHash<QString,QVariant> params;
params.insert( "category", 2 );
report->addReportToBatch( "/home/anywhere/report2.xml", params );

report->addReportToBatch( "/home/anywhere/report3.xml" );

report->runReportToPdfWriter( "batch.pdf" );

if ( report->hasError() )
    qWarning() << report->lastErrorMsg();

delete report;

Running batch reports in the Designer

The Run report dialog of the Designer has a Batch mode panel that lists the report files of all open documents. If Run reports in batch mode is checked, all of the listed reports are run in batch mode into the selected output. The option is available only when more than one report document is open. Since the reports are run from their files, save your changes before running the batch.

The batch_demo_report1.xml, batch_demo_report2.xml, and batch_demo_report3.xml demo reports in the reports directory of the NCReport package are designed for trying out batch mode.