Module TvaNdf

From Dolibarr ERP CRM Wiki
Jump to navigation Jump to search

Return to developer
documentation index

File Doc dev.png

Return to user
documentation index
File Doc user.png

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

  1. Download module_tvandf-x.y.z.zip (ZIP root = single tvandf/ directory)
  2. Home → Setup → Modules → Deploy/Import external module
  3. Activate TVANDF/'TvaNdf' module
  4. Verify extrafield creation: Setup → Dictionaries → Expense report lines - Extra fields
  5. 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

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.

See Also

Retrieved from "https://wiki.dolibarr.org/index.php?title=Module_TvaNdf&oldid=66071"