# Subtemplates

> Include subtemplates in WPF mail merge templates: INCLUDETEXT fields, the IncludeText class, MailMerge.SearchPath and content supplied in IncludeTextMerging.

- **Product:** TX Text Control .NET for WPF
- **Section:** Documentation
- **Kind:** Topic
- **Path:** TX Text Control .NET for WPF > Mail Merge and Reporting > Subtemplates
- **2438 words**
- **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/subtemplates/
- **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/subtemplates/llms.txt
- **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/subtemplates/llms-full.txt

---

When the same terms and conditions, letterhead or address block belong in twenty templates, maintaining twenty copies is error-prone. A subtemplate keeps such content in one document that any template includes through an MS Word `INCLUDETEXT` field. During the merge, `MailMerge` replaces the field with the subtemplate, so an edit to the subtemplate reaches every template at once. In a WPF application, you insert these fields from the Reporting tab or from code, point `MailMerge` to the folder of the subtemplates and, where needed, provide the included content from your code.

The examples work with the invoice template *invoice.docx* and the data *invoice.json* of [Merge Data into Fields](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/getting-started/mail-merge/fields/llms-full.txt). The design of templates in general is the subject of [Template Design](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/template-design/llms-full.txt).

### How Subtemplates Work

`MailMerge` treats an `INCLUDETEXT` field as a reference: it loads the document the field names and inserts the content at the field's position.

- **The search path.** The file name is looked up in the folder of [MailMerge.SearchPath](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver/mailmerge/searchpath-property/llms-full.txt), which also holds the image files of image placeholders. With an empty search path, the root directory is used.
- **Nested content is merged.** A subtemplate may contain merge fields, merge blocks and `INCLUDETEXT` fields of its own; they are merged with the same data as the template.
- **Formats.** Subtemplates are loaded from files in formats such as DOCX, DOC and RTF.
- **Headers and footers.** Put an `INCLUDETEXT` field into the header of a template to share a page header, and design the content of the subtemplate in its main text rather than in its header.

Instead of a file, your code can provide the content of each field, for example from a database; see [Supply Subtemplates From Code](#supply-subtemplates-from-code).

### Insert an INCLUDETEXT Field With the Ribbon

The WPF Reporting tab offers `INCLUDETEXT` among its special fields:

1. Place the input position where the subtemplate belongs.
2. In the **Merge Fields** group, open the **Insert Special Field** drop-down and click **IncludeText**.
3. Type the file name of the subtemplate, such as *terms.docx*, into the dialog box and click **OK**.

`MailMerge` always includes the whole document; a bookmark set in the field for MS Word is ignored.

### Insert an INCLUDETEXT Field in Code

[IncludeText](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/includetext/llms-full.txt) creates the field for the WPF `TextControl`. Add a button with `Click="insertTermsButton_Click"` to *MainWindow.xaml*, and in *MainWindow.xaml.cs* `using TXTextControl.DocumentServer.Fields;` and this handler:

```csharp
private void insertTermsButton_Click(object sender, RoutedEventArgs e)
{
    IncludeText includeText = new IncludeText
    {
        // Searched in MailMerge.SearchPath during the merge
        Filename = "terms.docx"
    };

    textControl1.ApplicationFields.Add(includeText.ApplicationField);
}
```

- The [IncludeText constructor](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/includetext/constructor/llms-full.txt) creates a new field, or, with an `ApplicationField` as parameter, gives access to one that exists.
- [Filename](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/includetext/filename-property/llms-full.txt) names the subtemplate. [TextFormat](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/includetext/textformat-property/llms-full.txt) sets the case of the included text: `Uppercase`, `Lowercase`, `FirstCapital`, `TitleCase` or `None`. [Bookmark](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver-fields/includetext/bookmark-property/llms-full.txt) isn't used by `MailMerge`.
- `ApplicationFields.Add` inserts the field at the input position.

Saved as DOCX, the template keeps the field as an MS Word field; the `LoadSettings` of the merge, with `ApplicationFieldFormat.MSWord`, import it again.

### Merge a Template With Subtemplates

Copy *terms.docx* into a folder *Subtemplates* of the application's output folder. The following handler sets the search path, merges the invoice in a `ServerTextControl` and loads the result into the editor; it needs `using System;`, `using System.IO;` and `using TXTextControl.DocumentServer;`:

```csharp
private void mergeWithSubtemplatesButton_Click(object sender, RoutedEventArgs e)
{
    byte[] result;

    using (ServerTextControl tx = new ServerTextControl())
    {
        tx.Create();

        LoadSettings loadSettings = new LoadSettings
        {
            ApplicationFieldFormat = ApplicationFieldFormat.MSWord,
            LoadSubTextParts = true
        };

        tx.Load("invoice.docx", StreamType.WordprocessingML, loadSettings);

        using (MailMerge mailMerge = new MailMerge
        {
            TextComponent = tx,
            // The Subtemplates folder next to the executable
            SearchPath = System.IO.Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Subtemplates")
        })
        {
            mailMerge.IncludeTextMerging += MailMerge_IncludeTextMerging;
            mailMerge.MergeJsonData(File.ReadAllText("invoice.json"));
        }

        tx.Save(out result, BinaryStreamType.InternalUnicodeFormat);
    }

    textControl1.Load(result, BinaryStreamType.InternalUnicodeFormat);
}
```

WPF has no `Application.StartupPath`; `AppDomain.CurrentDomain.BaseDirectory` is the folder the application runs from. The handler of [IncludeTextMerging](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver/mailmerge/includetextmerging-event/llms-full.txt) is shown next. Without one, each field includes its file from the search path.

### Supply Subtemplates From Code

For each `INCLUDETEXT` field, `MailMerge` raises `IncludeTextMerging`, and your handler may hand over a document of its own. The file name then works as a key: here, the field with the file name *legal-notice.docx* receives a formatted sentence built in code:

```csharp
private void MailMerge_IncludeTextMerging(object sender, MailMerge.IncludeTextMergingEventArgs e)
{
    // Other files are included from the search path
    if (!e.Filename.EndsWith("legal-notice.docx"))
    {
        return;
    }

    using (ServerTextControl notice = new ServerTextControl())
    {
        notice.Create();
        notice.Text = "Prices include statutory VAT.";
        notice.Select(0, notice.Text.Length);
        notice.Selection.Italic = true;

        byte[] data;
        notice.Save(out data, BinaryStreamType.InternalUnicodeFormat);
        e.IncludeTextDocument = data;
    }
}
```

The code works as follows:

- [Filename](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver/mailmerge-includetextmergingeventargs/filename-property/llms-full.txt) is the file name of the current field; [IncludeTextField](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver/mailmerge-includetextmergingeventargs/includetextfield-property/llms-full.txt) gives the field as an `IncludeText` object.
- The content is formatted in a second `ServerTextControl`, which runs without a window, also in a WPF application.
- [IncludeTextDocument](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/reference/txtextcontrol-documentserver/mailmerge-includetextmergingeventargs/includetextdocument-property/llms-full.txt) receives the document as a byte array in the internal TX Text Control format. Its reference page gives the type as `int`, but the compiled property is a `byte[]`, as used here.

An empty document leaves the subtemplate out; [Conditional Content](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/conditional-content/#include-subtemplates-depending-on-your-code) includes terms only for some records this way. The blog article [MailMerge: Using IncludeText Fields to Inject Formatted Text](https://www.textcontrol.com/blog/2009/10/09/mailmerge-using-includetext-fields-to-inject-formatted-text/) fills several fields with generated text.

### Next Steps

- [Conditional Content](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/conditional-content/llms-full.txt): include a subtemplate only for some records.
- [Template Design](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/template-design/llms-full.txt): plan templates, headers and footers.
- [Merge Events](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/events/llms-full.txt): the other events of a merge.
- The blog article [Using Sub-templates in Text Control Reporting](https://www.textcontrol.com/blog/2014/01/17/using-sub-templates-in-text-control-reporting/): a page header shared as a subtemplate.

---

## Nearby

- **Previous:** [Nested Blocks and Master-Detail Reports](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/nested-blocks/llms-full.txt)
- **Next:** [Images and Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-wpf/mail-merge/images-barcodes/llms-full.txt)