# Create a Template > Design a mail merge template in a Windows Forms editor: the Reporting ribbon tab, sample JSON data for its drop-downs, merge fields in code and a DOCX template. - **Product:** TX Text Control .NET for Windows Forms - **Section:** Documentation - **Kind:** Topic - **Path:** TX Text Control .NET for Windows Forms > Getting Started > Mail Merge > Create a Template - **2394 words** - **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/template/ - **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/template/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/template/llms-full.txt --- A mail merge starts with a template: a document with placeholders, called merge fields, where the data goes. In a Windows Forms application, users design templates in the editor with the **Reporting** ribbon tab, which lists the field names of your data. The steps below prepare the editor for designing templates, insert merge fields with the ribbon and in code, and save an invoice template that the next two tutorials fill with data. ### Prerequisites - The ribbon application from [Create a Ribbon Application with Sidebar Support](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/document-editor/ribbon-sidebar/llms-full.txt), with a `TextControl` named `textControl1`. - The Enterprise or Professional edition, which includes mail merge. See [Editions and Feature Availability](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/editions/llms-full.txt). ### The Sample Data The three mail merge tutorials use the same invoice. Add a file named *invoice.json* to the project and set its **Copy to Output Directory** property to **Copy if newer**: ```json [ { "Company": "Contoso Ltd.", "Name": "Jane Miller", "InvoiceNumber": "INV-1001", "Items": [ { "Description": "Consulting", "Quantity": 2, "Price": 150.00 }, { "Description": "Training", "Quantity": 1, "Price": 480.00 } ] } ] ``` Each property becomes a field name: `Company`, `Name` and `InvoiceNumber` are merge fields of this tutorial, and the `Items` array fills a repeating block in [Add Repeating Merge Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/blocks/llms-full.txt). ### Add the Reporting Tab 1. Select the ribbon by clicking its blue **File** tab title, and click its smart tag. 2. Click **Add a RibbonReportingTab**. The [RibbonReportingTab](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonreportingtab/llms-full.txt) has the groups **Data Source**, **Merge Fields**, **Merge Blocks** and **View**. Like every predefined tab, it works with the `TextControl` connected to its ribbon. ![The Reporting tab of the Windows Forms ribbon with the groups Data Source, Merge Fields, Merge Blocks and View.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/ribbon-reporting-tab.f35a177d.webp) The **Field Navigation** button of the **View** group appears once a sidebar is connected to it, as described below. ### Load the Sample Data Into the Tab The tab offers the field names of a data source that is loaded into its [DataSourceManager](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonreportingtab/datasourcemanager-property/llms-full.txt). The following code in *Form1.cs* loads *invoice.json* when the form opens: ```csharp using System; using System.IO; using System.Windows.Forms; using TXTextControl; using TXTextControl.DocumentServer.Fields; public partial class Form1 : TXTextControl.Windows.Forms.Ribbon.RibbonForm { public Form1() { InitializeComponent(); Load += Form1_Load; } private void Form1_Load(object sender, EventArgs e) { // Fill the drop-downs of the Reporting tab with the names in the sample data ribbonReportingTab1.DataSourceManager.LoadJson(File.ReadAllText("invoice.json")); } } ``` Use the name the designer gave the Reporting tab, shown in the **Properties** window. If your form is not a `RibbonForm`, derive it from `Form` instead. [LoadJson](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-datasources/datasourcemanager/loadjson-method/llms-full.txt) reads a JSON array of objects or a single object and derives the tables and columns from the property names. The sample data only feeds the drop-downs. The actual merge happens later, with any data of the same structure. Users can load a data source themselves as well, with the **Select Data Source** drop-down of the tab, as [Data Source](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/ribbon-dialogs/#data-source) describes. ### Insert Merge Fields With the Ribbon 1. Press **F5** and type the text of the invoice, for example *Invoice* and *Dear*, in the editor. 2. Place the input position where the company name goes. 3. Open the **Insert Merge Field** drop-down in the **Merge Fields** group of the **Reporting** tab and click **Company**. The drop-down lists the columns of the master table of the data source, here the fields of *invoice.json*: ![The Insert Merge Field drop-down of the Reporting tab, here listing the columns of the table Sales_SalesOrderDetail of another data source.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/insert-merge-field-menu.b85ca2d2.webp) 4. Insert **Name** and **InvoiceNumber** in the same way. Each merge field appears as a placeholder in the text. **Field Properties** in the same group opens the options of the selected field, such as text before and after its value. ### Show the Field Navigation Sidebar A template with many fields is easier to check in the field navigator, a sidebar panel that lists the merge blocks and merge fields of the document. The **Field Navigation** button of the **View** group opens it once a [Sidebar](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms/sidebar/llms-full.txt) is connected to the tab. [Show the Field Navigation Sidebar](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/ribbon-dialogs/#show-the-field-navigation-sidebar) connects one in the designer or in code. ### Insert Merge Fields in Code Your code can insert merge fields as well, for example from a menu of your own. Add the following method to `Form1` and call it with a field name: ```csharp // Insert a merge field at the current input position private void InsertMergeField(string name) { MergeField mergeField = new MergeField { Name = name, // matched with the data Text = "«" + name + "»" // shown in the template until it is merged }; mergeField.ApplicationField.HighlightMode = HighlightMode.Activated; mergeField.ApplicationField.DoubledInputPosition = true; textControl1.ApplicationFields.Add(mergeField.ApplicationField); } ``` The code works as follows: - [MergeField](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-fields/mergefield/llms-full.txt) is an MS Word MERGEFIELD field. Its [Name](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-fields/mergefield/name-property/llms-full.txt) is matched with the field names of the data, and its [Text](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-documentserver-fields/mergefield/text-property/llms-full.txt) is shown in the template until the field is merged. - [HighlightMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textfield/highlightmode-property/llms-full.txt) set to `Activated` highlights the field when the input position is in it, and [DoubledInputPosition](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textfield/doubledinputposition-property/llms-full.txt) lets users decide whether text they type at the edge of the field belongs to the field. - [ApplicationFields.Add](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/applicationfieldcollection/add-method/llms-full.txt) inserts the field at the input position. The Windows Forms mail merge sample uses the same method for its **Application Fields** menu: ![The Windows Forms mail merge sample with the Application Fields menu open and the field names name, firstname and company.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/mailmerge-insert-field.670bf6ea.webp) ### Save the Template Save the template as DOCX, for example from a **Save Template** button: ```csharp private void saveTemplateButton_Click(object sender, EventArgs e) { // The merge fields are saved as MS Word MERGEFIELD fields textControl1.Save("invoice.docx", StreamType.WordprocessingML); } ``` The merge fields are saved as MS Word MERGEFIELD fields. When you load the template again, import the fields with `LoadSettings`, as the next tutorial shows. ### Next Steps - [Merge Data into Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/fields/llms-full.txt): fill the template with the invoice data. - [Merge Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/fields/llms-full.txt): field options, formats and special fields in detail. - [Reporting Ribbon and Dialog Boxes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/ribbon-dialogs/llms-full.txt): the Reporting tab and its dialog boxes. - The blog article [Using the Reporting RibbonTab](https://www.textcontrol.com/blog/2018/04/16/using-the-reporting-ribbontab/): the tab with a preview of the merged document. --- ## Nearby - **Previous:** [Mail Merge](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/llms-full.txt) - **Next:** [Merge Data Into Fields](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/mail-merge/fields/llms-full.txt)