177 lines
6.4 KiB
Markdown
177 lines
6.4 KiB
Markdown
# 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
|
|
|
|
## 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 |