Modèles PDF

L'écran Modèles PDF est la bibliothèque de mises en page PDF réutilisables utilisées par NomaUBL au moment du rendu d'une facture. Chaque mise en page est une ressource pdf-template enregistrée dans config-pdf.json ; les modèles de document désignent une mise en page par nom via leur propriété pdfTemplate — une même mise en page peut donc être partagée entre plusieurs documents.

La page couvre quatre opérations :

• gérer le catalogue (Ajouter / Importer / Copier / Supprimer) ;
• éditer une mise en page via l'éditeur visuel — un éditeur plein écran avec le catalogue des sections à gauche, un aperçu en direct au centre et un inspecteur à droite ;
• désigner un défaut pour les documents qui ne portent pas de mise en page explicite ;
• charger un XML de facture réel dans l'éditeur pour que l'aperçu et l'auto-complétion XPath s'alignent sur vos données.

La page fonctionne quel que soit le système source — JD Edwards, SAP, NetSuite ou ERP personnalisé. L'entrée utilisée est l'UBL 2.1 généré, et non le XML source.

Nouveauté en 2026.05.1

Les modèles PDF étaient auparavant édités en ligne sur la page Documents (onglet PDF Template) et stockés dans les propriétés du modèle de document. Ils sont désormais des ressources partageables à part entière, dotées de leur propre page. L'onglet de la page Documents existe toujours, mais il choisit désormais une mise en page par nom depuis le catalogue de cette page, au lieu de contenir le JSON en ligne.

---

Accès à la page

• Barre latérale → Gestion → Modèles PDF.
• La page liste toutes les mises en page du catalogue. L'entrée built-in est la mise en page par défaut livrée — en lecture seule, toujours présente comme valeur de repli.
• La mise en page par défaut courante — c'est-à-dire celle utilisée par tout document sans pdfTemplate explicite — est marquée d'une étoile jaune ★ dans la barre latérale.

---

Vue d'ensemble

La page comporte un catalogue à gauche qui liste les mises en page enregistrées, et un panneau de synthèse à droite pour la mise en page sélectionnée. L'édition d'une mise en page ouvre l'éditeur visuel — un éditeur plein écran à trois volets documenté dans Éditeur visuel plus bas — et la mise en page est enregistrée dans le catalogue sous un nom.

---

Résolution d'une mise en page

Au moment du rendu PDF d'une facture, NomaUBL parcourt une chaîne en trois temps pour choisir la mise en page :

1. Le modèle de document de la facture (lu depuis F564231.UHTMPL) a une propriété pdfTemplate — si elle est renseignée, c'est ce nom qui s'applique.
2. À défaut, c'est la propriété defaultPdfTemplate du modèle global qui s'applique — réglée sur cette page via le bouton Définir par défaut.
3. À défaut, la mise en page intégrée built-in s'applique — toujours présente, jamais supprimable.

Cette troisième étape est la valeur de repli : un environnement tout juste installé produit des PDF cohérents avant même qu'une mise en page soit créée.

---

Actions de la barre supérieure

La barre d'actions couvre le cycle de vie du catalogue et la désignation du défaut.

Action	Effet
Ouvrir l'éditeur visuel	Ouvre la mise en page sélectionnée dans l'éditeur visuel plein écran — palette à gauche, aperçu en direct au centre, inspecteur à droite. Surface d'édition principale.
Ajouter	Ouvre une modale qui demande un nom et une description. Crée une ressource pdf-template vide — l'ajout des sections se fait ensuite dans l'éditeur visuel.
Importer	Charge un fichier JSON produit par une autre instance (ou par l'action Exporter). Met à jour le modèle correspondant si le nom existe déjà, sinon le crée. Le nom réservé built-in est rejeté.
Copier	Duplique la mise en page sélectionnée sous un nouveau nom. La méthode la plus rapide pour dériver une variante à partir de built-in ou d'un modèle existant spécifique à un client.
Supprimer	Supprime la mise en page sélectionnée après confirmation. Bouton désactivé sur built-in.
Définir par défaut	Enregistre le nom de la mise en page sélectionnée dans global.defaultPdfTemplate. Tout document sans pdfTemplate explicite utilise alors cette mise en page.
Remettre par défaut	Vide global.defaultPdfTemplate, ce qui ramène la résolution sur built-in.

---

Le catalogue

La barre latérale liste toutes les mises en page enregistrées, plus la built-in livrée.

• built-in — épinglée en haut, en lecture seule, marquée d'un badge factory. Sa sélection ouvre l'éditeur en mode lecture seule, signalé par un bandeau. Copier est la seule manière d'en dériver une mise en page éditable.
• Marqueur ★ — la mise en page utilisée comme défaut pour les documents sans pdfTemplate explicite. Une seule mise en page a l'étoile à un instant donné.
• Description — libellé libre enregistré sur la ressource. Apparaît à la fois dans la barre latérale et dans le sélecteur PDF Template d'un modèle de document.

---

Éditeur visuel

Le bouton Ouvrir l'éditeur visuel ouvre la mise en page dans un éditeur plein écran à trois volets côte à côte — c'est la manière de référence pour éditer un pdf-template. L'ancien parcours (liste de sections + tiroirs par section, clic sur un bouton Aperçu qui ouvre une modale) disparaît ; l'éditeur regroupe tout sur un seul écran, aperçu toujours visible.

Les trois volets :

Volet	Contenu
Gauche — palette + liste des sections	Moitié haute : le catalogue des sections disponibles (En-tête, Parties, Tableau des lignes, Règlement, Notes, Bloc personnalisé, …). Un clic pour ajouter au modèle. Moitié basse : la liste ordonnée des sections du modèle. Un clic pour sélectionner ; glisser-déposer la poignée ⋮⋮ pour réordonner.
Centre — aperçu en direct	Rendu du modèle courant sur une facture d'exemple intégrée (ou sur le XML chargé par l'opérateur), regénéré à chaque modification — cocher une case, ajouter une section, modifier un nœud de bloc personnalisé : tout se reflète dans l'aperçu en quelques millisecondes. Un clic sur un bloc dans l'aperçu le sélectionne ; l'inspecteur à droite saute sur les options correspondantes.
Droite — inspecteur	Affiche les options de la section sélectionnée, regroupées par catégorie (Fournisseur, Métadonnées facture, Colonnes, …). Pour un Bloc personnalisé, c'est l'éditeur arborescent complet — texte, champ, ligne / colonne, répétition, condition — qui s'ouvre directement dans ce volet, avec auto-complétion XPath et choix de police / couleur / alignement par nœud.

Charger une vraie facture

Le bouton ↑ Charger XML en haut de l'éditeur accepte une vraie facture UBL (glisser-déposer ou sélecteur de fichier). Une fois chargée :

• L'aperçu en direct bascule immédiatement sur vos données.
• L'auto-complétion XPath de l'éditeur de bloc personnalisé utilise votre XML — les suggestions correspondent aux éléments réellement présents dans votre facture.

L'échantillon est conservé pour la session, pas avec le modèle. Rouvrir l'éditeur revient à la facture d'exemple intégrée.

Enregistrer et abandonner

Le bouton Enregistrer en haut à droite persiste le modèle directement depuis l'éditeur. Le bouton Fermer (✕) affiche un message de confirmation Abandonner / Annuler tant qu'il reste des modifications non enregistrées — impossible de fermer sans choisir. Abandonner écarte chaque modification depuis le dernier enregistrement ; Annuler maintient dans l'éditeur.

---

Deux types de sections

Une mise en page est une suite de sections. Deux familles cohabitent dans un même modèle.

Sections prédéfinies — éléments de mise en page éprouvés

Neuf sections prédéfinies réordonnables couvrent la forme standard d'un PDF de facture : Header, Parties, Agent, Line Table, Document Allowances, VAT Breakdown, Totals, Payment, Notes. Chacune s'appuie sur une classe Java qui rend la partie correspondante d'une facture EN 16931 ; l'utilisateur en règle la visibilité via les bascules par section dans le tiroir intégré.

Le tiroir regroupe les bascules par préfixe Catégorie · Nom et les présente en colonnes côte à côte qui reflètent la mise en page PDF — Header se lit comme METAS | SUPPLIERS, Line Table comme Group headers | Columns | Sub-details — au lieu d'une longue liste plate. Les bascules utilisent le composant Checkbox rond-bleu pour une cohérence visuelle en mode sombre.

Liste complète des bascules par section prédéfinie :

• Header — huit bascules META · … (numéro de facture, date d'émission, date d'échéance, références contrat / commande / acheteur, type de facture, profil ID), plus six bascules Supplier · … (adresse, SIREN, forme légale, TVA, téléphone, e-mail).
• Parties — boîtes Client et Livraison, avec bascules séparées pour SIREN, TVA, adresse, identifiant de localisation et un switch principal Show Delivery box (désactivé, la mise en page rend un bloc Client en colonne unique). La boîte Livraison affiche le nom du destinataire (repli sur ID: … si seul l'identifiant de site est renseigné), la rue complète, le code postal + ville et le pays — comme la boîte Client.
• Line Table — bascules d'en-tête de groupe (Delivery group, Page break per delivery, Document Reference group et, (2026.06.14), Group by customer order — un troisième bandeau sous ceux de la livraison et de la référence de document, indiquant l'ID de commande client référencée, BT-132), sept bascules de colonnes (Line #, Description, Quantity, Unit, Unit Price, Amount, Tax) et sept bascules de sous-détail pour les métadonnées de ligne (BT-127, BT-134/135, BT-156, BT-157, BT-158, remises / charges, propriétés additionnelles d'article). Le bandeau commande client suit les mêmes règles de réinitialisation que les autres : un changement de livraison ré-imprime les deux fils internes, un changement de référence de document ré-imprime le bandeau commande client.
• Document Allowances — bascules de colonnes pour type, motif, montant, taxe.
• VAT Breakdown — bascules de colonnes pour catégorie, taux, base imposable, montant de TVA (une colonne d'exemption apparaît automatiquement quand elle est présente).
• Totals — sept bascules de lignes couvrant la pile complète (Total HT, Allowances, Charges, Tax Exclusive, Total Tax, Total TTC, Amount Payable).
• Payment — bascules pour moyen de paiement / IBAN / BIC / mention de conditions de paiement.
• Notes — bascule unique pour développer les préfixes [PMD] / [PMT] à partir du catalogue note-types.

Sections block — composition libre pilotée par XPath

La nouvelle section block est une primitive pilotée par XPath qui permet de composer toute mise en page non couverte par les sections prédéfinies. Un block est un arbre de nœuds typés :

Type	Usage
text	Chaîne littérale.
field	Rend une valeur XPath, avec libellé inline optionnel et sélecteur de format — date, currency, number, percent.
image	Insère une image (logo, filigrane, signature).
spacer / hr	Espace vertical ou filet horizontal.
row / column	Conteneur avec contrôles align (start / center / end) et gap. align: end et align: center réduisent la ligne à environ 50 % pour qu'une paire libellé + valeur reste groupée plutôt qu'étirée sur toute la page.
repeat	XPath retournant une NodeList ; le child du block est rendu une fois par occurrence.
if	XPath retournant un booléen ; le child du block est rendu si vrai, masqué sinon.
table	Grille lignes × colonnes avec bordures de cellules optionnelles et ligne d'en-tête stylée. Définir xpath la fait itérer (une ligne par occurrence), les enfants servant de gabarit par ligne.
note	Un bloc Note (par code) — choisissez un code dans la liste de référence note-types ; le rendu repère le cbc:Note qui porte le marqueur #CODE# correspondant et affiche son corps sur place. Permet de désactiver la section Notes globale et de poser chaque note exactement où elle doit aller (en-tête, entre les parties, près des totaux, dans une colonne).

Plusieurs blocks peuvent coexister dans un même modèle — par exemple un pour des mentions légales françaises, un pour une table structurée de conditions de paiement, un pour un filigrane image. Chaque block a un name utilisateur affiché à côté de la ligne de section dans l'éditeur ; un modèle qui contient trois blocks se lit ainsi Block · payment-terms, Block · legal-mentions, Block · watermark.

Conventions XPath dans un block

• Le sélecteur garde les préfixes de namespace cbc: / cac: — requis par le moteur namespace-aware ; un XPath saisi à la main sans préfixe ne correspondra à rien.
• Les sélections sont émises en /*/<chemin-complet> pour être indépendantes de la racine du document (le même chemin s'applique à Invoice comme à CreditNote).
• À l'intérieur d'un ancêtre itérant (un repeat ou une table munie d'un xpath), le sélecteur supprime en plus le chemin de l'itérateur pour que les cellules enfants démarrent en XPath relatif (cbc:TaxAmount plutôt que /*/cac:TaxTotal/cac:TaxSubtotal/cbc:TaxAmount). Les gabarits de ligne restent ainsi portables quand l'itérateur change.

---

Éditeur arborescent des blocs personnalisés

Quand une section Bloc personnalisé est sélectionnée dans l'éditeur visuel, le volet de droite bascule du mode "cases à cocher" à un éditeur arborescent complet. Il regroupe tout ce dont un bloc a besoin au même endroit :

Zone du volet inspecteur	Rôle
Arbre	Vue indentée de tous les nœuds du bloc, avec une étiquette de type (text, field, repeat, table, …). Cliquer un nœud le sélectionne ; l'aperçu en direct au centre met en évidence la zone correspondante.
Barre d'outils de nœud	Ajout d'enfant / encapsulation / dégagement / suppression / déplacement haut-bas — opérations appliquées au nœud sélectionné. Mêmes opérations disponibles via raccourcis clavier.
Formulaire d'attributs	Formulaire d'attributs par type (XPath, libellé, format, alignement, gap, …) plus un sous-panneau Style couvrant police, graisse, taille, couleur, alignement et marges intérieures.
Sortie de secours JSON	Vue JSON brute du nœud courant — en lecture seule par défaut, Modifier JSON bascule en édition pour les cas avancés que le formulaire ne couvre pas.

Détail subtil mais important en haut du formulaire d'attributs : un sélecteur Type qui transforme le nœud sélectionné sur place — passage de column à repeat sans suppression / recréation. Les attributs compatibles (enfants, style) sont reportés par le helper transmuteKind. Même mécanisme pour le cas fréquent de promotion d'un bloc statique en bloc itérant une fois la forme des données identifiée. La liste déroulante du type de bloc est triée par ordre alphabétique.

L'aperçu au centre se regénère à chaque frappe — l'iframe reste montée et se met à jour sur place, l'opérateur voit le résultat sans clignotement quand il modifie un XPath ou une option de style. Le bouton ↑ Charger XML en haut de l'éditeur fournit un seul échantillon qui alimente l'auto-complétion XPath de chaque bloc du modèle.

---

Réglages du modèle — barre du constructeur

La barre du constructeur porte quelques réglages appliqués à toute la mise en page :

Réglage	Effet
Accent	La couleur d'accent des titres de section (CLIENT / LIVRAISON), du total mis en évidence, du soulignement de l'en-tête du tableau de lignes et du fond des lignes surlignées. Saisissez un hexa à 6 chiffres avec ou sans # ; la teinte de fond est dérivée automatiquement. Vide = bleu par défaut.
Date	Le format de date appliqué dans tout le PDF — dates d'émission, d'échéance, de période et de livraison par ligne. Valeurs : yyyy-MM-dd (défaut), dd/MM/yyyy, dd-MM-yyyy, MM/dd/yyyy, dd MMM yyyy, dd MMMM yyyy.
Afficher le logo	Dessine le logo de la société en haut du bloc fournisseur de la page 1. L'image vient du champ Chemin du logo dans Paramètres → Global → Traitement → PDF, où un Décalage X du logo (pt) la décale aussi horizontalement. PNG, JPG et GIF sont pris en charge.

---

Slots de section

Au-delà des bascules de préréglage, trois sections proposent des slots nommés, chacun contenant un arbre de blocs complet (texte, champ, ligne, colonne, tableau, répéter, si, note, …) édité sur place avec le même constructeur. Un slot place un bloc là où, sinon, aucun point d'ancrage n'existe, sans intercaler une section Bloc autonome entre deux sections natives :

Section	Slots
En-tête	Pied gauche (sous le bloc fournisseur) et Pied droit (sous Profile ID) — par ex. une ligne TVA intra-UE sous l'adresse fournisseur, une mention de conditions de paiement sous Profile ID.
Parties	Pied client et Pied livraison, placés à l'intérieur de chaque encart (qui partagent sa largeur de cellule et sa police).
Boîte des totaux	Avant totaux (au-dessus du tableau des totaux) et Après totaux (en dessous).

Comme la section block racine, un slot s'affiche dans l'inspecteur sous forme d'une carte récapitulative compacte avec une pastille Éditer : un clic confie tout le volet inspecteur au constructeur de blocs, avec une barre ← Retour · Section · Slot en haut ; changer de section sort automatiquement.

---

API REST

La page lit et écrit via les endpoints de templates standards — mêmes routes que les autres types de ressources.

Méthode + chemin	Rôle
GET /api/templates	Liste tous les modèles ; la page filtre par type = pdf-template.
GET /api/templates/{nom}	Charge une mise en page (le JSON figure dans la propriété template).
POST /api/templates	Crée une mise en page (Add).
POST /api/templates/{from}/copy/{to}	Duplique (Copy).
PUT /api/templates/{nom}	Enregistre les modifications.
DELETE /api/templates/{nom}	Supprime une mise en page. Le nom réservé built-in est rejeté.
POST /api/pdf-templates/preview	Rend un JSON pdfTemplate arbitraire face à une facture d'exemple — utilisé par l'iframe d'aperçu.
PUT /api/templates/global (avec defaultPdfTemplate)	Backend des actions Set as default / Reset to factory.

---

Conseils & bonnes pratiques

• Partir de built-in via Copier. La mise en page livrée est une base solide — préférer la dériver par copie et ajustement de bascules plutôt que de partir d'un modèle vide.
• Un seul modèle, plusieurs documents. Pour chaque variante de facture (standard, avoir, reçu destinataire …), privilégier un modèle partagé plutôt qu'un JSON inline par document. Le bénéfice : un point d'édition unique quand les mentions légales ou le jeu de colonnes évoluent.
• Désigner un défaut tôt. Marquer une mise en page comme défaut avant le branchement des modèles de document spécifiques aux clients — chaque nouveau document utilise alors ce défaut implicitement, et la propriété pdfTemplate explicite reste réservée aux vraies variantes.
• Utiliser block pour ce que les sections prédéfinies ne couvrent pas. Mentions légales personnalisées, pieds de page spécifiques à un pays, blocs de signature structurés, filigranes — autant de cas mieux traités par un block que par une section prédéfinie.
• Itérer dans l'éditeur visuel. Basculer une section et observer l'aperçu au centre se regénérer est le moyen le plus rapide d'arriver à une mise en page — l'aperçu en direct est toujours visible, pas de modale à ouvrir.
• Charger une vraie facture une fois par session. Le bouton ↑ Charger XML en haut de l'éditeur alimente le sélecteur de chaque bloc — chargement unique, et chaque auto-complétion XPath utilise vos données.
• Ne pas supprimer built-in. Le bouton est désactivé sur cette entrée pour cette raison — c'est la valeur de repli au bout de la chaîne de résolution.