# Template Preview > Preview a mail merge template in a Windows Forms editor: DataSourceManager.Merge with MergeSettings, paging through records and restoring the template. - **Product:** TX Text Control .NET for Windows Forms - **Section:** Documentation - **Kind:** Topic - **Path:** TX Text Control .NET for Windows Forms > Mail Merge and Reporting > Template Preview - **3181 words** - **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/template-preview/ - **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/template-preview/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/template-preview/llms-full.txt --- While users design a template, they want to see what it produces: whether the table grows as expected, whether optional lines disappear and whether the numbers are formatted right. A template preview merges the template in the editor with the data loaded into the **Reporting** tab, shows the result in the same `TextControl`, lets users page through a few records and brings the template back afterward. The code below adds such a preview to a Windows Forms application with a few event handlers. The preview needs a data source in the tab, as [Create a Template](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/template/#load-the-sample-data-into-the-tab) loads it. The merge of real data is a separate step with `MailMerge`, described in [Merge Data into Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/fields/llms-full.txt). ### How a Preview Works The **Reporting** tab has no preview button of its own, but its [DataSourceManager](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonreportingtab/datasourcemanager-property/llms-full.txt) can merge a template with the data it holds. Its [Merge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/datasourcemanager/merge-method/llms-full.txt) method takes the template as a byte array in the internal TX Text Control format and returns one document per record, up to a maximum number of records. A preview uses it in three steps: 1. Save the template from the editor into a byte array and keep it. 2. Merge the byte array with the data of the tab and load a merged record into the editor. 3. Load the kept byte array into the editor again when the user returns to the template. The TX Words *Reporting* sample works the same way. Its **Merge and Export** button asks for the number of records and the empty elements to remove in a **Merge Settings** dialog box of the sample: ![TX Text Control Words with the Merge Settings dialog box over an invoice template, with the number of records, Merge all records, Merge into single document and check boxes for removing empty blocks, fields, lines, images and trailing whitespace](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/merge-settings-dialog.adbdfc8d.webp) After the merge, the sample shows a **Results** tab that pages through the merged records: ![The merged invoice in TX Text Control Words with the Results tab and its buttons Exit, First Record, Previous Record, Next Record, Last Record and Export Merge Result](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/merge-results-tab.9a6a6d39.webp) Its **Export Merge Result** button saves the merged records as files, with a file prefix, a directory and a format chosen in a dialog box: ![The Export Merge Result dialog box of TX Text Control Words over a merged invoice, with the file prefix invoice, the directory C:, the format Adobe PDF (*.pdf) and the option Open directory after export.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/export-merge-result-dialog.b5db2f6e.webp) Its source code is in *%USERPROFILE%\\Documents\\TX Text Control 34.0.NET for Windows Forms\\CSharp\\TX Words\\Reporting*. ### Add a Preview The following code adds a preview to the ribbon application of [Create a Template](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/template/llms-full.txt). Add a `CheckBox` named `previewCheckBox` with the text *Preview* and two buttons, `previousRecordButton` and `nextRecordButton`, to the form, and create their event handlers in the designer: `CheckedChanged` for the check box and `Click` for the buttons. Then add the following members to *Form1.cs*: ```csharp using System; using System.Collections.Generic; using System.Windows.Forms; using TXTextControl; using TXTextControl.DocumentServer.DataSources; ``` ```csharp private byte[] template; private IList previews; private int previewIndex; private void previewCheckBox_CheckedChanged(object sender, EventArgs e) { if (previewCheckBox.Checked) { ShowPreview(); } else { ShowTemplate(); } } private void ShowPreview() { DataSourceManager dataSourceManager = ribbonReportingTab1.DataSourceManager; if (!dataSourceManager.IsMergingPossible) { MessageBox.Show(this, "Load a data source into the Reporting tab first."); previewCheckBox.Checked = false; return; } // Keep the template to restore it later textControl1.Save(out template, BinaryStreamType.InternalUnicodeFormat); MergeSettings mergeSettings = new MergeSettings { RemoveEmptyFields = true, RemoveEmptyLines = false, RemoveEmptyImages = false }; // Merge the first five records, one document each previews = dataSourceManager.Merge(template, 5, textControl1, mergeSettings); previewIndex = 0; ShowRecord(); textControl1.EditMode = EditMode.ReadAndSelect; } private void ShowRecord() { textControl1.Load(previews[previewIndex], BinaryStreamType.InternalUnicodeFormat); Text = $"Preview: record {previewIndex + 1} of {previews.Count}"; } private void nextRecordButton_Click(object sender, EventArgs e) { if (previews != null && previewIndex < previews.Count - 1) { previewIndex++; ShowRecord(); } } private void previousRecordButton_Click(object sender, EventArgs e) { if (previews != null && previewIndex > 0) { previewIndex--; ShowRecord(); } } private void ShowTemplate() { if (template == null) { return; } // Bring back the template and make it editable again textControl1.Load(template, BinaryStreamType.InternalUnicodeFormat); textControl1.EditMode = EditMode.Edit; template = null; previews = null; Text = "Template"; } ``` The code works as follows: - [IsMergingPossible](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/datasourcemanager/ismergingpossible-property/llms-full.txt) is `true` when all requirements for `Merge` are met, so the preview starts only with data in the tab. - `textControl1.Save` with `BinaryStreamType.InternalUnicodeFormat` writes the template, with its fields and merge blocks, into the byte array `template`. - `Merge` with the maximum of 5 merges at most five records and returns a list with one document per record. The `TextControl` is passed for licensing. - [MergeSettings](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/llms-full.txt) decide what the merge removes. [RemoveEmptyFields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/removeemptyfields-property/llms-full.txt) is `true` by default. [RemoveEmptyLines](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/removeemptylines-property/llms-full.txt) and [RemoveEmptyImages](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/removeemptyimages-property/llms-full.txt) are `true` by default here and `false` by default in `MailMerge`, so the code sets both to `false`. Use the same values as the `MailMerge` of your real merge, so the preview matches the result. - [EditMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/editmode-property/llms-full.txt) set to `ReadAndSelect` protects the preview from changes, because edits would be lost when the template is loaded again. - The **Previous** and **Next** buttons load another document of the list, and the title of the form shows which record is visible. Press **F5**, load the data into the Reporting tab and check **Preview**. The editor shows the first merged record, and unchecking **Preview** brings the template back. ### Merge Settings The properties of `MergeSettings` correspond to the check boxes of the TX Words **Merge Settings** dialog box: | Property | Default | What it does | |---|---|---| | [AsSingleDocument](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/assingledocument-property/llms-full.txt) | `false` | Combines the records into one document, each starting on a new page after a section break | | [RemoveEmptyBlocks](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/removeemptyblocks-property/llms-full.txt) | `true` | Removes the content of merge blocks without data | | [RemoveEmptyFields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/removeemptyfields-property/llms-full.txt) | `true` | Removes fields without data | | [RemoveEmptyImages](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/removeemptyimages-property/llms-full.txt) | `true` | Removes images without merge data | | [RemoveEmptyLines](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/removeemptylines-property/llms-full.txt) | `true` | Removes lines that are empty after the merge | | [RemoveTrailingWhitespace](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/mergesettings/removetrailingwhitespace-property/llms-full.txt) | `true` | Removes trailing whitespace | With `AsSingleDocument` set to `true`, the list returned by `Merge` holds one document with all records, which users can scroll through instead of paging. Numbers and dates are formatted with the culture in [MergeCulture](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/datasourcemanager/mergeculture-property/llms-full.txt) of the `DataSourceManager`, the culture of the current thread by default. ### Find Fields Without Data in the Preview The `DataSourceManager` raises its own [FieldMerged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/datasourcemanager/fieldmerged-event/llms-full.txt) and [DataRowMerged](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/datasourcemanager/datarowmerged-event/llms-full.txt) events during `Merge`, with the same arguments as the events of `MailMerge`. A `FieldMerged` handler can collect the fields whose `Merged` property is `false`, and the preview can list them next to the result, as the template test in [Template Design](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/template-design/#test-a-template) does with `MailMerge`. ### Preview With MailMerge `DataSourceManager.Merge` merges the data the designer loaded. When the preview has to use the same data and settings as your application's real merge, merge with `MailMerge` in a `ServerTextControl` instead and load the result into the editor, as [Merge Data into Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/fields/#merge-the-data) does. The description of the TX Words sample recommends `MailMerge` for the merge of real documents and uses `Merge` of the `DataSourceManager` for its preview. The blog article [Using the Reporting RibbonTab](https://www.textcontrol.com/blog/2018/04/16/using-the-reporting-ribbontab/) shows the shortest form of the `DataSourceManager` preview. ### Next Steps - [Reporting Ribbon and Dialog Boxes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/ribbon-dialogs/llms-full.txt): the tab whose data the preview uses. - [Template Design](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/template-design/llms-full.txt): test templates before they go live. - [Merge Events](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/events/llms-full.txt): follow a merge with events. --- ## Nearby - **Previous:** [Reporting Ribbon and Dialog Boxes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/ribbon-dialogs/llms-full.txt) - **Next:** [Merge Events](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/events/llms-full.txt)