# Template Assistant

> Try the Mail Merge Template Assistant online demo: steps from JSON data to outline, how browser and server share the work, and the APIs it is built on.

- **Product:** TX Text Control .NET Server
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET Server > Mail Merge and Reporting > Template Assistant
- **1823 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/template-assistant/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/template-assistant/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/template-assistant/llms-full.txt

---

Learning how merge fields, merge blocks and data-shaping rules fit together is easier with a live template in front of you. The Mail Merge Template Assistant is an online demo in which you design a template in the Document Editor step by step, from connecting JSON data to nested blocks with sorting and filter rules, and every step creates real TX Text Control fields and blocks.

The Template Assistant is a demo application, not a component of TX Text Control .NET Server. It's built on the Document Editor and `MailMerge`, so your application can do what it does with the same APIs.

### What the Template Assistant Is

The [Mail Merge Template Assistant](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-template-designer) is one of the technical demos of Text Control, which run on ASP.NET Core with .NET 10 and the Core version of TX Text Control .NET Server. Like the other demos, it has three areas: **Try it** to use the assistant, **Learn** to read how it works and **Code** to see the code behind it.

In the demo, the Document Editor has an additional **Template Assistant** group in its **Reporting** ribbon tab. The group opens a panel next to the document, which overlaps the editor instead of resizing it, so the document keeps its layout. The blog article [Learning Mail Merge Templates from Basic Fields to Advanced Reporting Structures](https://www.textcontrol.com/blog/2026/08/27/learning-mail-merge-templates-from-basic-fields-to-advanced-reporting-structures/) introduces the assistant.

![Document Editor with the Template Assistant group in the Reporting ribbon tab and the assistant panel at the right, showing the Fields step with the fields available at the input position](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-server/template-assistant-editor.0c9a75aa.webp)

### The Steps of the Assistant

| Step | What you do | Documented in |
|---|---|---|
| 1 Data | Load a JSON file or use the sample data of sales orders with products, customers and images. The assistant shows the structure of the data, and the same JSON fills the **Reporting** tab of the editor | [Data Sources](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/data-sources/llms-full.txt) |
| 2 Fields | Insert the fields that are available at the input position: fields of the document level outside blocks and fields of the current record inside a block. Values that contain image data become image placeholders, and barcodes can be inserted for values. `IF`, `DATE` and `INCLUDETEXT` fields are available as well | [Merge Fields](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/fields/llms-full.txt), [Images](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/images/llms-full.txt), [Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/barcodes/llms-full.txt) |
| 3 Blocks | Design a merge block from a collection of the data, with nested child collections and the fields of each level, and style its table | [Merge Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/blocks/llms-full.txt), [Nested Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/nested-blocks/llms-full.txt) |
| 4 Rules | Sort the rows of a block, filter them and make a nested block depend on its parent record | [Sorting and Filtering](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/sorting-filtering/llms-full.txt) |
| 5 Outline | See the fields and blocks of the document with their nesting and levels and jump to an element | [Template Design](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/template-design/#test-a-template) |

In the Blocks step, a dialog designs a merge block: you choose the outer collection and its nested child collections, check the fields of each level and pick a style for the tables, and **Insert at caret** inserts the nested blocks into the document:

![Design a merge block dialog with the block hierarchy, the fields checked for each level and a preview of the parent and nested tables in the selected style](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-server/assistant-block-designer.74a8f867.webp)

The Rules step sets the sorting and filter rules of a block and, for a nested block, a condition on its parent row; **Apply rules to block** stores them with the block:

![Rules step of the Template Assistant with a sort order by SalesOrderDetailID, a filter for UnitPrice greater than 200 and a disabled conditional block option](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-server/assistant-rules-step.2f631a81.webp)

When the input position is in a field that the assistant supports, the field's properties open in the panel, such as the name, the text before and after and the formats of a merge field, and changes apply immediately. Two more actions complete the workflow:

- **Preview merge** merges the template with the JSON data on the server and shows the result in the editor. **Restore template** brings the template back.
- **Download template** saves the template in the TX Text Control format with its fields, blocks, table styles and rules, ready for `MailMerge`.

The merged preview shows the nested blocks filled with the sample data, one table with its product row for each order detail:

![Merged preview in the Document Editor, in which the order detail block and its nested product block are repeated with values from the sample data](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-server/assistant-preview-merge.90c8f651.webp)

### How the Assistant Works

The assistant keeps no model of the template apart from the document itself. Fields are application fields, merge blocks are subtext parts, tables are regular tables and the sorting and filter rules are stored with the merge blocks, so the downloaded template works with `MailMerge` without the assistant. The work is divided between the browser and the server:

| Where | What happens | APIs |
|---|---|---|
| Browser | Reading the structure of the JSON, finding the fields for the input position, inserting and editing fields, showing the panel | [TXTextControl.loadJsonData](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/loadjsondata-method/llms-full.txt), [TXTextControl.addMergeField](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/addmergefield-method/llms-full.txt), [TXTextControl.saveDocument](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/javascript/txtextcontrol/savedocument-method/llms-full.txt) |
| Server | Checking a block design against the data, generating nested blocks, styling tables, storing rules and merging the preview | [DataSourceManager.InsertMergeBlock](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-datasources/datasourcemanager/insertmergeblock-method/llms-full.txt), [MergeBlockInfo](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver-datasources/mergeblockinfo/llms-full.txt), [TableCell.CellFormat](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol/tablecell/cellformat-property/llms-full.txt), [MailMerge.MergeJsonData](https://docs.textcontrol.com/tx-text-control-dotnet-server/reference/txtextcontrol-documentserver/mailmerge/mergejsondata-method/llms-full.txt) |

For a new block, the browser saves the document in the TX Text Control format and sends it to the server. The server inserts the block with `InsertMergeBlock`, a `MergeBlockInfo` whose `ChildBlocks` describe the nested levels and a `MergeBlockSettings` for a table row block with a header row, and the browser loads the returned document. In the Document Editor section, [Loading and Saving Documents](https://docs.textcontrol.com/tx-text-control-dotnet-server/document-editor/load-save/llms-full.txt) shows how documents travel between the editor and a controller.

### Reuse What the Assistant Shows

The **Code** area of the demo shows the code of the assistant: its JavaScript, its controller and its sample data. It's the actual code behind the demo, and you can study it and apply its patterns in your own application. Parts of it, such as the analysis behind the outline and helpers shared by all demos, aren't included in the code shown.

The documentation covers each pattern the assistant uses:

- Insert merge fields from JavaScript: [Merge Fields](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/mail-merge/fields/#insert-merge-fields-in-the-document-editor) in Getting Started.
- Insert nested merge blocks on the server: [Nested Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/nested-blocks/#create-a-nested-template-in-code).
- Store sorting, filter and merging rules: [Sorting and Filtering](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/sorting-filtering/llms-full.txt).
- Test a template with sample data: [Template Design](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/template-design/#test-a-template).

The demo site has related demos, such as the [Nested Merge Block Designer](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-nested-blocks) and [Merging Sub-Templates](https://demos.textcontrol.com/demos/rich-text-editor/mail-merge-include-text).

### Next Steps

- [Template Design](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/template-design/llms-full.txt): design templates that merge well.
- [Nested Blocks](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/nested-blocks/llms-full.txt): build the master-detail structures that the assistant generates.
- [Document Editor with ASP.NET Core](https://docs.textcontrol.com/tx-text-control-dotnet-server/getting-started/document-editor/aspnet-core/llms-full.txt): add the editor to your own application.

---

## Nearby

- **Previous:** [Template Design](https://docs.textcontrol.com/tx-text-control-dotnet-server/mail-merge/template-design/llms-full.txt)
- **Next:** [PDF Processing](https://docs.textcontrol.com/tx-text-control-dotnet-server/pdf/llms-full.txt)