# 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

### 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](../../README.md#-document-generation) | [API Documentation](../../README.md#templates-docx)