Occasionally, people contact our technical support with a common question: how to properly merge several reports into one, especially before exporting. While this is technically straightforward, there are some options to consider. For instance, how to manage different units of measurement or page numbering when merging reports. There is no universal solution, as it depends on the specific goals and objectives of the report creator. To illustrate how to merge multiple reports into one, we have developed several examples for JS and .NET.

---

The MergeDocument() method

Even in small code, it is easy to make mistakes. To simplify the process, we added a MergeDocument() method to the StiReport class for merging reports. In the JavaScript reporting tool, this method is called mergeDocumentAsync().

The method takes a report as input, and its pages will be added to the current report. It also has an overload that accepts a Boolean value as the second parameter, which determines whether the report needs to be pre-built. This allows merging two StiReport objects in a single line: report.MergeDocument(report2, true).

When using this merging method, the following factors are automatically handled:

• The units of measurement of the embedded report are converted to match those of the main report;
• Caching is correctly managed;
• Bookmarks are copied.

Features of working with dashboards

A template file can contain both report pages and a dashboard. However, the dashboard is not a static object and does not have fixed dimensions. Although the dashboard has a Render() method, it is merely a placeholder and cannot be built like a report. The specific dimensions of the dashboard can only be set during export, making it impossible to combine the report and dashboard into a single, ready-made document. The MergeDocument method only adds report pages from another template to the main report. If the template contains only a dashboard, the method will throw an exception. This should be considered when preparing templates for merging.

Practical application of the method

First, it is important to determine which report will be embedded into another, as this affects the report units and page order. Consider the following code example:

report1.MergeDocument(report2);

Pages from report2 will be added to report1 after its pages and converted to report1's units.

Thus, the commands report1.MergeDocument(report2) and report2.MergeDocument(report1) will produce two different documents as output, despite using the same reports in both cases.

Another important aspect concerns the building of reports.
Most often, it is necessary to combine already built reports. For example, reports might be created in different parts of an application as separate pieces, and then they need to be combined into one final report.

Another common approach involves creating reports in one place, but saving them as finished documents on disk or in a database. In other words, reports are first accumulated and then combined into one. In this case, the code might look like this:

var report = StiReport.CreateNewReport();
report.LoadDocument("documents\\Invoice.mdc");
var report2 = StiReport.CreateNewReport();
report2.LoadDocument("documents\\Christmas.mdc");

report.MergeDocument(report2);

report.Show();

But, in some cases, you just need to download, build and combine two report templates in one place. Example code for merging reports:

var report = StiReport.CreateNewReport();
report.Load("Reports\\Invoice.mrt");
var report2 = StiReport.CreateNewReport();
report2.Load("Reports\\Christmas.mrt");

report.Render();
report2.Render();
report.MergeDocument(report2);

report.Show();

To simplify the code, you can use the overload of the MergeDocument() method with two parameters, passing true as the second parameter. This way, the rendering of both reports will be automatically handled within the method. For example, the code for merging reports with the build overload would look like this:

var report = StiReport.CreateNewReport();
report.Load("Reports\\Invoice.mrt");
var report2 = StiReport.CreateNewReport();
report2.Load("Reports\\Christmas.mrt");

report.MergeDocument(report2, true);

report.Show();

If you are merging more than two reports, it is important to maintain consistency and remember that the units of the main report are used. Here is an example of combining three reports:

var report = StiReport.CreateNewReport();
report.Load("Reports\\Invoice.mrt");
var report2 = StiReport.CreateNewReport();
report2.Load("Reports\\Christmas.mrt");
var report3 = StiReport.CreateNewReport();
report3.Load("Reports\\Report3.mrt");

report.MergeDocument(report2, true);
report.MergeDocument(report3, true);

//report is containing a rendered pages of the report, report2 and report3
report.Show();

The JavaScript reporting tool uses an asynchronous merging method called mergeDocumentAsync(). Globally, everything described above applies to this method. The merging of report pages, as well as their rendering, occurs asynchronously. Therefore, if the mergeDocumentAsync() method is used with one argument and the reports need to be built before merging, the renderAsync2() method should be called on them in JavaScript. For example, combining several reports:

var report = StiReport.CreateNewReport();
report.Load("Reports\\Invoice.mrt");
var report2 = StiReport.CreateNewReport();
report2.Load("Reports\\Christmas.mrt");

await report.renderAsync2();
await report2.renderAsync2();
await report.mergeDocumentAsync(report2);

viewer.report = report;

Merging several templates into one report with the use of the mergeDocumentAsync(,) method.

var report = StiReport.CreateNewReport();
report.Load("Reports\\Invoice.mrt");
var report2 = StiReport.CreateNewReport();
report2.Load("Reports\\Christmas.mrt");

await report.mergeDocumentAsync(report2, true);

viewer.report = report;

This makes it much easier to combine reports before viewing, printing, or exporting.