Templates et interface admin

Vavang Invoice intègre ses écrans d’administration via les Sylius Twig Hooks et les templates du bundle. Préférez une personnalisation au niveau du hook avant de copier des templates complets du plugin.

Hooks publics utilisés par le plugin

Le bundle contribue actuellement aux hooks suivants :

• sylius_invoice_admin.compliance_dashboard.index ;
• sylius_invoice_admin.compliance_document.index.

Les deux réutilisent la sidebar et la navbar standard de Sylius Admin et fournissent leur propre template de contenu.

Surcharge recommandée : remplacer la contribution du hook

L’application hôte peut remplacer la contribution content dans sa configuration Sylius Twig Hooks :

# config/packages/sylius_twig_hooks.yaml
sylius_twig_hooks:
    hooks:
        'sylius_invoice_admin.compliance_dashboard.index':
            content:
                template: 'admin/invoice/dashboard/content.html.twig'
                priority: 0

Cette approche couple l’application au nom de hook documenté plutôt qu’à la structure interne du fichier Twig d’origine.

Le hook de liste des documents peut être personnalisé de la même manière avec sylius_invoice_admin.compliance_document.index.

Surcharge d’un template de bundle

Le contenu par défaut du dashboard se trouve actuellement ici :

@SyliusInvoicePlugin/admin/dashboard/content.html.twig

Le mécanisme de surcharge des bundles Symfony permet de le masquer depuis l’application hôte via :

templates/bundles/SyliusInvoicePlugin/admin/dashboard/content.html.twig

La liste des documents de conformité utilise actuellement @SyliusInvoicePlugin/admin/dashboard/list_content.html.twig.

La copie complète d’un template présente un coût de BC plus élevé : markup, variables et structure des fragments peuvent évoluer même si la route et le hook restent stables. Réservez cette technique aux cas où le remplacement ou la composition par hook ne suffit pas.

Ce qu’il ne faut pas considérer comme stable

Ne considérez pas chaque fichier sous templates/admin/dashboard/ comme un contrat d’extension stable indépendant. Des fichiers tels que configuration.html.twig, errors.html.twig, health.html.twig ou les fragments de reporting restent des templates d’implémentation sauf mention explicite.

Checklist de montée de version

Après modification d’un hook ou surcharge d’un template de bundle :

1. rendez la route admin concernée dans un test d’intégration ;
2. vérifiez que les variables nécessaires existent toujours après montée de version du plugin ;
3. testez le clavier et le responsive ;
4. comparez votre surcharge avec le template amont avant d’accepter une nouvelle version du plugin.