feat: add UpdateFieldsOnOpen option for TOC refresh #68

vaceslav · 2026-01-06T15:46:53Z

Summary

Add UpdateFieldsOnOpen option to PlaceholderReplacementOptions for refreshing Table of Contents when documents are opened in Word
When templates with TOC are processed and content is removed via conditionals/loops, TOC page numbers become stale
This option sets Word's <w:updateFields> document setting so Word prompts users to update fields on open

Usage

var options = new PlaceholderReplacementOptions
{
    UpdateFieldsOnOpen = true
};

var processor = new DocumentTemplateProcessor(options);
processor.ProcessTemplate(templateStream, outputStream, data);

Test plan

Test that UpdateFieldsOnOpen = true sets document setting correctly
Test that UpdateFieldsOnOpen = false (default) does not set document setting
Test TOC structure preserved after processing
Test placeholders after TOC work correctly
All 936 tests pass

Closes #67

When templates with Table of Contents are processed and content is removed via conditionals or loops, TOC page numbers become stale. Add UpdateFieldsOnOpen option that sets Word's <w:updateFields> document setting. When enabled, Word prompts users to update fields (including TOC) when opening the document. Closes #67

Copilot

Pull request overview

This PR adds a new UpdateFieldsOnOpen option to address the issue of stale Table of Contents (TOC) page numbers after template processing. When templates contain TOC fields and content is removed via conditionals or loops, the cached page numbers become outdated. The new option sets Word's document setting to prompt users to update fields when opening the document.

Key Changes

Added UpdateFieldsOnOpen boolean property to PlaceholderReplacementOptions (defaults to false for backward compatibility)
Implemented ApplyUpdateFieldsOnOpen() method to set the Word document setting
Added comprehensive test coverage for TOC behavior and the new option

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`TriasDev.Templify/Core/PlaceholderReplacementOptions.cs`	Adds new `UpdateFieldsOnOpen` property with comprehensive documentation explaining the TOC refresh behavior
`TriasDev.Templify/Core/DocumentTemplateProcessor.cs`	Implements `ApplyUpdateFieldsOnOpen()` method to configure Word document settings and integrates it into the processing pipeline
`TriasDev.Templify.Tests/Integration/TableOfContentsTests.cs`	Adds comprehensive test suite documenting TOC behavior, including tests for stale page numbers, structure preservation, and the new option
`TriasDev.Templify.Tests/Helpers/DocumentVerifier.cs`	Adds helper methods to verify TOC presence, extract entries, and check `UpdateFieldsOnOpen` setting
`TriasDev.Templify.Tests/Helpers/DocumentBuilder.cs`	Adds methods to build test documents with TOC fields, headings, and page breaks

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-07T12:47:24Z

TriasDev.Templify/Core/DocumentTemplateProcessor.cs

+            settingsPart = document.MainDocumentPart.AddNewPart<DocumentSettingsPart>();
+            settingsPart.Settings = new Settings();
+        }
+


Potential null reference exception: settingsPart.Settings could be null if the DocumentSettingsPart already exists but has no Settings object initialized. Add a null check after line 267 to handle this case, or initialize Settings if it's null.

Suggested change

if (settingsPart.Settings == null)

{

settingsPart.Settings = new Settings();

}

Copilot · 2026-01-07T12:47:25Z

TriasDev.Templify.Tests/Helpers/DocumentVerifier.cs

+            foreach (Run run in para.Descendants<Run>())
+            {
+                FieldChar? fieldChar = run.GetFirstChild<FieldChar>();
+                if (fieldChar != null)
+                {
+                    if (fieldChar.FieldCharType?.Value == FieldCharValues.Begin)
+                    {
+                        inTocField = true;
+                        afterSeparator = false;
+                    }
+                    else if (fieldChar.FieldCharType?.Value == FieldCharValues.Separate)
+                    {
+                        afterSeparator = true;
+                    }
+                    else if (fieldChar.FieldCharType?.Value == FieldCharValues.End)
+                    {
+                        inTocField = false;
+                        afterSeparator = false;
+                    }
+                }
+            }


This foreach loop immediately maps its iteration variable to another variable - consider mapping the sequence explicitly using '.Select(...)'.

Copilot · 2026-01-07T12:47:25Z

TriasDev.Templify.Tests/Helpers/DocumentVerifier.cs

+        foreach (string entry in entries)
+        {
+            // TOC entries typically end with a page number
+            string[] parts = entry.Split('\t', ' ');
+            if (parts.Length > 0 && int.TryParse(parts[^1], out int pageNum))
+            {
+                pageNumbers.Add(pageNum);
+            }
+        }


This foreach loop immediately maps its iteration variable to another variable - consider mapping the sequence explicitly using '.Select(...)'.

BREAKING CHANGE: UpdateFieldsOnOpen changed from bool to enum. Add UpdateFieldsOnOpenMode enum with three options: - Never: default, never set the flag (backward compatible behavior) - Always: always set the flag (replaces true) - Auto: only set flag if document contains fields (TOC, PAGE, etc.) Auto mode is recommended for applications that process various templates, as it only prompts users to update fields when necessary. Detected fields: TOC, PAGE, NUMPAGES, PAGEREF, DATE, TIME, FILENAME

Document the new UpdateFieldsOnOpenMode option in README: - Explain the three modes (Never, Always, Auto) - Provide usage examples - Explain why Templify can't update TOC directly - Add to API Reference section

Add configuration options section and TOC support documentation to docs/for-developers/quick-start.md including all available PlaceholderReplacementOptions and detailed UpdateFieldsOnOpenMode usage examples.

Collection expressions are not available in C# 10.0 (net6.0). Changed from collection expression to traditional array initializer.

- Move field type array to class-level static readonly field for performance - Add REF, NOTEREF, SECTIONPAGES to Auto mode field detection

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-07T13:11:55Z

TriasDev.Templify/Core/DocumentTemplateProcessor.cs

+            .Any(fc => fc.Text != null &&
+                       _dynamicFieldTypes.Any(field =>
+                           fc.Text.Contains(field, StringComparison.OrdinalIgnoreCase)));


The field detection logic has a potential false positive issue. It checks if the FieldCode text contains any of the dynamic field types, but this could match partial words. For example, a field code containing "TOCENTRY" or "PAGETOTAL" would match "TOC" and "PAGE" respectively. Consider using word boundary matching or checking for the field type at the start of the field code text (after trimming whitespace).

Suggested change

.Any(fc => fc.Text != null &&

_dynamicFieldTypes.Any(field =>

fc.Text.Contains(field, StringComparison.OrdinalIgnoreCase)));

.Any(fc =>

{

if (string.IsNullOrWhiteSpace(fc.Text))

{

return false;

}

// Field codes typically start with the field type, followed by

// spaces, switches (starting with '\'), and parameters.

// Example: "PAGE \\* MERGEFORMAT"

string text = fc.Text.TrimStart();

// Get the first token (up to whitespace or a backslash for switches)

int endIndex = text.IndexOfAny(new[] { ' ', '\t', '\r', '\n', '\\' });

string fieldTypeInDoc = endIndex >= 0 ? text[..endIndex] : text;

foreach (string field in _dynamicFieldTypes)

{

if (fieldTypeInDoc.Equals(field, StringComparison.OrdinalIgnoreCase))

{

return true;

}

}

return false;

});

Copilot · 2026-01-07T13:11:56Z

docs/for-developers/quick-start.md

+
+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:** OpenXML SDK cannot calculate page numbers—only Word's layout engine can determine actual pagination.


The comment states "OpenXML SDK cannot calculate page numbers" but should be "The OpenXML SDK" for grammatical correctness.

Suggested change

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

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

Copilot · 2026-01-07T13:11:56Z

TriasDev.Templify/README.md

+
+**Why can't Templify update TOC page numbers directly?**
+
+Page numbers are calculated by Word's layout engine at render time. OpenXML (and Templify) can only store the document structure, not the rendered output. Only Word can calculate actual page numbers based on fonts, margins, page breaks, etc.


The documentation mentions "OpenXML (and Templify)" but should be "The OpenXML SDK (and Templify)" for consistency and grammatical correctness.

Suggested change

Page numbers are calculated by Word's layout engine at render time. OpenXML (and Templify) can only store the document structure, not the rendered output. Only Word can calculate actual page numbers based on fonts, margins, page breaks, etc.

Page numbers are calculated by Word's layout engine at render time. The OpenXML SDK (and Templify) can only store the document structure, not the rendered output. Only Word can calculate actual page numbers based on fonts, margins, page breaks, etc.

- Add null check for settingsPart.Settings in ApplyUpdateFieldsOnOpen - Fix field detection false positives by parsing field type token - Fix grammar: "OpenXML SDK" → "The OpenXML SDK" in docs

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-07T13:54:11Z

docs/for-developers/quick-start.md

+
+- `TOC` - Table of Contents
+- `PAGE` - Current page number
+- `NUMPAGES` - Total page count
+- `PAGEREF` - Page references


The documentation lists only TOC, PAGE, NUMPAGES, PAGEREF, DATE, TIME, and FILENAME fields as detected in Auto mode, but the implementation also includes REF, NOTEREF, and SECTIONPAGES. The documentation should be updated to include all field types that are detected, or clarify that these are examples of commonly used fields.

Suggested change

- `TOC` - Table of Contents

- `PAGE` - Current page number

- `NUMPAGES` - Total page count

- `PAGEREF` - Page references

The following fields are currently detected when `UpdateFieldsOnOpen` is set to `Auto`:

- `TOC` - Table of Contents

- `PAGE` - Current page number

- `NUMPAGES` - Total page count

- `PAGEREF` - Page references

- `REF` - Cross-references

- `NOTEREF` - Footnote or endnote references

- `SECTIONPAGES` - Page count in the current section

Copilot · 2026-01-07T13:54:12Z

TriasDev.Templify/README.md

+{
+    UpdateFieldsOnOpen = UpdateFieldsOnOpenMode.Auto
+};
+// Only prompts if document contains TOC, PAGE, NUMPAGES, PAGEREF, DATE, TIME, or FILENAME fields


The comment on line 768 lists TOC, PAGE, NUMPAGES, PAGEREF, DATE, TIME, or FILENAME fields, but the implementation (_dynamicFieldTypes array in DocumentTemplateProcessor.cs) also includes REF, NOTEREF, and SECTIONPAGES. The documentation should be updated to include all detected field types or clarify that these are examples.

Suggested change

// Only prompts if document contains TOC, PAGE, NUMPAGES, PAGEREF, DATE, TIME, or FILENAME fields

// Only prompts if document contains TOC, PAGE, NUMPAGES, PAGEREF, REF, NOTEREF, SECTIONPAGES, DATE, TIME, or FILENAME fields

Copilot · 2026-01-07T13:54:12Z

TriasDev.Templify/Core/DocumentTemplateProcessor.cs

+                foreach (string field in _dynamicFieldTypes)
+                {
+                    if (fieldTypeInDoc.Equals(field, StringComparison.OrdinalIgnoreCase))
+                    {
+                        return true;
+                    }
+                }


This foreach loop implicitly filters its target sequence - consider filtering the sequence explicitly using '.Where(...)'.

- Add missing field types (REF, NOTEREF, SECTIONPAGES) to documentation - Refactor GetTableOfContentsPageNumbers to use LINQ

vaceslav requested a review from Copilot January 7, 2026 12:43

Copilot started reviewing on behalf of vaceslav January 7, 2026 12:43 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

vaceslav added 5 commits January 7, 2026 13:55

docs: add UpdateFieldsOnOpen documentation

cbfa1b7

Document the new UpdateFieldsOnOpenMode option in README: - Explain the three modes (Never, Always, Auto) - Provide usage examples - Explain why Templify can't update TOC directly - Add to API Reference section

docs: add UpdateFieldsOnOpen documentation to developer quick-start

11b4bec

Add configuration options section and TOC support documentation to docs/for-developers/quick-start.md including all available PlaceholderReplacementOptions and detailed UpdateFieldsOnOpenMode usage examples.

fix: use array initializer syntax for net6.0 compatibility

21dcbcf

Collection expressions are not available in C# 10.0 (net6.0). Changed from collection expression to traditional array initializer.

refactor: extract dynamic field types to static readonly array

1b808a9

- Move field type array to class-level static readonly field for performance - Add REF, NOTEREF, SECTIONPAGES to Auto mode field detection

vaceslav force-pushed the feat/update-fields-on-open branch from 0f9865d to 1b808a9 Compare January 7, 2026 13:06

vaceslav requested a review from Copilot January 7, 2026 13:08

Copilot started reviewing on behalf of vaceslav January 7, 2026 13:09 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

fix: address PR review comments for UpdateFieldsOnOpen

c22edc1

- Add null check for settingsPart.Settings in ApplyUpdateFieldsOnOpen - Fix field detection false positives by parsing field type token - Fix grammar: "OpenXML SDK" → "The OpenXML SDK" in docs

vaceslav requested a review from Copilot January 7, 2026 13:50

Copilot started reviewing on behalf of vaceslav January 7, 2026 13:50 View session

Copilot AI reviewed Jan 7, 2026

View reviewed changes

fix: address remaining PR review comments

911a4e1

- Add missing field types (REF, NOTEREF, SECTIONPAGES) to documentation - Refactor GetTableOfContentsPageNumbers to use LINQ

vaceslav merged commit 8bd178e into main Jan 7, 2026
14 checks passed

vaceslav deleted the feat/update-fields-on-open branch January 7, 2026 14:09

-            .Any(fc => fc.Text != null &&
-                       _dynamicFieldTypes.Any(field =>
-                           fc.Text.Contains(field, StringComparison.OrdinalIgnoreCase)));
+            .Any(fc =>
+            {
+                if (string.IsNullOrWhiteSpace(fc.Text))
+                {
+                    return false;
+                }
+                // Field codes typically start with the field type, followed by
+                // spaces, switches (starting with '\'), and parameters.
+                // Example: "PAGE \\* MERGEFORMAT"
+                string text = fc.Text.TrimStart();
+                // Get the first token (up to whitespace or a backslash for switches)
+                int endIndex = text.IndexOfAny(new[] { ' ', '\t', '\r', '\n', '\\' });
+                string fieldTypeInDoc = endIndex >= 0 ? text[..endIndex] : text;
+                foreach (string field in _dynamicFieldTypes)
+                {
+                    if (fieldTypeInDoc.Equals(field, StringComparison.OrdinalIgnoreCase))
+                    {
+                        return true;
+                    }
+                }
+                return false;
+            });


		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: OpenXML SDK cannot calculate page numbers—only Word's layout engine can determine actual pagination.

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


		Why can't Templify update TOC page numbers directly?

		Page numbers are calculated by Word's layout engine at render time. OpenXML (and Templify) can only store the document structure, not the rendered output. Only Word can calculate actual page numbers based on fonts, margins, page breaks, etc.

	// Only prompts if document contains TOC, PAGE, NUMPAGES, PAGEREF, DATE, TIME, or FILENAME fields
	// Only prompts if document contains TOC, PAGE, NUMPAGES, PAGEREF, REF, NOTEREF, SECTIONPAGES, DATE, TIME, or FILENAME fields

feat: add UpdateFieldsOnOpen option for TOC refresh #68

feat: add UpdateFieldsOnOpen option for TOC refresh #68

Uh oh!

Conversation

vaceslav commented Jan 6, 2026

Summary

Usage

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants