Format Specifiers Guide

Format specifiers allow you to control how values are displayed in your generated documents. You can format booleans as checkboxes or Yes/No text, transform string casing, display numbers with specific decimal places, format currency values according to locale, and apply custom date formats.

Each specifier applies to one kind of value: string specifiers to text, boolean specifiers to true/false, number specifiers to numbers and date specifiers to dates (or date text). On any other kind of value the specifier is ignored and the value is shown as usual. Numbers, dates and currency use the culture configured by the developer (PlaceholderReplacementOptions.Culture, by default the culture of the machine running Templify).

Table of Contents

• Quick Start
• Available Format Specifiers
• String Formatters
• Raw (No Markdown)
• Boolean Formatters
• Number and Currency Formatters
• Date Formatters
• Using Format Specifiers
• Localization Support
• Custom Formatters
• Advanced Usage
• Best Practices

Quick Start

Add a format specifier to any placeholder using the :format syntax:

Template:

User Status: {{IsActive:checkbox}}

C# Data:

var data = new Dictionary<string, object>
{
    ["IsActive"] = true
};

JSON Data:

{
  "IsActive": true
}

Output:

User Status: ☑

Available Format Specifiers

String Formatters

uppercase

Converts a string value to UPPERCASE.

Example:

Customer: {{CustomerName:uppercase}}

JSON:

{
  "CustomerName": "alice johnson"
}

Output:

Customer: ALICE JOHNSON

lowercase

Converts a string value to lowercase.

Example:

Code: {{ProductCode:lowercase}}

JSON:

{
  "ProductCode": "ABC-123-XYZ"
}

Output:

Code: abc-123-xyz

Notes: - String formatters only apply to string values. Non-string values are rendered normally. - Case conversion respects the configured culture (e.g., Turkish locale handles I/i correctly).

raw

Inserts the value without markdown interpretation. By default, *, _ and ~ in values are read as markdown (bold, italic, strikethrough). Use :raw for file names, identifiers, product codes or formulas that contain these characters.

Example:

File: {{FileName:raw}}
Formula: {{Formula:raw}}

JSON:

{
  "FileName": "my_report_final.docx",
  "Formula": "2*3*4"
}

Output:

File: my_report_final.docx
Formula: 2*3*4

Without :raw, the output would be myreportfinal.docx (with "report" in italic) and 234.

Notes: - :raw only disables markdown. The value otherwise uses default conversion, and line breaks still work. - :raw cannot be combined with another format specifier. Use either :raw or, for example, :uppercase. - To disable markdown for all placeholders, developers can set EnableMarkdown = false in PlaceholderReplacementOptions. - Text templates (TextTemplateProcessor) never apply markdown, so :raw has no visible effect there.

Boolean Formatters

checkbox

Displays a checked or unchecked checkbox symbol.

Value	Output
true	☑
false	☐

Example:

Task completed: {{IsCompleted:checkbox}}

yesno

Displays "Yes" or "No" text.

Value	Output
true	Yes
false	No

Example:

Approved: {{IsApproved:yesno}}

checkmark (alias: check)

Displays a checkmark or X symbol. {{IsValid:check}} is the same as {{IsValid:checkmark}}.

Value	Output
true	✓
false	✗

Example:

Valid: {{IsValid:checkmark}}

truefalse

Displays "True" or "False" text (explicit default).

Value	Output
true	True
false	False

Example:

Debug mode: {{DebugEnabled:truefalse}}

onoff

Displays "On" or "Off" text.

Value	Output
true	On
false	Off

Example:

Power: {{PowerStatus:onoff}}

enabled

Displays "Enabled" or "Disabled" text.

Value	Output
true	Enabled
false	Disabled

Example:

Feature flag: {{NewFeature:enabled}}

active

Displays "Active" or "Inactive" text.

Value	Output
true	Active
false	Inactive

Example:

Account status: {{AccountStatus:active}}

Number and Currency Formatters

currency

Formats a number as currency using the configured culture's currency symbol and format.

Culture	Input	Output
en-US	1234.56	$1,234.56
de-DE	1234.56	1.234,56 €
fr-FR	1234.56	1 234,56 €

Example:

Total: {{Amount:currency}}

JSON:

{
  "Amount": 1234.56
}

Output (en-US culture):

Total: $1,234.56

number:FORMAT

Formats a number using a .NET format string. The format string follows the colon after number.

Specifier	Description	Input	Output
:number:N2	Number with 2 decimal places	1234.5678	1,234.57
:number:N0	Number with no decimals	1234.5	1,235
:number:F3	Fixed-point with 3 decimals	3.14159	3.142
:number:P2	Percentage with 2 decimals	0.1234	12.34%
:number:C	Currency (same as :currency)	42	$42.00

Example:

Value: {{Price:number:N2}}
Rate: {{InterestRate:number:F3}}
Progress: {{Completion:number:P0}}

JSON:

{
  "Price": 1234.5678,
  "InterestRate": 3.14159,
  "Completion": 0.85
}

Output (en-US culture):

Value: 1,234.57
Rate: 3.142
Progress: 85%

Notes: - Number formatters only apply to numeric values (all .NET number types, e.g. int, long, decimal, double, and JSON numbers) - Non-numeric values with a number format specifier are rendered normally (format is ignored). This includes numbers stored as text: "Price": "19.99" is not formatted; use "Price": 19.99 - The exact output depends on the culture: with en-US, :number:P2 gives 12.34%, with the invariant culture 12.34 %, with de-DE 12,34 %. Without a precision (:number:P), the number of decimals comes from the culture and can differ between operating systems, so prefer an explicit precision such as P0 or P2 - Invalid format strings are handled gracefully — the value falls through to default formatting - Format specifier names are case-insensitive: :currency, :CURRENCY, and :Currency all work

Date Formatters

date:FORMAT

Formats date values using a .NET date format string. The format string follows the colon after date.

Specifier	Description	Input	Output (en-US)
:date:yyyy-MM-dd	ISO date	2024-01-15	2024-01-15
:date:dd.MM.yyyy	European date	2024-01-15	15.01.2024
:date:MMMM d, yyyy	Long date	2024-01-15	January 15, 2024
:date:dd. MMMM yyyy	German long date (de-DE)	2024-01-15	15. Januar 2024
:date:yyyy	Year only	2024-01-15	2024

Example:

Order Date: {{OrderDate:date:MMMM d, yyyy}}
Due Date: {{DueDate:date:dd.MM.yyyy}}

JSON:

{
  "OrderDate": "2024-01-15",
  "DueDate": "2024-02-15"
}

Output (en-US culture):

Order Date: January 15, 2024
Due Date: 15.02.2024

Supported value types: - DateTime objects - DateTimeOffset objects - Date strings (parsed automatically, e.g., "2024-01-15", "2024-01-15T10:30:00+02:00", "01/15/2024"; ISO and invariant formats first, then the configured culture, e.g. "15.01.2024" with de-DE)

Notes: - Month and day names are localized based on the configured culture - Non-date values with a date format specifier are rendered normally (format is ignored) - Unparseable date strings are rendered as-is - Invalid format strings are handled gracefully

Using Format Specifiers

Basic Usage

Template:

Name: {{Name}}
Active: {{IsActive:checkbox}}
Verified: {{IsVerified:yesno}}
Valid: {{IsValid:checkmark}}

C# Data:

var data = new Dictionary<string, object>
{
    ["Name"] = "John Doe",
    ["IsActive"] = true,
    ["IsVerified"] = false,
    ["IsValid"] = true
};

JSON Data:

{
  "Name": "John Doe",
  "IsActive": true,
  "IsVerified": false,
  "IsValid": true
}

Output:

Name: John Doe
Active: ☑
Verified: No
Valid: ✓

With Nested Properties

Format specifiers work seamlessly with nested object properties.

Template:

User: {{User.Name}}
Status: {{User.IsActive:checkbox}}

C# Data:

var data = new Dictionary<string, object>
{
    ["User"] = new
    {
        Name = "Jane Smith",
        IsActive = true
    }
};

JSON Data:

{
  "User": {
    "Name": "Jane Smith",
    "IsActive": true
  }
}

Output:

User: Jane Smith
Status: ☑

With Array Indexing

Format specifiers work with array elements.

Template:

First item: {{Items[0].Name}}
Active: {{Items[0].IsActive:yesno}}

C# Data:

var data = new Dictionary<string, object>
{
    ["Items"] = new[]
    {
        new { Name = "Item 1", IsActive = true },
        new { Name = "Item 2", IsActive = false }
    }
};

JSON Data:

{
  "Items": [
    { "Name": "Item 1", "IsActive": true },
    { "Name": "Item 2", "IsActive": false }
  ]
}

Output:

First item: Item 1
Active: Yes

In Loops

Format specifiers are particularly useful in loops to display status indicators.

Template:

{{#foreach Tasks}}
- {{Name}}: {{IsCompleted:checkbox}}
{{/foreach}}

C# Data:

var data = new Dictionary<string, object>
{
    ["Tasks"] = new[]
    {
        new { Name = "Design mockups", IsCompleted = true },
        new { Name = "Implement feature", IsCompleted = false },
        new { Name = "Write tests", IsCompleted = true }
    }
};

JSON Data:

{
  "Tasks": [
    { "Name": "Design mockups", "IsCompleted": true },
    { "Name": "Implement feature", "IsCompleted": false },
    { "Name": "Write tests", "IsCompleted": true }
  ]
}

Output:

- Design mockups: ☑
- Implement feature: ☐
- Write tests: ☑

In Conditionals

Use format specifiers within conditional blocks.

Template:

{{#if ShowStatus}}
Account Status: {{IsActive:active}}
{{/if}}

C# Data:

var data = new Dictionary<string, object>
{
    ["ShowStatus"] = true,
    ["IsActive"] = true
};

JSON Data:

{
  "ShowStatus": true,
  "IsActive": true
}

Output:

Account Status: Active

Localization Support

Format specifiers automatically adapt to the culture you specify in PlaceholderReplacementOptions. Setting Culture is enough: the built-in boolean formatters (yesno, truefalse, onoff, enabled, active) use the same culture. A custom BooleanFormatterRegistry uses the culture passed to its own constructor (English when none is passed).

German (de-DE)

C# Code:

var options = new PlaceholderReplacementOptions
{
    Culture = new CultureInfo("de-DE")
};
var processor = new DocumentTemplateProcessor(options);

Template:

Bestätigt: {{IsConfirmed:yesno}}

Data (C# or JSON):

{
  "IsConfirmed": true
}

Output:

Bestätigt: Ja

French (fr-FR)

C# Code:

var options = new PlaceholderReplacementOptions
{
    Culture = new CultureInfo("fr-FR")
};
var processor = new DocumentTemplateProcessor(options);

Template:

Confirmé: {{IsConfirmed:yesno}}

Output:

Confirmé: Oui

Spanish (es-ES)

C# Code:

var options = new PlaceholderReplacementOptions
{
    Culture = new CultureInfo("es-ES")
};
var processor = new DocumentTemplateProcessor(options);

Template:

Confirmado: {{IsConfirmed:yesno}}

Output:

Confirmado: Sí

Supported Languages

The word-based boolean formatters are translated for these languages (selected by the culture's language; all other languages use English):

Language	yesno	truefalse	onoff	enabled	active
English (default)	Yes / No	True / False	On / Off	Enabled / Disabled	Active / Inactive
German (de)	Ja / Nein	Wahr / Falsch	Ein / Aus	Aktiviert / Deaktiviert	Aktiv / Inaktiv
French (fr)	Oui / Non	Vrai / Faux	Activé / Désactivé	Activé / Désactivé	Actif / Inactif
Spanish (es)	Sí / No	Verdadero / Falso	Encendido / Apagado	Habilitado / Deshabilitado	Activo / Inactivo
Italian (it)	Sì / No	Vero / Falso	Acceso / Spento	Abilitato / Disabilitato	Attivo / Inattivo
Portuguese (pt)	Sim / Não	Verdadeiro / Falso	Ligado / Desligado	Ativado / Desativado	Ativo / Inativo
Dutch (nl)	Ja / Nee	Waar / Onwaar	Aan / Uit	Ingeschakeld / Uitgeschakeld	Actief / Inactief
Polish (pl)	Tak / Nie	Prawda / Fałsz	Włączone / Wyłączone	Włączone / Wyłączone	Aktywny / Nieaktywny
Russian (ru)	Да / Нет	Истина / Ложь	Вкл / Выкл	Включено / Отключено	Активно / Неактивно
Japanese (ja)	はい / いいえ	English	English	English	English
Chinese (zh)	是 / 否	English	English	English	English

Symbol-based formatters (checkbox, checkmark, check) are culture-independent.

Custom Formatters

You can create custom boolean formatters for your specific needs.

Creating a Custom Formatter

C# Code:

// Create a registry
var registry = new BooleanFormatterRegistry();

// Register a custom formatter
registry.Register("thumbs", new BooleanFormatter("👍", "👎"));

// Use in options
var options = new PlaceholderReplacementOptions
{
    BooleanFormatterRegistry = registry
};
var processor = new DocumentTemplateProcessor(options);

Template:

User feedback: {{IsPositive:thumbs}}

Data:

{
  "IsPositive": true
}

Output:

User feedback: 👍

Multiple Custom Formatters

C# Code:

var registry = new BooleanFormatterRegistry();

// Register multiple custom formatters
registry.Register("thumbs", new BooleanFormatter("👍", "👎"));
registry.Register("traffic", new BooleanFormatter("🟢", "🔴"));
registry.Register("stars", new BooleanFormatter("⭐", "☆"));

var options = new PlaceholderReplacementOptions
{
    BooleanFormatterRegistry = registry
};
var processor = new DocumentTemplateProcessor(options);

Template:

Feedback: {{IsPositive:thumbs}}
Status: {{IsOperational:traffic}}
Featured: {{IsFeatured:stars}}

Data:

{
  "IsPositive": true,
  "IsOperational": false,
  "IsFeatured": true
}

Output:

Feedback: 👍
Status: 🔴
Featured: ⭐

Advanced Usage

Combining with Expressions

Format specifiers can be combined with boolean expressions for powerful conditional formatting.

See the Boolean Expressions Guide for details.

Quick Example:

Template:

Eligible: {{(Age >= 18 and HasLicense):yesno}}

Data:

{
  "Age": 20,
  "HasLicense": true
}

Output:

Eligible: Yes

Specifier and Value Type Mismatch

A specifier that does not fit the value's type is ignored, and the value is rendered normally. Boolean specifiers only apply to booleans, string specifiers to text, and so on.

Template:

Name: {{Name:checkbox}}
Count: {{Count:yesno}}

Data:

{
  "Name": "Test",
  "Count": 42
}

Output:

Name: Test
Count: 42

Case Insensitivity

Format specifier names are case-insensitive.

All of these are equivalent: - {{IsActive:checkbox}} - {{IsActive:CHECKBOX}} - {{IsActive:CheckBox}} - {{IsActive:ChEcKbOx}}

Unknown Formatters

If you specify a formatter that doesn't exist, the value is rendered with its default formatting (True/False for booleans).

Template:

Status: {{IsActive:unknownformat}}

Data:

{
  "IsActive": true
}

Output:

Status: True

Best Practices

1. Choose Appropriate Formatters

Match the formatter to your document's purpose: - checkbox - Task lists, checklists, forms - yesno - Questions, approvals, confirmations - checkmark - Validation results, requirements met - onoff - Settings, switches, toggles - enabled - Feature flags, capabilities - active - Account status, subscriptions

2. Be Consistent

Use the same formatter for similar concepts throughout your document.

Good:

Task 1: {{Task1.IsCompleted:checkbox}}
Task 2: {{Task2.IsCompleted:checkbox}}
Task 3: {{Task3.IsCompleted:checkbox}}

Avoid:

Task 1: {{Task1.IsCompleted:checkbox}}
Task 2: {{Task2.IsCompleted:yesno}}
Task 3: {{Task3.IsCompleted:checkmark}}

3. Consider Your Audience

• Business users - Prefer text-based formats (yesno, enabled, active)
• Technical users - Symbols work well (checkbox, checkmark)
• International - Set up proper localization

4. Use Symbols Wisely

Symbol-based formatters (checkbox, checkmark) render well in most contexts, but verify they display correctly in your target output format (Word, PDF, etc.).

5. Document Custom Formatters

If you create custom formatters, document their meaning for template authors:

// thumbs: 👍 for positive feedback, 👎 for negative
registry.Register("thumbs", new BooleanFormatter("👍", "👎"));

// priority: 🔴 for high priority, 🟢 for normal
registry.Register("priority", new BooleanFormatter("🔴", "🟢"));

Real-World Examples

Project Status Report

Template:

Project Status Report
=====================

Tasks:
{{#foreach Tasks}}
- {{Name}}: {{IsCompleted:checkbox}}
{{/foreach}}

Milestones:
{{#foreach Milestones}}
- {{Name}}: {{IsReached:checkmark}}
{{/foreach}}

Budget Approved: {{BudgetApproved:yesno}}
Team Active: {{TeamActive:active}}

Data:

{
  "Tasks": [
    { "Name": "Requirements gathering", "IsCompleted": true },
    { "Name": "Design phase", "IsCompleted": true },
    { "Name": "Development", "IsCompleted": false },
    { "Name": "Testing", "IsCompleted": false }
  ],
  "Milestones": [
    { "Name": "Project kickoff", "IsReached": true },
    { "Name": "Alpha release", "IsReached": false },
    { "Name": "Beta release", "IsReached": false }
  ],
  "BudgetApproved": true,
  "TeamActive": true
}

Employee Checklist

Template:

Employee Onboarding Checklist
==============================

Employee: {{Employee.Name}}
Department: {{Employee.Department}}

Required Documents:
- ID Verified: {{Documents.IDVerified:checkbox}}
- Background Check: {{Documents.BackgroundCheck:checkbox}}
- Signed Contract: {{Documents.ContractSigned:checkbox}}

System Access:
- Email Account: {{Access.Email:enabled}}
- VPN Access: {{Access.VPN:enabled}}
- Building Access: {{Access.Building:enabled}}

Training Complete: {{Training.Complete:yesno}}

Data:

{
  "Employee": {
    "Name": "Sarah Johnson",
    "Department": "Engineering"
  },
  "Documents": {
    "IDVerified": true,
    "BackgroundCheck": true,
    "ContractSigned": true
  },
  "Access": {
    "Email": true,
    "VPN": true,
    "Building": false
  },
  "Training": {
    "Complete": false
  }
}

Service Health Dashboard

Template:

Service Health Dashboard
========================

Core Services:
{{#foreach Services}}
- {{Name}}: {{IsOperational:traffic}}  {{IsOperational:active}}
{{/foreach}}

Automated Backups: {{BackupsEnabled:onoff}}
Monitoring: {{MonitoringActive:enabled}}

C# Code (with custom formatter):

var registry = new BooleanFormatterRegistry();
registry.Register("traffic", new BooleanFormatter("🟢", "🔴"));

var options = new PlaceholderReplacementOptions
{
    BooleanFormatterRegistry = registry
};
var processor = new DocumentTemplateProcessor(options);

Data:

{
  "Services": [
    { "Name": "API Gateway", "IsOperational": true },
    { "Name": "Database", "IsOperational": true },
    { "Name": "Cache Server", "IsOperational": false },
    { "Name": "Message Queue", "IsOperational": true }
  ],
  "BackupsEnabled": true,
  "MonitoringActive": true
}

Summary

Format specifiers provide a powerful way to control value presentation in your documents:

• ✅ String formatters (:uppercase, :lowercase) and :raw (no markdown)
• ✅ 7 built-in boolean formatters (checkbox, yesno, checkmark, truefalse, onoff, enabled, active) plus the check alias
• ✅ Currency formatting with locale support (:currency)
• ✅ Flexible number formatting with .NET format strings (:number:N2, :number:F3, :number:P2)
• ✅ Date formatting with .NET format strings (:date:yyyy-MM-dd, :date:MMMM d, yyyy)
• ✅ Automatic localization support
• ✅ Custom formatter registration
• ✅ Works with nested properties, arrays, loops, and conditionals
• ✅ Combines with boolean expressions
• ✅ Case-insensitive format names
• ✅ Same data works with C# Dictionaries or JSON

For more advanced usage, see: - Boolean Expressions Guide - Combine expressions with formatters - API Reference - Complete API documentation - FAQ - Common questions and answers