panel/docs/features/DOCX_TEMPLATES.md

DOCX Template System

This system allows you to generate DOCX documents by filling templates with project data.

How to Create Templates

1. Create a DOCX Template: Use Microsoft Word or any DOCX editor to create your template.

2. Add Placeholders: Use single curly braces {variableName} to mark where data should be inserted. Available variables:

Available Variables (with duplicates for repeated use)

Project Information

• {project_name}, {project_name_1}, {project_name_2}, {project_name_3} - Project name
• {project_number}, {project_number_1}, {project_number_2} - Project number
• {address}, {address_1}, {address_2} - Project address
• {city}, {city_1}, {city_2} - City
• {plot} - Plot number
• {district} - District
• {unit} - Unit
• {investment_number} - Investment number
• {wp} - WP number
• {coordinates} - GPS coordinates
• {notes} - Project notes

Processed/Transformed Fields

• {investment_number_short} - Last part of investment number after last dash (e.g., "1234567" from "I-BC-DE-1234567")
• {project_number_short} - Last part of project number after last dash
• {project_name_upper} - Project name in uppercase
• {project_name_lower} - Project name in lowercase
• {city_upper} - City name in uppercase
• {customer_upper} - Customer name in uppercase

Contract Information

• {contract_number} - Contract number
• {customer_contract_number} - Customer contract number
• {customer}, {customer_1}, {customer_2} - Customer name
• {investor} - Investor name

Dates

• {finish_date} - Finish date (formatted)
• {completion_date} - Completion date (formatted)
• {today_date} - Today's date

Project Type & Status

• {project_type} - Project type (design/construction/design+construction)
• {project_status} - Project status

Financial

• {wartosc_zlecenia}, {wartosc_zlecenia_1}, {wartosc_zlecenia_2} - Contract value

Standard Custom Fields (Pre-filled but Editable)

• {zk} - ZK field
• {nr_zk} - ZK number
• {kabel} - Cable information
• {dlugosc} - Length
• {data_wykonania} - Execution date
• {st_nr} - Station number
• {obw} - Circuit
• {wp_short} - Short WP reference
• {plomba} - Seal/plomb information

Example Template Content

Project Report

Project Name: {project_name} ({project_name_upper})
Project Number: {project_number} (Short: {project_number_short})
Location: {city_upper}, {address}

Investment Details:
Full Investment Number: {investment_number}
Short Investment Number: {investment_number_short}

Contract Details:
Contract Number: {contract_number}
Customer: {customer} ({customer_upper})
Value: {wartosc_zlecenia} PLN

Custom Information:
Meeting Notes: {meeting_notes}
Special Instructions: {special_instructions}
Additional Comments: {additional_comments}

Technical Details:
ZK: {zk}
ZK Number: {nr_zk}
Cable: {kabel}
Length: {dlugosc}
Execution Date: {data_wykonania}
Station Number: {st_nr}
Circuit: {obw}
WP Short: {wp_short}
Seal: {plomba}

Primary Contact:
Name: {primary_contact}
Phone: {primary_contact_phone}
Email: {primary_contact_email}

Generated on: {today_date}

Uploading Templates

1. Go to the Templates page (/templates)
2. Click "Add Template"
3. Provide a name and description
4. Upload your DOCX file
5. The template will be available for generating documents

Generating Documents

1. Open any project page
2. In the sidebar, find the "Generate Document" section
3. Select a template from the dropdown
4. Optional: Click "Pokaż dodatkowe pola" to add custom data
5. Fill in the standard fields (zk, nr_zk, kabel, etc.) and any additional custom fields
6. Click "Generate Document"
7. The filled document will be downloaded automatically with filename: {template_name}_{project_name}_{timestamp}.docx

Custom Data Fields

During document generation, you can add custom data that will be merged with the project data:

Standard Fields (Pre-filled but Fully Editable)

These fields are pre-filled with common names but can be modified or removed:

• zk, nr_zk, kabel, dlugosc, data_wykonania, st_nr, obw, wp_short, plomba

Additional Custom Fields

• Custom fields override project data if they have the same name
• Use descriptive names like meeting_notes, special_instructions, custom_date
• Custom fields are available in templates as {custom_field_name}
• Empty custom fields are ignored
• All fields can be removed if not needed

Example Custom Fields:

• meeting_notes: "Please bring project documentation"
• special_instructions: "Use company letterhead"
• custom_date: "2025-01-15"
• additional_comments: "Follow up required"

Template Syntax

The system uses docxtemplater library which supports:

• Simple variable replacement: {variable}
• Loops: {#contacts}{name}{/contacts}
• Conditions: {#primary_contact}Primary: {name}{/primary_contact}
• Formatting and styling from your DOCX template is preserved

Data Processing & Transformations

The system automatically provides processed versions of common fields:

• Short codes: {investment_number_short} extracts the last segment after dashes (e.g., "1234567" from "I-BC-DE-1234567")
• Case transformations: {project_name_upper}, {city_upper}, {customer_upper} for uppercase versions
• Duplicate fields: Multiple versions of the same field for repeated use ({project_name_1}, {project_name_2}, etc.)

If you need additional transformations (like extracting different parts of codes, custom formatting, calculations, etc.), please let us know and we can add them to the system.

Tips

• Test your templates with sample data first
• Use descriptive variable names
• Keep formatting simple for best results
• Save templates with .docx extension only
• Maximum file size: 10MB
• For repeated information: If you need the same data to appear multiple times, create unique placeholders like {project_name_header} and {project_name_footer} and provide the same value for both

Storage & Persistence

Templates are stored in two locations for persistence in Docker environments:

Database Storage

• Location: data/database.sqlite (table: docx_templates)
• Content: Template metadata (name, description, file paths, timestamps)
• Persistence: Handled by Docker volume mount ./data:/app/data

File Storage

• Location: templates/ (host) → /app/templates/ (container)
• Content: Actual DOCX template files
• Persistence: Handled by Docker volume mount ./templates:/app/templates
• Web Access: Files are served via /api/templates/download/{filename}

Docker Volume Mounts

Both development and production Docker setups include volume mounts to ensure template persistence across container restarts:

volumes:
  - ./data:/app/data                    # Database
  - ./templates:/app/templates          # Template files
  - ./uploads:/app/public/uploads       # Other uploads
  - ./backups:/app/backups              # Backup files

🔧 Troubleshooting

Common Issues

Problem: "Duplicate tag" error during generation

• Cause: Using the same placeholder multiple times (e.g., {project_name} twice)
• Solution: Use numbered variants like {project_name}, {project_name_1}, {project_name_2} OR add the same value to custom fields with different names

Problem: Template not rendering correctly

• Cause: Invalid placeholder syntax
• Solution: Ensure all placeholders use single curly braces {variable} (not double {{}})
• Verify: Check for typos in variable names

Problem: Missing data in generated document

• Cause: Project missing required fields or custom data not provided
• Solution: Fill in all required project information or provide custom data during generation
• Check: Review project details before generating

Problem: Formatting lost in generated document

• Cause: Complex Word formatting or incompatible styles
• Solution:
  • Simplify template formatting
  • Avoid complex tables or text boxes
  • Use basic styles (bold, italic, underline work best)
  • Test with minimal formatting first

Problem: Generated file not downloading

• Cause: Browser popup blocker or network issue
• Solution:
  • Allow popups for this site
  • Check browser console for errors (F12)
  • Try different browser
  • Check file size < 10MB

Problem: Template upload fails

• Cause: File too large or invalid format
• Solution:
  • Ensure file is .docx format (not .doc)
  • File size must be under 10MB
  • Re-save file in Word to fix corruption
  • Check file isn't password-protected

Problem: Custom fields not appearing

• Cause: Field name mismatch between template and custom data
• Solution:
  • Ensure exact match (case-sensitive)
  • Example: {meeting_notes} in template requires meeting_notes in custom data
  • Check for spaces in field names

Problem: Dates not formatted correctly

• Cause: Date format differences
• Solution: Dates are auto-formatted as YYYY-MM-DD
• Tip: Use {today_date} for current date

Getting Help

If you encounter other issues:

1. Check browser console (F12) for error messages
2. Verify template file is valid .docx
3. Test with simpler template first
4. Contact system administrator with error details

---

📋 Quick Reference

File Limits

• Maximum template size: 10MB
• Supported format: .docx only
• Unlimited templates per project

Available Endpoints

• GET /api/templates - List all templates
• POST /api/templates - Upload new template
• POST /api/templates/generate - Generate document
• GET /api/templates/download/{filename} - Download template

Best Practices

✅ Test templates with sample data first
✅ Use descriptive placeholder names
✅ Keep formatting simple
✅ Use numbered variants for repeated data
✅ Provide meaningful template descriptions
❌ Don't use same placeholder twice
❌ Don't use complex Word features (macros, forms)
❌ Don't upload non-.docx files

---

See Also: Main README | API Documentation