How to Use Template Merging with Placeholder Substitution in OfficeCLI

OfficeCLI merges PowerPoint, Word, and Excel templates with user-provided values by replacing {PLACEHOLDER} strings with data supplied via CLI flags or JSON files.

Template merging with placeholder substitution is a core feature of the OfficeCLI open-source tool, enabling automated document generation without manual editing. This article explains the complete workflow using actual source code implementations from the repository.

How Template Merging Works

OfficeCLI implements a four-stage pipeline for document generation:

1. Load the template — Reads the source file (.pptx, .docx, or .xlsx) through format-specific handlers
2. Register for reuse — Stores templates in a static registry to avoid redundant file I/O
3. Substitute placeholders — Walks XML document parts and replaces {PLACEHOLDER} patterns with dictionary values
4. Write output — Saves the merged document to your specified path

Placeholders use the syntax {PLACEHOLDER} with any alphanumeric identifier. Unmatched placeholders remain unchanged, allowing partial template population.

CLI Command Structure

The merge sub-command exposes template merging through the command line. The following flags control the operation:

Flag	Short	Purpose
--template	-t	Path to source template file
--output	-o	Destination path for merged document
--param	-p	Key=value pair (repeatable)
--json	—	JSON file containing placeholder dictionary

Basic PowerPoint Example

officecli merge \
    --template templates/financial-report.pptx \
    --output reports/q1-2024.pptx \
    --param title="Q1 2024 Financial Report" \
    --param date="2024-04-01"

Word Example with JSON Input

# data.json: { "client": "Acme Corp", "project": "Website Redesign" }

officecli merge \
    -t templates/contract.docx \
    -o contracts/acme-contract.docx \
    --json data.json

Programmatic Usage (C# SDK)

For .NET applications, invoke OfficeCliEngine.MergeAsync() directly:

using OfficeCli;

var templatePath = @"templates/financial-report.pptx";
var outputPath   = @"reports/q2-2024.pptx";

var placeholders = new Dictionary<string, string>
{
    ["title"] = "Q2 2024 Financial Report",
    ["date"]  = "2024-07-01"
};

await OfficeCliEngine.MergeAsync(templatePath, outputPath, placeholders);

Placeholder Syntax in Document XML

Placeholders appear as plain text within the document's XML structure. For example, in a PowerPoint slide:

<p:txBody>
  <a:p>
    <a:r>
      <a:t>{title}</a:t>
    </a:r>
  </a:p>
</p:txBody>

OfficeCLI locates these patterns during the merge operation and replaces them with supplied values.

Key Implementation Files

Understanding the source architecture helps debug and extend template merging behavior:

File	Location	Function
PowerPointHandler.EffectTemplates.cs	src/officecli/Handlers/Pptx/	Static template registry (_templateRegistry) and PowerPoint placeholder substitution
WordHandler.Helpers.FindReplace.cs	src/officecli/Handlers/Word/	Find-and-replace engine for Word document XML
PptxBatchEmitter.cs	src/officecli/Handlers/Pptx/	Batch slide merging and template integration
officecli.csproj	src/officecli/	CLI entry point defining the merge command and flag parsing

The PowerPoint implementation in PowerPointHandler.EffectTemplates.cs maintains a static registry for template reuse, while the Word implementation in WordHandler.Helpers.FindReplace.cs handles XML text node traversal for replacement operations.

Supported File Formats

OfficeCLI template merging supports three primary Office formats:

• PowerPoint (.pptx) — Slides, layouts, and masters
• Word (.docx) — Documents, headers, footers, and text boxes
• Excel (.xlsx) — Worksheets and cell content

Each format uses dedicated handlers that understand the specific Open XML structure for that document type.

Summary

• Use {PLACEHOLDER} syntax in template documents for substitution points
• Supply values via --param flags for simple cases or --json for complex data
• Templates are cached in a static registry to improve performance on repeated operations
• Unmatched placeholders remain unchanged, enabling flexible partial merges
• The implementation spans PowerPointHandler.EffectTemplates.cs and WordHandler.Helpers.FindReplace.cs for format-specific logic

Frequently Asked Questions

What happens if a placeholder is missing from my data?

The original {PLACEHOLDER} text remains unchanged in the output document. This intentional behavior allows you to reuse templates with partial data sets and fill remaining values manually or in subsequent processing steps.

Can I use the same template for multiple output files?

Yes. Templates are registered in a static registry (_templateRegistry in PowerPointHandler.EffectTemplates.cs), so OfficeCLI avoids re-reading the source file for each merge operation. This design optimizes batch generation scenarios.

Does placeholder substitution preserve document formatting?

Yes. OfficeCLI modifies only the text content within XML nodes, leaving all styling, layouts, and formatting intact. The replacement occurs at the text level in WordHandler.Helpers.FindReplace.cs and equivalent PowerPoint handlers.

Is there a limit to how many placeholders I can use?

No hard limit exists. You can supply any number of --param flags or include unlimited keys in your JSON file. Performance depends on document size and complexity rather than placeholder count.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}