Quick Start for Developers¶

Get started with Templify in your .NET application.

Installation¶

dotnet add package TriasDev.Templify

Basic Usage¶

using TriasDev.Templify;

var data = new Dictionary<string, object>
{
    ["CustomerName"] = "John Doe",
    ["OrderDate"] = DateTime.Now.ToString("yyyy-MM-dd")
};

var processor = new DocumentTemplateProcessor();
using var templateStream = File.OpenRead("template.docx");
using var outputStream = File.Create("output.docx");

var result = processor.ProcessTemplate(templateStream, outputStream, data);

if (result.Success)
{
    Console.WriteLine("Template processed successfully!");
}

Configuration Options¶

Customize template processing with PlaceholderReplacementOptions:

var options = new PlaceholderReplacementOptions
{
    MissingVariableBehavior = MissingVariableBehavior.ReplaceWithEmpty,
    Culture = CultureInfo.GetCultureInfo("de-DE"),
    EnableNewlineSupport = true,
    UpdateFieldsOnOpen = UpdateFieldsOnOpenMode.Auto
};

var processor = new DocumentTemplateProcessor(options);

Available Options¶

Option	Type	Default	Description
`MissingVariableBehavior`	enum	`LeaveUnchanged`	How to handle missing variables
`Culture`	`CultureInfo`	`CurrentCulture`	Culture for formatting numbers and dates
`EnableNewlineSupport`	`bool`	`true`	Convert `\n` to Word line breaks
`UpdateFieldsOnOpen`	enum	`Never`	When to prompt Word to update fields
`TextReplacements`	dictionary	`null`	Text replacement lookup table
`DocumentProperties`	`DocumentProperties?`	`null`	Metadata properties to set on output document

Headers and Footers¶

ProcessTemplate automatically processes all headers and footers in the document - no additional API calls or configuration needed. The same visitor pipeline (placeholders, conditionals, loops) is applied to every header and footer part (Default, First Page, Even Page).

Update Fields on Open (TOC Support)¶

When templates contain Table of Contents (TOC) or other dynamic fields, and content changes during processing (via conditionals or loops), page numbers become stale.

Why this happens: The OpenXML SDK cannot calculate page numbers—only Word's layout engine can determine actual pagination.

UpdateFieldsOnOpenMode Options¶

Mode	Description
`Never`	Never prompt to update fields (default)
`Always`	Always prompt to update fields
`Auto`	Recommended - Only prompt if document contains fields (TOC, PAGE, etc.)

Usage Examples¶

For applications processing user-uploaded templates (recommended):

// Auto-detect: only prompts if document has TOC, PAGE, etc.
var options = new PlaceholderReplacementOptions
{
    UpdateFieldsOnOpen = UpdateFieldsOnOpenMode.Auto
};

For templates known to have TOC:

var options = new PlaceholderReplacementOptions
{
    UpdateFieldsOnOpen = UpdateFieldsOnOpenMode.Always
};

Fields Detected in Auto Mode¶

TOC - Table of Contents
PAGE - Current page number
NUMPAGES - Total page count
PAGEREF - Page references
DATE - Current date
TIME - Current time
FILENAME - Document filename
REF - Cross-references
NOTEREF - Footnote/endnote references
SECTIONPAGES - Pages in current section

Note: When enabled, Word displays a prompt asking the user to confirm field updates. This is a security measure built into Word.

Document Properties¶

Set metadata on the output document (Author, Title, Subject, etc.). Properties left as null preserve the original template value.

var options = new PlaceholderReplacementOptions
{
    DocumentProperties = new DocumentProperties
    {
        Author = "My Application",
        Title = "Generated Report"
    }
};

Available Properties¶

Property	Maps to in Word
`Author`	Author (Creator)
`Title`	Title
`Subject`	Subject
`Description`	Comments
`Keywords`	Keywords
`Category`	Category
`LastModifiedBy`	Last Modified By

Note: When DocumentProperties is null (default), all original template metadata is preserved. When set, only non-null properties are applied.