delphi-database/docs/ADVANCED_TEMPLATE_FEATURES.md

Advanced Template Features Documentation

This document explains the enhanced template system with advanced features like conditional sections, loops, rich variable formatting, and PDF generation.

Overview

The enhanced template system supports:

• Conditional Content Blocks - Show/hide content based on conditions
• Loop Functionality - Repeat content for data tables and lists
• Rich Variable Formatting - Apply formatting filters to variables
• Template Functions - Built-in functions for data manipulation
• PDF Generation - Convert DOCX templates to PDF using LibreOffice
• Advanced Variable Resolution - Enhanced variable processing with caching

Template Syntax

Basic Variables

{{ variable_name }}

Standard variable substitution from context or database.

Formatted Variables

{{ variable_name | format_spec }}

Apply formatting to variables:

• {{ amount | currency }} → $1,234.56
• {{ date | date:%m/%d/%Y }} → 12/25/2023
• {{ phone | phone }} → (555) 123-4567
• {{ text | upper }} → UPPERCASE TEXT

Conditional Sections

{% if condition %}
Content to show if condition is true
{% else %}
Content to show if condition is false (optional)
{% endif %}

Examples:

{% if CLIENT_BALANCE > 0 %}
Outstanding balance: {{ CLIENT_BALANCE | currency }}
{% else %}
Account is current
{% endif %}

Loop Sections

{% for item in collection %}
Content repeated for each item
Access item properties: {{ item.property }}
{% endfor %}

Loop variables available inside loops:

• {{ item_index }} - Current index (1-based)
• {{ item_index0 }} - Current index (0-based)
• {{ item_first }} - True if first item
• {{ item_last }} - True if last item
• {{ item_length }} - Total number of items

Example:

{% for payment in payments %}
{{ payment_index }}. {{ payment.date | date }} - {{ payment.amount | currency }}
{% endfor %}

Template Functions

{{ function_name(arg1, arg2) }}

Built-in functions:

• {{ format_currency(amount, "$", 2) }}
• {{ format_date(date, "%B %d, %Y") }}
• {{ math_add(value1, value2) }}
• {{ join(items, ", ") }}

Variable Formatting Options

Currency Formatting

Format	Example Input	Output
currency	1234.56	$1,234.56
currency:€	1234.56	€1,234.56
currency:$:0	1234.56	$1,235

Date Formatting

Format	Example Input	Output
date	2023-12-25	December 25, 2023
date:%m/%d/%Y	2023-12-25	12/25/2023
date:%B %d	2023-12-25	December 25

Number Formatting

Format	Example Input	Output
number	1234.5678	1,234.57
number:1	1234.5678	1,234.6
number:2:	1234.5678	1 234.57

Text Transformations

Format	Example Input	Output
upper	hello world	HELLO WORLD
lower	HELLO WORLD	hello world
title	hello world	Hello World
truncate:10	Very long text	Very lo...

API Endpoints

Generate Advanced Document

POST /api/templates/{template_id}/generate-advanced

Request body:

{
  "context": {
    "CLIENT_NAME": "John Doe",
    "AMOUNT": 1500.00,
    "payments": [
      {"date": "2023-01-15", "amount": 500.00},
      {"date": "2023-02-15", "amount": 1000.00}
    ]
  },
  "output_format": "PDF",
  "enable_conditionals": true,
  "enable_loops": true,
  "enable_formatting": true,
  "enable_functions": true
}

Analyze Template

POST /api/templates/{template_id}/analyze

Analyzes template complexity and features used.

Test Variable Formatting

POST /api/templates/test-formatting

Test formatting without generating full document:

{
  "variable_value": "1234.56",
  "format_spec": "currency:€:0"
}

Example Template

Here's a complete example template showcasing advanced features:

LEGAL INVOICE

Client: {{ CLIENT_NAME | title }}
Date: {{ TODAY | date }}

{% if CLIENT_BALANCE > 0 %}
NOTICE: Outstanding balance of {{ CLIENT_BALANCE | currency }}
{% endif %}

Services Provided:
{% for service in services %}
{{ service_index }}. {{ service.description }}
   Date: {{ service.date | date:%m/%d/%Y }}
   Hours: {{ service.hours | number:1 }}
   Rate: {{ service.rate | currency }}
   Amount: {{ service.amount | currency }}
{% endfor %}

Total: {{ format_currency(total_amount) }}

{% if payment_terms %}
Payment Terms: {{ payment_terms }}
{% else %}
Payment due within 30 days
{% endif %}

PDF Generation Setup

For PDF generation, LibreOffice must be installed on the server:

Ubuntu/Debian

sudo apt-get update
sudo apt-get install libreoffice

Docker

Add to Dockerfile:

RUN apt-get update && apt-get install -y libreoffice

Usage

Set output_format: "PDF" in the generation request.

Error Handling

The system gracefully handles errors:

• Missing variables - Listed in unresolved array
• Invalid conditions - Default to false
• Failed loops - Skip section
• PDF conversion errors - Fall back to DOCX
• Formatting errors - Return original value

Performance Considerations

• Variable caching - Expensive calculations are cached
• Template analysis - Analyze templates to optimize processing
• Conditional short-circuiting - Skip processing unused sections
• Loop optimization - Efficient handling of large datasets

Migration from Basic Templates

Existing templates continue to work unchanged. To use advanced features:

1. Add formatting to variables: {{ amount }} → {{ amount | currency }}
2. Add conditionals for optional content
3. Use loops for repeating data
4. Test with the analyze endpoint
5. Enable PDF output if needed

Security

• Safe evaluation - Template expressions run in restricted environment
• Input validation - All template inputs are validated
• Resource limits - Processing timeouts prevent infinite loops
• Access control - Template access follows existing permissions