changes
This commit is contained in:
HotSwapp
260
docs/ADVANCED_TEMPLATE_FEATURES.md
Normal file
260
docs/ADVANCED_TEMPLATE_FEATURES.md
Normal file
@@ -0,0 +1,260 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user