190 lines
5.5 KiB
Markdown
190 lines
5.5 KiB
Markdown
# XML Template Usage Guide
|
|
|
|
## 🎯 **How Templates Work**
|
|
|
|
The XML template system preserves your document structure while replacing `<pack_content>` sections with data from your CSV file.
|
|
|
|
### **Processing Logic**
|
|
|
|
1. **PRESERVED**: All XML content except `<pack_content>` sections
|
|
2. **REMOVED**: All existing `<pack_content>` sections (if any)
|
|
3. **INSERTED**: New `<pack_content>` sections from CSV data before `</Document>`
|
|
|
|
---
|
|
|
|
## 📋 **Template Examples**
|
|
|
|
### **1. Minimal Template (No Existing Pack Content)**
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<unit_pack document_id="EXAMPLE_ID" VerForm="1.0">
|
|
<Document operation_date_time="2024-01-01T00:00:00+00:00" document_number="EXAMPLE_DOC">
|
|
<organisation>
|
|
<id_info>
|
|
<LP_info org_name="YOUR_COMPANY" LP_TIN="1234567890" RRC="123456789" />
|
|
</id_info>
|
|
<Address>
|
|
<location_address country_code="643" text_address="Your Address" />
|
|
</Address>
|
|
<contacts phone_number="123456789" email="your@email.com" />
|
|
</organisation>
|
|
|
|
<!-- CSV data will be inserted here automatically -->
|
|
|
|
</Document>
|
|
</unit_pack>
|
|
```
|
|
|
|
**Result**: CSV data gets inserted before `</Document>` tag.
|
|
|
|
### **2. Template with Existing Pack Content**
|
|
|
|
```xml
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<unit_pack document_id="EXAMPLE_WITH_EXISTING" VerForm="1.0">
|
|
<Document operation_date_time="2024-01-01T00:00:00+00:00" document_number="EXAMPLE_DOC">
|
|
<organisation>
|
|
<id_info>
|
|
<LP_info org_name="Test Company" LP_TIN="1234567890" RRC="123456789" />
|
|
</id_info>
|
|
</organisation>
|
|
|
|
<!-- These existing pack_content sections will be REMOVED and replaced -->
|
|
<pack_content>
|
|
<pack_code><![CDATA[OLD_PACK_CODE_1]]></pack_code>
|
|
<cis><![CDATA[OLD_CIS_1]]></cis>
|
|
<cis><![CDATA[OLD_CIS_2]]></cis>
|
|
</pack_content>
|
|
<pack_content>
|
|
<pack_code><![CDATA[OLD_PACK_CODE_2]]></pack_code>
|
|
<cis><![CDATA[OLD_CIS_3]]></cis>
|
|
</pack_content>
|
|
|
|
<!-- Additional sections after pack_content are preserved -->
|
|
<additional_info>
|
|
<note>This section will be preserved</note>
|
|
</additional_info>
|
|
|
|
</Document>
|
|
</unit_pack>
|
|
```
|
|
|
|
**Result**: Old `<pack_content>` sections are removed, new ones from CSV are inserted, but `<additional_info>` is preserved.
|
|
|
|
---
|
|
|
|
## 🔧 **Template Customization**
|
|
|
|
### **What You Can Customize**
|
|
|
|
✅ **Document attributes**: `document_id`, `VerForm`, `file_date_time`, etc.
|
|
✅ **Organisation information**: Company name, TIN, address, contacts
|
|
✅ **Additional XML sections**: Any custom elements outside `<pack_content>`
|
|
✅ **XML structure**: Different document layouts
|
|
|
|
### **What Gets Replaced**
|
|
|
|
❌ **All `<pack_content>` sections** - These are completely replaced with CSV data
|
|
❌ **Content inside `<pack_content>`** - `<pack_code>` and `<cis>` elements
|
|
|
|
---
|
|
|
|
## 📊 **Generated Pack Content Structure**
|
|
|
|
Each SET CIS from your CSV becomes a `<pack_content>` section:
|
|
|
|
```xml
|
|
<pack_content>
|
|
<pack_code><![CDATA[SET_CIS_VALUE]]></pack_code>
|
|
<cis><![CDATA[CIS_CODE_1]]></cis>
|
|
<cis><![CDATA[CIS_CODE_2]]></cis>
|
|
<cis><![CDATA[CIS_CODE_3]]></cis>
|
|
<!-- ... one <cis> element per "Код" value for this SET CIS -->
|
|
</pack_content>
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 **Best Practices**
|
|
|
|
### **1. Use Placeholder Values**
|
|
```xml
|
|
<organisation>
|
|
<id_info>
|
|
<LP_info org_name="YOUR_COMPANY_NAME" LP_TIN="YOUR_TIN" RRC="YOUR_RRC" />
|
|
</id_info>
|
|
</organisation>
|
|
```
|
|
|
|
### **2. Add Comments for Clarity**
|
|
```xml
|
|
<!-- This section will be preserved -->
|
|
<organisation>
|
|
<!-- Company details -->
|
|
</organisation>
|
|
|
|
<!-- Pack content will be inserted here -->
|
|
```
|
|
|
|
### **3. Include All Required Sections**
|
|
```xml
|
|
<unit_pack document_id="..." VerForm="..." file_date_time="..." VerProg="...">
|
|
<Document operation_date_time="..." document_number="...">
|
|
<organisation>...</organisation>
|
|
<!-- Pack content goes here -->
|
|
</Document>
|
|
</unit_pack>
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 **Common Use Cases**
|
|
|
|
### **1. Different Companies**
|
|
Create templates for different organizations:
|
|
```bash
|
|
python xml_generator.py data.csv template_company_a.xml -o output_a.xml
|
|
python xml_generator.py data.csv template_company_b.xml -o output_b.xml
|
|
```
|
|
|
|
### **2. Different Document Types**
|
|
Use different templates for various document formats:
|
|
```bash
|
|
python xml_generator.py data.csv template_invoice.xml -o invoice.xml
|
|
python xml_generator.py data.csv template_shipment.xml -o shipment.xml
|
|
```
|
|
|
|
### **3. Testing with Sample Data**
|
|
Keep a template with sample data for testing:
|
|
```xml
|
|
<pack_content>
|
|
<pack_code><![CDATA[SAMPLE_PACK_CODE]]></pack_code>
|
|
<cis><![CDATA[SAMPLE_CIS_1]]></cis>
|
|
<cis><![CDATA[SAMPLE_CIS_2]]></cis>
|
|
</pack_content>
|
|
```
|
|
|
|
---
|
|
|
|
## ⚠️ **Important Notes**
|
|
|
|
1. **XML Validity**: Ensure your template is valid XML
|
|
2. **Encoding**: Use UTF-8 encoding for proper character handling
|
|
3. **CDATA Sections**: The tool automatically wraps content in `<![CDATA[...]]>`
|
|
4. **Special Characters**: XML entities are automatically escaped
|
|
5. **Document Structure**: Must have `<Document>` and `</Document>` tags
|
|
|
|
---
|
|
|
|
## 🔍 **Testing Your Template**
|
|
|
|
Use dry-run mode to verify your template works:
|
|
```bash
|
|
python xml_generator.py --dry-run your_data.csv your_template.xml
|
|
```
|
|
|
|
Generate to stdout for quick inspection:
|
|
```bash
|
|
python xml_generator.py your_data.csv your_template.xml
|
|
``` |