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

#### Contacts
- `{contacts}` - Array of contacts (use loops in advanced templates)
- `{primary_contact}` - Primary contact name
- `{primary_contact_phone}` - Primary contact phone
- `{primary_contact_email}` - Primary contact email

## 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}

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. Add any custom fields you need (e.g., `custom_note`, `additional_info`)
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:

- **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

### 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

## 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