Reporting and Mail Merge have become wide-sweeping terms for automated document, report and label creation. Creating invoices, proposals, generated covering letters or shipping labels was never that easy - simply using word processing skills. This sample illustrates the typical process including creating a reporting template, merging its application fields with data from various data sources and exporting the result of that process.
The source code for this example is contained in the following directories:
To create a reporting template, first a data source must be chosen. That can be done by selecting such a source with the dialog that is opened when clicking the corresponding Select Data Source drop down menu button. In this sample an additional Load Sample Database button is added to the drop down menu. It provides an XML data base that can be used to create a sample reporting template.
After loading a database, the Insert Merge Field and Insert Merge Block drop down menus contain merge fields and merge blocks that can be inserted into the document. These items are related to a master table that can be chosen by clicking one of the Select Master Table drop down menu buttons that represents such a table. The Field Navigation sidebar provides an overview and editing options for all inserted merge fields and merge blocks.
How such a reporting template can be structured in the end, can be seen from one of the sample templates that are provided via the application menu. Each of these templates is related to the sample XML database.
When finishing the design process, the template can be used for the merge process. Usually, creating a template and performing a merge process are two separate operations. In this sample, however, these two processes are combined into one sequence for reasons of comprehension.
The merge process is initiated by clicking the Merge and Export button that opens a dialog to specify some merge settings such as determining the number of records, whether or not the resulting documents should be merged into a single document and what kind of empty merge elements should be removed.
After accepting the set merge settings by clicking the OK button, the merge process begins. When it is finished, the result tab and the first merged record result is displayed. The user can navigate through all created records.
To export the results, the Export Merge Result... button can be clicked. It opens a dialog where the user can determine the prefix text, the destination directory and format of the exported files.
Both creating the template and performing the merge process are handled by an instance of the DataSourceManager that is provided by the RibbonReportingTab'sDataSourceManager property.
The sample database is loaded by using the DataSourceManager.LoadXmlFile method.
private void SampleDatabaseButton_Click(object sender, EventArgs e) {
m_rtRibbonReportingTab.DataSourceManager.LoadXmlFile(m_strFilesDirectory + "sample_db.xml");
}Private Sub SampleDatabaseButton_Click(ByVal sender As Object, ByVal e As EventArgs)
m_rtRibbonReportingTab.DataSourceManager.LoadXmlFile(m_strFilesDirectory & "sample_db.xml")
End SubThe merge process itself is performed by the DataSourceManager.Merge method and returns a list of byte arrays containing one binary TX internal unicode format document for each merged result.
private void MergePreview(byte[] template, int maxPreviews, TextControl textControl, MergeSettings mergeSettings, RibbonReportingTab reportingTab) {
try {
m_lstMergedFiles = reportingTab.DataSourceManager.Merge(template, maxPreviews, textControl, mergeSettings);
} catch (Exception e) {
// Store the exception if thrown.
m_exException = e;
}
}Private Sub MergePreview(ByVal template As Byte(), ByVal maxPreviews As Integer, ByVal textControl As TextControl, ByVal msMergeSettings As MergeSettings, ByVal reportingTab As RibbonReportingTab)
Try
m_lstMergedFiles = reportingTab.DataSourceManager.Merge(template, maxPreviews, textControl, msMergeSettings)
Catch e As Exception
' Store the exception if thrown.
m_exException = e
End Try
End SubAs mentioned before, usually, creating a template and performing a merge process are two separate operations. For this reason, in real-world applications, we don't recommend to use the DataSourceManager.Merge method for the merge process, as shown in this example. Instead, you should always use an instance of the MailMerge class to merge template documents with database content.
For more details, please visit: Howto: Mail Merge