panel/DOCX_TEMPLATES_README.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

• Duplicate tags error: Each placeholder can only be used once in the template. If you need the same information to appear multiple times, use unique placeholders like {project_name_1} and {project_name_2} with the same data value.
• Template not rendering: Check for syntax errors in placeholders
• Missing data: Ensure the project has the required information
• Formatting issues: Try simplifying the template formatting
• File not downloading: Check browser popup blockers