Frank Cools c471defd25 Implement minor version system for template management

- Add major.minor version format (30.1)
- Keep government version as major number (30)
- Use minor version for fixes and improvements (.1, .2, .3)
- Update manifest.json with minor version system
- Add practical examples to maintenance manual
- Enable automatic updates for template fixes
- Maintain government version compliance

2025-10-08 01:26:12 +02:00

8.7 KiB

Raw Blame History

Template Maintenance Manual

DeclarationTVA Module - Official Template Management

Overview

This manual explains how to maintain and update the official CA-3 template for the DeclarationTVA module. The system supports both online template updates and local template management.

🏗️ Template System Overview

How It Works

Official Template: Stored in templates/declarationtva/ca3_official_template.pdf
Custom Templates: Users can upload custom templates (stored as ca3_custom_template.pdf)
Version Control: Template versions are managed through manifest.json
Online Updates: Other installations can check for template updates via Gitea

Key Files

templates/declarationtva/ca3_official_template.pdf - Official template file
templates/manifest.json - Version and update information
core/class/declarationtva_pdf.class.php - Template management logic

🔄 Updating the Official Template

Step 1: Prepare Your New Template

Obtain the new official template (e.g., from government sources)
Ensure it's a valid PDF and follows the expected format
Name it appropriately (e.g., 3310-ca3-sd_4931.pdf)

Step 2: Replace the Template File

# Navigate to the module directory
cd /path/to/dolibarr/htdocs/custom/declarationtva

# Replace the official template
cp /path/to/your/new/template.pdf templates/declarationtva/ca3_official_template.pdf

Step 3: Update Version Information (if needed)

If this is a new version of the template, update the version in the code:

File: core/class/declarationtva_pdf.class.php

// Line 67 - Update the version number
public $template_version = '30';  // Change to new version if needed

File: templates/manifest.json

{
  "templates": {
    "ca3": {
      "current_version": "30",  // Update if new version
      "document_number": "10963*30",  // Update document number if changed
      "description": "Official CA-3 VAT Declaration Template",
      "releases": {
        "30": {
          "download_url": "https://git.covago.com/frank/DeclarationTVA/raw/branch/main/templates/declarationtva/ca3_official_template.pdf",
          "checksum": "sha256:placeholder_checksum_here",
          "release_date": "2025-01-27",  // Update to current date
          "description": "Official CA-3 template version 30"
        }
      }
    }
  }
}

Step 4: Commit and Push Changes

# Add the new template file
git add templates/declarationtva/ca3_official_template.pdf

# Add any manifest changes
git add templates/manifest.json

# Add any code changes
git add core/class/declarationtva_pdf.class.php

# Commit the changes
git commit -m "Update official CA-3 template to version X

- Replace ca3_official_template.pdf with new government template
- Update version information in manifest.json
- Update template version in PDF class"

# Push to repository
git push origin main

📊 Version Management

When to Update Versions

Government Template Changes: When the official government template is updated
Format Changes: When the PDF structure changes significantly
Field Changes: When form fields are added, removed, or modified

Version Number Guidelines

Major Version: Use the official government version number (e.g., "30")
Minor Version: Use for fixes and improvements (e.g., "30.1", "30.2")
Format: major.minor (e.g., "30.1" for government version 30 with fixes)
Document Changes: Always document what changed in the commit message

Version Update Process

Check if template actually changed (compare with current version)
If changed: Update version numbers in both files
If unchanged: Just replace the file, keep same version

Minor Version System

The system uses a major.minor version format:

Major Version (30): Official government version
Minor Version (.1, .2, .3): Your fixes and improvements

Examples:

30.0 - Original government template
30.1 - Government template + field fixes
30.2 - Government template + additional improvements
31.0 - New government template (when available)

Benefits:

✅ Keep government version as major number
✅ Track your improvements with minor numbers
✅ Other installations get automatic updates
✅ Clear version history

Practical Example

Scenario: You need to fix field positioning in the official template

Current version: 30.1
Fix the template: Update PDF file with corrected fields
Update version: Change to 30.2
Update manifest: Add new release entry for 30.2
Commit and push: All installations will auto-update to 30.2

Result:

Government version stays 30 (major)
Your fixes are tracked as 30.2 (minor)
All installations get the improved template automatically

📁 File Structure

templates/
├── declarationtva/
│   ├── ca3_official_template.pdf    # Official template (replace this)
│   ├── ca3_custom_template.pdf      # User custom template (auto-generated)
│   └── README.md                    # Template documentation
├── manifest.json                    # Version and update info
└── README.md                       # Template system documentation

core/class/
└── declarationtva_pdf.class.php       # Template management logic

Key Files to Edit

1. Template File

Location: templates/declarationtva/ca3_official_template.pdf
Purpose: The actual PDF template file
Action: Replace with new template

2. Manifest File

Location: templates/manifest.json
Purpose: Version information and download URLs
Action: Update version, date, description if needed

3. PDF Class

Location: core/class/declarationtva_pdf.class.php
Purpose: Template version and management logic
Action: Update $template_version if new version

🔧 Troubleshooting

Common Issues

Template Not Updating

Problem: Users don't see template updates Solution:

Check if manifest.json is accessible online
Verify template file is in correct location
Clear any caches

Version Mismatch

Problem: Version numbers don't match Solution:

Ensure $template_version in PDF class matches manifest
Check that both files are committed and pushed

Template Upload Fails

Problem: Users can't upload custom templates Solution:

Check file permissions on template directory
Verify template path is correct
Check PHP upload limits

Debug Steps

Check Template Status: Go to Configuration → Template Management tab
Check Logs: Look for DeclarationTVA log entries
Verify Files: Ensure template files exist in correct locations
Test Reset: Try "REVENIR AU MODELE OFFICIEL" button

✅ Best Practices

Template Updates

Always test the new template before deploying
Keep backups of previous template versions
Document changes in commit messages
Update version numbers only when necessary

Version Management

Use government version numbers when available
Don't increment versions for minor fixes
Document version changes clearly
Test version detection after updates

File Management

Use descriptive commit messages
Tag important releases if needed
Keep template files organized
Document any special requirements

Testing

Test template upload functionality
Test template reset functionality
Test version detection on other installations
Verify online updates work correctly

🚀 Quick Update Checklist

When updating the official template:

Obtain new template file from official source
Replace templates/declarationtva/ca3_official_template.pdf
Check if version needs updating (usually keep same version)
Update manifest.json if version changed
Update PDF class if version changed
Test template functionality locally
Commit and push changes
Verify online access to template file
Test on other installations if possible

📞 Support

If you encounter issues:

Check the logs for error messages
Verify file permissions and paths
Test template functionality step by step
Check online accessibility of template files

Last updated: January 2025 Template system version: 2.3.0

8.7 KiB Raw Blame History