Mail Merge

As part of the relaunch of our TX Text Control online demos , 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.

https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-template-designer

The new Mail Merge Template Assistant 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.

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 &#9584; TX Text Control .NET Server &#9584; JavaScript API &#9584; TXTextControl Object &#9584; loadJsonData Method Loads JSON data which is used to create table and field name menu items in the mailings ribbon tab. " data-tippy-interactive="true" data-tippy-placement="bottom" data-tooltip-width="wide"

>load Json Data , 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.

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.

Understanding and Editing Field Properties

After selecting a supported &#9584; TX Text Control .NET Server &#9584; TXTextControl Namespace &#9584; ApplicationField Class The ApplicationField class supports text field formats of applications such as Microsoft Word. " data-tippy-interactive="true" data-tippy-placement="bottom" data-tooltip-width="wide"

>Application Field 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.

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 &#9584; TX Text Control .NET Server &#9584; TXTextControl Namespace &#9584; SubTextPart Class A SubTextPart object represents a user-defined part of a TX Text Control document. " data-tippy-interactive="true" data-tippy-placement="bottom" data-tooltip-width="wide"

>Sub Text Parts in the TX Text Control document.

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.

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.

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.

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.

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, &#9584; TX Text Control .NET Server &#9584; DocumentServer Namespace &#9584; MailMerge Class &#9584; MergeJsonData Method Merges data given as a JSON string into a document template. " data-tippy-interactive="true" data-tippy-placement="bottom" data-tooltip-width="wide"

>Mail Merge. Merge Json Data 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.

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.

https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-template-designer

Featured Product

AI Development

Text Control MCP Server

Text Control Agent Skills

Server and Web Document Processing

TX Text Control .NET Server

Client-Side Packages - works together for web apps

DS Server

ReportingCloud

Desktop Document Processing

Windows Forms

TX Text Control .NET

TX Spell .NET

WPF

TX Text Control .NET

TX Spell .NET

ActiveX

TX Text Control ActiveX

Featured Projects

SignFabric

AI-Powered Documents

HEDBridge

Core Technologies

​

Latest Posts

​

Support

Getting Started

​

Other Resources

Company

Contact

Newsletter

Legal

Text Control Account

​

​

Mail Merge

Post tagged with Mail Merge in 2026 ​

August 2026

Post tagged with Mail Merge in 2026