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