Module TvaNdf

Informations

Module name	Tvandf
Editor / Editeur	Alex BORDARAUD - Lysis https://lysis.net
Download or buy page / Page achat ou téléchargement
Status / Statut / Estado	Stable
Prerequisites / Prérequis	Dolibarr min version: 19.0
Last update date / Date mise à jour fiche / Fecha última actualización	2026-05-4
Note / Nota	Module ID: 142804 (List_of_modules_id)

TVANDF (technical module name: TvaNdf, directory tvandf, ID 142804) is a complementary Dolibarr module that transforms multi-VAT expense report entry. It adds a matrix interface allowing expense breakdown across multiple VAT rates with single supporting document for the entire group. Technically, the module uses extrafield tvandf_line_group to group generated standard Dolibarr lines, providing full compatibility with the native accounting engine.

Technical Architecture

Database Layer

No core table modifications: Uses existing expensereport_det structure
Extrafield integration: options_tvandf_line_group UUID links related lines
ECM compatibility: Standard fk_ecm_files reference sharing across group members
VAT dictionary binding: Dynamic rate columns from active c_tva entries filtered by mysoc->country_id

Hook Implementation

Context targeting: expensereportcard hook injection points
Asset loading: CSS/JS via printCommonFooter with bootstrap data attributes
Action buttons: addMoreActionsButtons for matrix toggle and add-line functions
Permission alignment: Respects core expensereport->creer rights and draft/refused workflow

Frontend Architecture

jQuery UI dialogs: Matrix forms with VAT rate columns and shared metadata fields
AJAX endpoints: ajax/expensereport_matrix.php for CRUD operations on line groups
File upload: Integrated ECM document attachment with progress feedback
View switching: Seamless toggle between matrix UI and standard Dolibarr line table

Description

English (Technical)

Core Problem: Standard Dolibarr expense workflow (expensereport/card.php) processes entries through ExpenseReportLine objects with one VAT rate per database row. Multi-rate receipts require multiple line insertions, duplicated context fields (fk_projet, date, comments), and separate ECM document associations following native fk_element patterns.

TVANDF Solution: Hook-based matrix UI overlaying the expense card context. Dynamic VAT grid populated from active tax dictionary, generating standard expense lines linked via technical extrafield. ECM integration uses shared document references across grouped lines.

Technical Benefits:

Non-intrusive integration: Hook system preserves core functionality
Native line compatibility: Generated ExpenseReportLine objects with standard fields
Extrafield grouping: UUID-based line association without schema modifications
Permission compliance: Core rights and status workflow preservation
ECM integration: Standard document management with reference sharing

Français (Technique)

Problème central : Le workflow natif Dolibarr (expensereport/card.php) traite les saisies via des objets ExpenseReportLine avec un taux de TVA par ligne en base. Les reçus multi-taux nécessitent plusieurs insertions de lignes, la duplication des champs de contexte (fk_projet, date, comments), et des associations ECM séparées suivant les patterns natifs fk_element.

Solution TVANDF : Interface matricielle basée sur hooks superposée au contexte de fiche de frais. Grille TVA dynamique alimentée depuis le dictionnaire fiscal actif, générant des lignes de frais standard reliées via extrafield technique. L'intégration ECM utilise des références de documents partagées entre lignes groupées.

Avantages techniques :

Intégration non-intrusive: Le système de hooks préserve les fonctionnalités du cœur
Compatibilité lignes natives: Objets ExpenseReportLine générés avec champs standards
Regroupement par extrafield: Association de lignes par UUID sans modifications de schéma
Conformité permissions: Préservation des droits et workflow de statut du cœur
Intégration ECM: Gestion documentaire standard avec partage de références

Fonctionnalités techniques

Matrix UI Components

Dynamic VAT columns: Auto-generated from c_tva active entries for company country
Shared metadata fields: Date, expense type, project, description, quantity, mileage
File attachment zone: ECM upload with fk_ecm_files reference storage
Calculation engine: Real-time HT/TTC totals with VAT breakdown display
Validation logic: Field requirement checks aligned with Dolibarr expense configuration

Backend Processing

Line group creation: UUID generation and extrafield population on insert
ECM file linking: Document association across all group member lines
Deletion cascade: Group-level removal with confirmation dialog
Edit synchronization: Metadata updates propagated to all grouped lines
Accounting integration: Standard line generation preserving native booking logic

Administration Interface

Setup tab: Prerequisites explanation, extrafield documentation, native settings link
About tab: Module metadata, version info, editor contact
Changelog tab: Version history from ChangeLog.md with markdown rendering
Dependency checks: Core expense report module validation

API Endpoints

AJAX Interface (`ajax/expensereport_matrix.php`)

get_state: Load existing line groups with VAT rate breakdown
save_group: Create/update line group with metadata and VAT amounts
delete_group: Remove line group and all associated lines
upload_piece: ECM file upload with progress tracking
get_vat_rates: Dynamic VAT rate list for company configuration

Security Model

Token validation: CSRF protection on all AJAX endpoints
Permission checks: expensereport->creer validation per operation
Entity filtering: MultiCompany support with proper data isolation
Status validation: Draft/refused state enforcement for edit operations

Installation and Configuration

Technical Requirements

Dolibarr version: 19.0+ (see modTvaNdf.class.php for exact version)
PHP version: 7.1+ with standard extensions
Database: Compatible with all Dolibarr-supported databases
Browser: JavaScript-enabled for matrix UI functionality
Dependencies: Core expense report module mandatory

Installation Process

Download module_tvandf-x.y.z.zip (ZIP root = single tvandf/ directory)
Home → Setup → Modules → Deploy/Import external module
Activate TVANDF/'TvaNdf' module
Verify extrafield creation: Setup → Dictionaries → Expense report lines - Extra fields
Configure VAT rates in Setup → Dictionaries → VAT for proper matrix columns

Configuration Notes

Extrafield preservation: Do not delete tvandf_line_group while using matrix features
VAT dictionary dependency: Active rates determine available matrix columns
ECM configuration: Standard Dolibarr document management settings apply
Permission setup: Standard expense report rights control matrix access

Developer Information

Module Structure

Core descriptor: core/modules/modTvaNdf.class.php
Hook implementation: class/actions_tvandf.class.php
Matrix logic: lib/tvandf_matrix.lib.php
AJAX handler: ajax/expensereport_matrix.php
Frontend assets: js/expensereport_matrix.js, css/expensereport_matrix.css

Customization Points

VAT rate filtering: Modify tvandf_matrix_list_vat_rates() for custom rate logic
Extrafield naming: TVANDF_EXTRA_LINE_GROUP constant in lib/tvandf.lib.php
UI labels: Translation files in langs/*/tvandf.lang
Matrix layout: CSS customization in css/expensereport_matrix.css

Extension Opportunities

Additional grouping fields: Extend extrafield structure for complex scenarios
Custom validation rules: Hook into save logic for business-specific constraints
Reporting integration: Matrix data available through standard Dolibarr line queries
API expansion: Additional endpoints for external integration needs

Compatibility and Limitations

Dolibarr Compatibility

Core versions: Tested on Dolibarr 19.0 through 21.x series
MultiCompany: Full support with entity-based data isolation
Accounting: Compatible with all standard accounting export formats
Themes: Responsive design adapts to standard Dolibarr themes

Known Limitations

JavaScript dependency: Matrix UI requires enabled JavaScript
Browser compatibility: Modern browsers required for optimal experience
Large VAT sets: Performance considerations with 15+ active VAT rates
Mobile optimization: Matrix interface optimized for desktop/tablet use

Support and Development

Professional Services

Installation assistance: Configuration and deployment support
Custom development: Module extensions and integrations
Training services: User and administrator training programs
Technical support: Issue resolution and optimization guidance

Community Resources

Documentation: Complete technical documentation in module doc/ directory
Issue tracking: Report bugs and feature requests to module maintainer
Version updates: Regular releases with Dolibarr compatibility updates
Code contributions: Community patches and improvements welcome

Contact Information

Developer: Alex BORDARAUD - Lysis
Website: https://lysis.net
License: GPLv3+
Module ID: 142804

Related Modules and Integration

Dolibarr Core Integration

ModuleExpensesReports: Core expense report functionality
ModuleECM: Document management system integration
ModuleMultiCompany: Multi-entity support compatibility
ModuleAccounting: Accounting export and journal integration

Complementary Modules

VAT management modules for enhanced tax handling
Project module integration for expense allocation
HR modules for approval workflow enhancement
Reporting modules for advanced expense analytics

Technical Reference

Database Schema Extensions

```sql -- Extrafield on expensereport_det table ALTER TABLE llx_expensereport_det_extrafields ADD COLUMN tvandf_line_group varchar(255); ```

Key PHP Classes

ActionsTvandf: Main hook implementation class
ExpenseReportLine: Native Dolibarr line object (preserved)
ExtraFields: Dolibarr extrafield management (extended)

JavaScript API

Matrix initialization: TvandfMatrix.init()
Group operations: TvandfMatrix.saveGroup(), TvandfMatrix.deleteGroup()
File upload: TvandfMatrix.uploadFile()

Configuration Constants

TVANDF_EXTRA_LINE_GROUP: Extrafield name constant
Module configuration accessible via $conf->tvandf global

Version History

See ChangeLog.md in module root for detailed version history and upgrade notes.