Créer des modèles avancés pour la génération de documents

La génération de documents par publipostage consiste à lire des valeurs depuis une source de données et à placer chacune dans l'espace réservé correspondant d'un modèle. Vous conservez deux éléments : un modèle contenant les champs de fusion (les variables à remplir) et une source de données qui fournit les valeurs ainsi que tout ce qui reste identique sur chaque copie. Le moteur de reporting de PDF4me prend ces deux fichiers et renvoie un document terminé.

PDF4me accepte les modèles Word, HTML et PDF, et le plus riche des trois est Word. Avec une syntaxe brève et lisible, vous concevez un seul modèle Word couvrant factures, reçus, contrats, devis ou tout document personnalisé, puis en générez des milliers à partir de données. Ce guide parcourt toute la syntaxe — champs de fusion, conditions, mise en forme, tableaux, images et HTML en ligne — avec des exemples prêts à copier et un modèle d'exemple que vous pouvez télécharger et exécuter. Chaque lien de syntaxe pointe vers la page exacte de la documentation de la syntaxe des modèles Word.

Comment concevoir un modèle Word ?​

Tout commence par un espace réservé. Partout où vous voulez insérer une valeur, tapez le nom du champ entre doubles chevrons et crochets :

<<[FieldName]>>

Le nom entre crochets doit correspondre à une propriété de votre source de données. Gardez des noms descriptifs, tenez-vous à une seule convention (camelCase ou PascalCase) et évitez les caractères spéciaux. Voici un modèle minimal et les données qui le remplissent :

Dear <<[CustomerName]>>,

Thank you for your order #<<[OrderNumber]>>.

{
  "CustomerName": "John Smith",
  "OrderNumber": "12345"
}

Le moteur renvoie :

Dear John Smith,

Thank you for your order #12345.

C'est toute l'idée. Tout ce qui suit est une variation du même principe — conditions, boucles et mise en forme enveloppent toujours de simples champs de fusion. Les détails complets se trouvent dans la Vue d'ensemble de la syntaxe.

Comment ajouter des conditions à un modèle ?​

L'action Generate Document peut se ramifier selon vos données. Selon qu'une condition est vraie ou non, elle insère un bloc de contenu ou un autre. La structure de base if / elseif / else se lit ainsi :

<<if [condition1]>> Add the first block
<<elseif [condition2]>> Add the second block
<<else>> Add the fallback block
<</if>>

Les conditions peuvent tester une valeur directement ou s'appuyer sur les méthodes d'énumération (voir plus bas), par exemple <<if [employees.Any(p => p.Age > 50)]>>. Vous trouverez l'ensemble complet des opérateurs de comparaison et logiques dans Logique conditionnelle.

Comment mettre en forme les valeurs d'un modèle ?​

Souvent, une valeur brute doit être préparée avant d'être placée — une date dans un style précis, un nombre arrondi, du texte en majuscules. Ajoutez une spécification de format après le nom du champ, séparée par deux points et entre guillemets :

<<[token]:"format">>

Les dates utilisent un motif de style .NET :

Invoice Date: <<[invoiceDate]:"dd.MM.yyyy">>
Due Date:     <<[dueDate]:"MMMM dd, yyyy">>

La casse a ses propres commutateurs courts — :upper, :caps (mettre chaque mot en majuscule) et :firstCap :

Customer: <<[customerName]:upper>>
Product:  <<[productName]:caps>>

Les nombres utilisent des formats numériques standard, si bien que <<[price]:"F2">> fixe une valeur à deux décimales. La liste complète des motifs de date, de texte et de nombre est dans Mise en forme dans les modèles.

Comment construire des tableaux à partir d'une liste ?​

Les tableaux sont là où la génération de documents prend tout son sens — une ligne de modèle se déploie en autant de lignes que vos données. Créez un tableau Word normal, ouvrez une boucle <<foreach>> dans la première cellule, ajoutez un champ de fusion dans chaque cellule suivante et fermez la boucle dans la dernière cellule :

Column 1: <<foreach [product in products]>><<[product.productName]>>
Column 2: <<[product.manufactured]:"yyyy.MM.dd">>
Column 3: <<[product.price]>><</foreach>>

Chaque objet du tableau products devient une ligne, et vous pouvez mettre en forme les cellules en ligne comme partout ailleurs. D'autres motifs de tableau, y compris des lignes filtrées et agrégées, sont traités dans Tableaux dans les modèles.

Comment répéter des paragraphes et des sections ?​

La même boucle <<foreach>> fonctionne aussi en dehors des tableaux. Enveloppez n'importe quel bloc de contenu — un paragraphe, un titre avec son corps, une section entière — et il se répète une fois par élément de la collection :

<<foreach [item in collection]>>
Content with <<[item.property]>>
<</foreach>>

Les boucles peuvent s'imbriquer (une section par service, une ligne par employé à l'intérieur) et peuvent filtrer ou trier la collection au passage. Consultez Répéter paragraphes et sections pour des exemples imbriqués et conditionnels.

Comment ajouter des images à un modèle ?​

PDF4me peut intégrer des images dans un document généré depuis une URL publique ou une chaîne Base64. Une règle compte : le champ d'image doit se trouver dans une Zone de texte Word. Créez la zone de texte à l'endroit voulu, puis ajoutez le champ.

Depuis une URL publique :

<<image [imageUrl]>>

Depuis une chaîne encodée en Base64 :

<<image [imageBase64]>>

Vous contrôlez la taille avec des commutateurs comme -keepRatio, -fitHeight, -fitWidth et -fitSize, p. ex. <<image [companyLogo] -keepRatio>>. La référence complète des tailles et des exemples d'images par ligne se trouvent dans Insérer des images.

Comment insérer du HTML dans un modèle ?​

Si vos données contiennent déjà du HTML mis en forme, affichez-le tel quel avec le commutateur -html au lieu de l'échapper en texte brut :

<<[token] -html>>

Le moteur analyse la valeur du champ comme du HTML et applique la mise en forme — gras, italique, listes, titres, spans colorés et plus — dans le document généré. Les balises et styles pris en charge sont listés dans Insérer du HTML.

Travaillez vos données avec les méthodes d'énumération​

Au-delà des champs simples, le moteur expose des méthodes de style IEnumerable que vous pouvez appeler directement dans un token — filtrer, trier, compter, moyenner et plus. Quelques exemples :

Total products: <<[products.Count()]>>
Average price:  $<<[products.Average(p => p.price)]:"F2">>
Top items:      <<foreach [p in products.OrderByDescending(x => x.price).Take(5)]>><<[p.name]>><</foreach>>

Elles se combinent naturellement avec les conditions et les boucles. La liste complète des méthodes — Where, OrderBy, GroupBy, Sum, Any, First et le reste — est dans Énumération dans les modèles.

Les données d'exemple ressemblent à ceci — un fournisseur, un client et une liste de produits sur laquelle le modèle itère :

{
  "VendorName": "PDF4me",
  "VendorCity": "Zurich",
  "VendorCountry": "Switzerland",
  "VendorZip": "8630",
  "VendorContact": "123456",
  "InvoiceDate": "22-08-2022",
  "CustomerName": "John Doe",
  "CustomerCity": "Start City",
  "CustomerCountry": "US",
  "CustomerZip": "3214",
  "products": [
    { "productName": "PDF Converter", "value": 2000, "expires": "01/08/2025" },
    { "productName": "PDF API", "value": 1250, "expires": "18/02/2029" },
    { "productName": "PDF Editor", "value": 1999, "expires": "12/12/2027" }
  ],
  "comments": "This document is <b>computer generated</b> and does not require a signature."
}

Remarquez que comments contient du HTML — associez-le au commutateur <<[comments] -html>> et la balise <b> s'affiche en gras dans la sortie.

Liens rapides pour concevoir votre modèle​

Questions fréquentes​

Comment créer des champs de fusion dans un modèle Word ?​

Tapez le nom du champ entre doubles chevrons et crochets, comme <<[CustomerName]>>, partout où vous voulez insérer une valeur. Le nom doit correspondre à une propriété de votre source de données JSON ou XML. Vous pouvez ajouter des champs manuellement n'importe où — titres, paragraphes, cellules de tableau ou zones de texte.

Quels formats de modèle PDF4me prend-il en charge ?​

Word (.docx, .doc), HTML et PDF. Les trois utilisent la même syntaxe de champs de fusion, donc ce que vous apprenez pour un modèle Word se transpose. Word offre le contrôle le plus complet sur la mise en page, les conditions, les tableaux et les images.

Puis-je ajouter des conditions if/else à un modèle Word ?​

Oui. Enveloppez le contenu avec <<if [condition]>> ... <<elseif [condition]>> ... <<else>> ... <</if>>. Une condition peut comparer un champ directement ou appeler une méthode d'énumération comme Any() ou Count(). Ainsi un seul modèle gère chaque variante de vos données au lieu de maintenir un fichier par cas.

Comment mettre en forme dates et nombres dans un modèle ?​

Placez le format après le nom du champ, entre guillemets : <<[invoiceDate]:"dd.MM.yyyy">> pour une date, <<[price]:"F2">> pour un nombre à deux décimales. La casse dispose de commutateurs courts — :upper, :caps et :firstCap.

Comment générer un tableau qui grandit avec mes données ?​

Créez un tableau Word, ouvrez <<foreach [item in collection]>> dans la première cellule, placez un champ de fusion dans chaque cellule restante et fermez avec <</foreach>> dans la dernière cellule. Chaque élément de la collection devient automatiquement une ligne.

Dépannage​

Étapes suivantes​

Concevez le modèle une fois, reliez-le à vos données, et PDF4me produit factures, contrats et rapports personnalisés à la demande — depuis un seul appel d'API ou une automatisation qui en traite des milliers à la fois.

Références​

• Syntaxe des modèles Word — Vue d'ensemble
• Mise en forme dans les modèles
• Tableaux dans les modèles
• Insérer des images
• Insérer du HTML
• Logique conditionnelle et énumération
• Document Generation API