# Learning Mail Merge Templates from Basic Fields to Advanced Reporting Structures > The new Mail Merge Template Assistant transforms the TX Text Control online demo into an interactive tutorial. It guides developers through basic data binding and merge fields, as well as advanced concepts such as nested blocks, conditional logic, sorting, filtering, images, and barcodes. Since it works directly with native TX Text Control document elements, developers can learn how real mail merge templates are structured by building and exploring them step by step. - **Author:** Bjoern Meyer - **Published:** 2026-08-27 - **Modified:** 2026-08-27 - **Description:** The new Mail Merge Template Assistant transforms the TX Text Control online demo into an interactive tutorial. It guides developers through basic data binding and merge fields, as well as advanced concepts such as nested blocks, conditional logic, sorting, filtering, images, and barcodes. Since it works directly with native TX Text Control document elements, developers can learn how real mail merge templates are structured by building and exploring them step by step. - **13 min read** (2407 words) - **Tags:** - ASP.NET - ASP.NET Core - Mail Merge - Mail Merge Templates - **Web URL:** https://www.textcontrol.com/blog/2026/08/27/learning-mail-merge-templates-from-basic-fields-to-advanced-reporting-structures/ - **LLMs URL:** https://www.textcontrol.com/blog/2026/08/27/learning-mail-merge-templates-from-basic-fields-to-advanced-reporting-structures/llms.txt - **LLMs-Full URL:** https://www.textcontrol.com/blog/2026/08/27/learning-mail-merge-templates-from-basic-fields-to-advanced-reporting-structures/llms-full.txt --- As part of the [relaunch of our TX Text Control online demos](https://www.textcontrol.com/blog/2026/08/21/introducing-the-new-tx-text-control-technical-demos/llms-full.txt), we are changing how we present features and concepts. Rather than simply presenting a working example, the new demos are designed as educational resources. Developers can use these resources to understand how TX Text Control works, explore individual concepts, and gradually transition from basic functionality to more advanced implementation scenarios. > **Try the Mail Merge Template Assistant** > > The Mail Merge Template Assistant is available in the TX Text Control online demos. You can use it to learn how to create data-driven document templates with TX Text Control, from basic fields to advanced reporting structures. > > The new [Mail Merge Template Assistant](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-template-designer) exemplifies this approach. It provides a complete, guided introduction to creating data-driven document templates with TX Text Control. It starts by connecting a JSON data source and inserting individual merge fields. Then, it moves on to nested merge blocks, images, barcodes, conditional fields, sorting, filtering, styling, and template analysis. Rather than hiding these concepts behind an abstract report designer, the demo works directly with the actual TX Text Control document. The fields, merge blocks, tables, and reporting instructions created by the assistant are native TX Text Control objects that remain part of the editable template. Developers who want to understand the structure of TX Text Control MailMerge templates, from basic to more sophisticated hierarchical reporting scenarios, can therefore use this demo as an interactive tutorial. ![Mail Merge Template Assistant](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/demo1.webp "Mail Merge Template Assistant") ### Starting with the Data Every reporting template starts with data. The first step of the assistant is to understand the data structure before adding anything to the document. The demo includes a hierarchical JSON sample with sales orders and related information, including order details, products, product photos, customer addresses and contacts, and embedded image data. Developers can use this sample immediately or upload their own JSON document. Once connected, the data is not simply presented as a flat list of available column names. Instead, the assistant analyzes the hierarchy and displays objects, arrays, root fields, and child tables as an inspectable schema. Arrays are treated as repeating data, while objects represent related records. This makes it much easier to understand how the JSON structure translates into a reporting template structure. At the same time, the JSON is connected to the TX Text Control reporting functionality using loadJsonData, so the data visible in the assistant is the same data model available to the document editor. This first step is particularly useful for learning Mail Merge because it introduces the important concept that the hierarchy of the data source determines which fields and repeating structures are available at a particular position in the document. ![Mail Merge Template Assistant Data](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/assistant_data.webp "Mail Merge Template Assistant Data") #### Inserting Your First Merge Fields The next step introduces one of the most fundamental reporting concepts: Merge fields. The *Fields* tab displays the available fields at the current input position and allows you to insert them directly at the caret. At the document level, this includes root fields and related accessible records. Inside a merge block, the assistant automatically adjusts the available fields according to the current data context. This is particularly useful when working with hierarchical data. You can reference related information using dot notation, such as Production\_Product.Name. This allows you to use values from descendant records without flattening the underlying data structure. The fields inserted by the assistant are real TX Text Control merge fields, created using addMergeField(). This is an important characteristic of the demo. While the assistant helps developers create the document, it does not maintain a separate representation of the template behind the scenes. The same section demonstrates how other types of dynamic content can be included in a reporting template. Image-compatible fields are detected by inspecting the actual JSON values. This allows Base64 image data to be inserted as named image placeholders. Barcode placeholders can also be created with selectable barcode types. Additional field tools demonstrate IF, DATE, and INCLUDETEXT ApplicationFields. This makes the section useful for learning that a Mail Merge template can contain considerably more logic than simple field replacement. ![Mail Merge Template Assistant Merge Fields](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/assistant_mergefields.webp "Mail Merge Template Assistant Merge Fields") #### Understanding and Editing Field Properties After selecting a supported ApplicationField in the document, the assistant changes context and displays that field's properties. Depending on the field type, developers can adjust settings such as the field name, the text displayed before and after the value, the date and number formats, text formatting options, IF comparisons and values, IncludeText documents and bookmarks, and formatting preservation. Changes are applied directly to the selected field, eliminating the need for a separate Apply operation. The demo also provides examples, token hints, and presets for formatting options. ![Mail Merge Template Assistant Merge Fields](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/assistant_mergefields2.webp "Mail Merge Template Assistant Merge Fields") This makes the demo useful for discovering not only how fields are inserted but also for understanding the additional information stored in those fields and how TX Text Control exposes that information through its API. #### From Fields to Repeating Merge Blocks While individual fields are sufficient for values such as customer names, order numbers, and invoice dates, most real-world reports eventually require repeated data. For example, an order might contain multiple line items. Each line item may reference a product. In turn, a product could have related photographs or other associated records. This is where merge blocks become essential. The *Blocks* tab provides a visual way to construct these structures. Developers can select a root table, add nested child tables, and choose the fields that belong to each level. They can also create several hierarchy levels in a single operation. Existing generated blocks can also be selected and redesigned. The result is not an HTML approximation of a report structure. In the demo, the server uses DataSourceManager.InsertMergeBlock together with MergeBlockSettings and the TableRow type to create table structures, merge fields, and SubTextParts in the TX Text Control document. ![Mail Merge Template Assistant Block Designer](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/block-designer.webp "Mail Merge Template Assistant Block Designer") This section is a valuable learning resource because it makes the relationship between the data and document hierarchies visible. Developers can start with a single repeating block and progressively introduce additional levels to see how nested reporting structures are represented. #### Styling Repeating Data Reporting templates are about more than just data structure. The resulting document must also resemble a professionally designed business document. For this reason, the demo shows how to style tables in generated merge blocks. There are several built-in styles available, and you can use a custom style designer to control header colors, nested header colors, body and border colors, text colors, border widths, and cell padding. A live preview allows you to experiment with the table's appearance before applying a style. ![Mail Merge Template Assistant Block Designer](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/style-design.webp "Mail Merge Template Assistant Block Designer") Importantly, styling is independent of the block's definition. You can change a style without rebuilding the block or changing its fields and reporting rules. Custom styles are stored locally in the browser and sent to the server when applied. #### Adding Sorting, Filtering, and Conditional Output Once a document contains repeating data, another important reporting concept becomes relevant. The data does not have to be rendered exactly as it appears in the original data source. The *Rules* tab shows how to shape data directly at the merge-block level. Blocks can be sorted by a selected field in ascending or descending order. Repeating rows can be filtered using relational operators, and nested blocks can be made conditional based on values in their parent row. The demo supports comparisons including equal, not equal, greater than, less than, blank, and not blank. These rules are stored with the actual merge block definition using SortInstruction, FilterInstruction, and BlockMergingCondition values on MergeBlockInfo. For developers learning TX Text Control reporting, this demonstrates an important distinction: Data shaping does not require manual preprocessing of every data source before merging. Relevant reporting instructions can be included in the template itself. ![Mail Merge Template Assistant Filter](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/assistant_filter.webp "Mail Merge Template Assistant Filter") #### Making Complex Templates Easier to Understand As templates grow, understanding their structure can be more challenging than creating individual fields. The *Outline* tab solves this problem by analyzing the document currently loaded in TX Text Control and presenting its reporting structure visually. The tab identifies fields and merge blocks, reconstructs parent-child relationships, determines nesting depth, and separates document-level fields from those belonging to individual merge blocks. Nested structures are displayed using distinct hierarchy levels. Clicking an item takes the user directly to the corresponding element in the document. This makes the *Outline* tab a particularly useful educational tool. Developers can create a block, add a nested level, and insert related fields to immediately inspect how the template's structure has changed. ![Mail Merge Template Assistant Learn](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/template-learn.webp "Mail Merge Template Assistant Learn") #### Seeing Merge Blocks Directly in the Document The demo takes it a step further by visualizing the merge block hierarchy directly next to the document. When the caret is inside a merge block, vertical markers appear on the left side of the page. If blocks are nested, all active levels are shown simultaneously, with deeper levels positioned progressively farther from the document. These markers employ the same hierarchy concept as the Outline, enabling you to immediately identify which parts of the document correspond to which repeating data structures. These markers' positions are calculated from the actual TX Text Control document model without moving the input position. This process resolves the active SubTextParts, determines their start positions and lengths, reads character bounds, and translates those document coordinates into the current editor viewport and zoom level. For developers new to nested MailMerge structures, this visualization makes an otherwise abstract concept considerably easier to understand. ![Mail Merge Template Assistant Learn](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/template-learn2.webp "Mail Merge Template Assistant Learn") #### Previewing the Actual Merge Result At any time, you can merge the template with the currently connected JSON data. The *Preview Merge* command temporarily saves the editable template and sends it, along with the JSON data, to the server. There, MailMerge.MergeJsonData performs the merge. The resulting document is then reloaded into the same editor. The button then changes to *Restore template*, which allows the developer to switch back to the original template and continue editing. Therefore, fields, blocks, rules, and styles are never lost simply because the result has been previewed. This creates a direct learning cycle: Modify the template, preview the result, return to the template, make another change, and compare the outcome. ![Mail Merge Template Assistant Preview](https://s1-www.textcontrol.com/assets/dist/blog/2026/08/27/a/assets/preview.webp "Mail Merge Template Assistant Preview") ### The Document Remains the Template One of the most important concepts demonstrated in the example is its document-first architecture. Rather than creating a separate report definition that later needs to be translated into a document, the assistant uses the document itself as the source of truth. The document itself remains the source of truth. Fields are ApplicationFields. Merge blocks are TX Text Control SubTextParts. Tables are real, Word-compatible document tables. Sorting, filtering, and conditions are stored as part of the merge block information. Rather than relying on a second client-side representation, the assistant repeatedly reads this information back from the actual document. Once the design is finished, the editable template can be downloaded as a mail merge template (.tx). This document retains its fields, merge blocks, hierarchy, styling, and data-shaping rules, so it can be reused as a TX Text Control reporting template. #### Browser and Server Working Together The demo provides a useful example of combining browser-side and server-side TX Text Control functionality. Operations such as browsing the JSON schema, tracking the caret context, inserting fields, editing ApplicationField parameters, displaying the assistant, and visualizing the document structure occur in the browser. Operations requiring the complete document model are handled by ASP.NET Core and the TX Text Control server-side APIs. These include validating block definitions against the JSON schema, generating nested merge-block tables, applying styles in the correct nested document context, storing sorting and filtering instructions, performing the merge, and analyzing the completed template structure. The result is a practical demonstration of how the JavaScript Document Editor APIs, ServerTextControl, DataSourceManager, and MailMerge can collaborate within a single application. ### A Tutorial for TX Text Control MailMerge The Mail Merge Template Assistant is a technical demonstration, but its purpose is not just to show that individual APIs exist. It has been designed to make the underlying concepts visible. Begin with a JSON object and a single merge field. Then, continue by adding repeating records, related and nested data, images, and conditional fields. Next, configure sorting and filtering. Finally, inspect the complete template hierarchy and preview the finished merge. This progression makes the demo an ideal starting point for developers who want to learn TX Text Control MailMerge and understand how to construct increasingly sophisticated templates. This is also the direction in which we are moving with our relaunched online demos in general. While working examples remain important, we also want the demos to explain the concepts behind the functionality. They should help developers understand not only what TX Text Control can do but also how the individual pieces fit together when building real document workflows. The Mail Merge Template Assistant brings this approach to one of TX Text Control's most powerful features: creating reusable, data-aware document templates that grow from a few simple fields into deeply nested, fully formatted reporting structures. > **Try the Mail Merge Template Assistant** > > The Mail Merge Template Assistant is available in the TX Text Control online demos. You can use it to learn how to create data-driven document templates with TX Text Control, from basic fields to advanced reporting structures. > > --- ## About Bjoern Meyer As CEO, Bjoern is the visionary behind our strategic direction and business development, bridging the gap between our customers and engineering teams. His deep passion for coding and web technologies drives the creation of innovative products. If you're at a tech conference, be sure to stop by our booth - you'll most likely meet Bjoern in person. With an advanced graduate degree (Dipl. Inf.) in Computer Science, specializing in AI, from the University of Bremen, Bjoern brings significant expertise to his role. In his spare time, Bjoern enjoys running, paragliding, mountain biking, and playing the piano. - [LinkedIn](https://www.linkedin.com/in/bjoernmeyer/) - [X](https://x.com/txbjoern) - [GitHub](https://github.com/bjoerntx) --- ## Related Posts - [TX Text Control for Blazor: Mail Merge Integration Tutorial](https://www.textcontrol.com/blog/2025/03/25/tx-text-control-for-blazor-mail-merge-integration-tutorial/llms.txt) - [Mail Merge: Skipping Records During the Merge Process in .NET C#](https://www.textcontrol.com/blog/2025/02/10/mail-merge-skipping-records-during-the-merge-process-in-net-c-sharp/llms.txt) - [Mail Merge MS Word DOCX Documents and Convert to PDF in .NET C#](https://www.textcontrol.com/blog/2025/02/07/mail-merge-ms-word-docx-documents-and-convert-to-pdf-in-net-c-sharp/llms.txt) - [Merging Self-Calculating Business Objects with TX Text Control MailMerge in C#](https://www.textcontrol.com/blog/2024/12/27/merging-self-calculating-business-objects-with-tx-text-control-mailmerge-in-csharp/llms.txt) - [Merging Form Fields using the MailMerge Class](https://www.textcontrol.com/blog/2022/02/21/merging-form-fields-using-the-mailmerge-class/llms.txt) - [MailMerge: Rendering Conditional Table Rows](https://www.textcontrol.com/blog/2022/02/17/mailmerge-rendering-conditional-table-rows/llms.txt) - [Merging Barcodes with JSON Data in C#](https://www.textcontrol.com/blog/2022/02/14/merging-barcodes-with-json-data-in-csharp/llms.txt) - [Meet Text Control at NDC Oslo 2026](https://www.textcontrol.com/blog/2026/08/26/meet-text-control-at-ndc-oslo-2026/llms.txt) - [Introducing the New TX Text Control Technical Demos](https://www.textcontrol.com/blog/2026/08/21/introducing-the-new-tx-text-control-technical-demos/llms.txt) - [Building a Browser-Based PDF Workflow for Medical Billing using .NET C#](https://www.textcontrol.com/blog/2026/08/18/building-browser-based-pdf-workflow-medical-billing-dotnet-csharp/llms.txt) - [Introducing HEDBridge: A Modern Migration Path for Legacy HighEdit HED Documents](https://www.textcontrol.com/blog/2026/08/14/introducing-hedbridge-modern-migration-path-legacy-highedit-hed-documents/llms.txt) - [Silicon Valley, Here We Come!](https://www.textcontrol.com/blog/2026/08/10/silicon-valley-here-we-come/llms.txt) - [Against the Trend: Why We Still Believe in Transparent, Perpetual Software Licensing. And Why You Should Too](https://www.textcontrol.com/blog/2026/08/06/against-the-trend-transparent-perpetual-software-licensing/llms.txt) - [Unlock the Full Value of Your TX Text Control License](https://www.textcontrol.com/blog/2026/08/06/unlock-the-full-value-of-your-tx-text-control-license/llms.txt) - [Introducing TX Text Control Web Collaboration Preview for ASP.NET Core](https://www.textcontrol.com/blog/2026/08/05/introducing-tx-text-control-web-collaboration-preview-for-asp-net-core-document-editors/llms.txt) - [Building Long-Term Trust with Digital Signatures and Timestamps in C# .NET](https://www.textcontrol.com/blog/2026/08/04/building-long-term-trust-with-digital-signatures-and-timestamps-in-c-sharp-dot-net/llms.txt) - [AI Natural Language Document Generation with MCP and TX Text Control .NET](https://www.textcontrol.com/blog/2026/07/16/ai-natural-language-document-generation-with-mcp-server-and-tx-text-control-dotnet/llms.txt) - [WeAreDevelopers World Congress Europe 2026 Wrap Up: Record Breaking Days in Berlin](https://www.textcontrol.com/blog/2026/07/13/wearedevelopers-world-congress-europe-2026-wrap-up-record-breaking-days-in-berlin/llms.txt) - [C# Document Generation: A Developer's Guide for .NET](https://www.textcontrol.com/blog/2026/07/08/csharp-document-generation-developer-guide-for-dotnet/llms.txt) - [Validating PDF/UA Documents in .NET C#: A Practical Guide](https://www.textcontrol.com/blog/2026/07/06/validating-pdf-ua-documents-in-dotnet-csharp/llms.txt) - [See Text Control at WeAreDevelopers World Congress Europe 2026 in Berlin](https://www.textcontrol.com/blog/2026/07/06/see-text-control-at-wearedevelopers-world-congress-europe-2026-in-berlin/llms.txt) - [DWX 2026 Wrap-Up: Four Days of Innovation, Conversations, and Enterprise Document Solutions](https://www.textcontrol.com/blog/2026/07/03/dwx-2026-wrap-up-four-days-of-innovation-conversations-and-enterprise-document-solutions/llms.txt) - [Create SignFabric Envelopes from Mail Merge Templates in .NET C#](https://www.textcontrol.com/blog/2026/06/23/create-signfabric-envelopes-from-mail-merge-templates-using-dotnet-csharp/llms.txt) - [Convert SSRS RDL Reports to DOCX and TX Text Control Templates in .NET C#](https://www.textcontrol.com/blog/2026/06/22/convert-ssrs-rdl-reports-to-docx-and-tx-text-control-templates-in-dotnet-csharp/llms.txt) - [Export Document Tables to CSV in .NET C#](https://www.textcontrol.com/blog/2026/06/19/export-document-tables-to-csv-in-dotnet-csharp/llms.txt)