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

```yaml
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