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

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

Request body:
```json
{
  "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

```http
POST /api/templates/{template_id}/analyze
```

Analyzes template complexity and features used.

### Test Variable Formatting

```http
POST /api/templates/test-formatting
```

Test formatting without generating full document:
```json
{
  "variable_value": "1234.56",
  "format_spec": "currency:€:0"
}
```

## Example Template

Here's a complete example template showcasing advanced features:

```docx
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
```bash
sudo apt-get update
sudo apt-get install libreoffice
```

### Docker
Add to Dockerfile:
```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