Aperçu de la liaison de données

La liaison de données vous permet de créer des modèles de documents réutilisables avec des références d'espace réservé qui sont résolues au moment de la génération. Au lieu de coder en dur les valeurs dans votre définition de document, vous utilisez des références $data qui sont remplacées par des données réelles lors de la génération du PDF.

Fonctionnement

1. Créez un modèle avec les références $data.path.to.value dans votre définition de document.
2. Fournissez un objet de données aux côtés du modèle lors de la génération d'un PDF.
3. DocPayload résout toutes les références $data, en les remplaçant par des valeurs de votre objet de données.
4. Le PDF est rendu avec le contenu résolu.

Références scalaires

La forme la plus basique de la liaison de données est une référence scalaire -- un chemin $data qui pointe vers une seule valeur de votre objet de données.

Modèle

{
  "document": {
    "styles": {
      "title": { "fontSize": 18, "fontWeight": "bold" },
      "highlight": { "color": "#E94560", "fontWeight": "bold" }
    },
    "content": [
      { "p": "Invoice for $data.client.companyName", "style": "title" },
      { "p": "Invoice Number: $data.invoice.number" },
      { "p": "Prepared by: $data.user.name" },
      { "p": "Contact: $data.user.email" },
      { "p": "Amount Due: [b]$data.invoice.totalAmount[/b]", "style": "highlight" }
    ]
  }
}

Données

{
  "client": {
    "companyName": "GlobalTech Industries"
  },
  "user": {
    "name": "Laura Bennett",
    "email": "laura.bennett@shipforge.io"
  },
  "invoice": {
    "number": "INV-2026-0317",
    "totalAmount": "$24,500"
  }
}

Résultat

Les paragraphes résolus deviennent :

• « Facture pour GlobalTech Industries »
• « Numéro de facture : INV-2026-0317 »
• « Préparé par : Laura Bennett »
• « Contact : laura.bennett@shipforge.io »
• « Montant dû : $24 500 »

Syntaxe du chemin d'accès

Les références utilisent des chemins séparés par des points pour parcourir les objets imbriqués de vos données.

Référence	Chemin de données
$data.name	Propriété name de niveau supérieur
$data.client.companyName	companyName dans l'objet client
$data.client.address.city	city dans address dans client

Indexation des tableaux

Utilisez la notation entre crochets pour accéder à des éléments spécifiques dans les tableaux :

Référence	Description
$data.items[0].name	Propriété name du premier élément
$data.company.bills[3].amount	amount de la quatrième facture dans company
$data.matrix[0][1]	Index chaînés — ligne 0, colonne 1
$item.addresses[0].city	Indexation des tableaux dans le contexte $item

{ "p": "Primary contact: $data.contacts[0].name — $data.contacts[0].email" }

Avec les données :

{
  "contacts": [
    { "name": "Alice Chen", "email": "alice@acme.com" },
    { "name": "Bob Park", "email": "bob@acme.com" }
  ]
}

Ceci rend : « Contact principal : Alice Chen — alice@acme.com »

L'indexation des tableaux fonctionne partout où les références $data fonctionnent, y compris dans les chemins $item lors de l'itération sur les données de tableau/liste. Si l'index est hors limites ou que la valeur n'est pas un tableau, la référence est conservée telle quelle.

Où fonctionnent les références

Les références $data sont supportées dans :

• Texte de paragraphe -- { "p": "Hello $data.user.name" }
• À l'intérieur des balises de formatage en ligne -- { "p": "[b]$data.invoice.total[/b]" }
• Valeurs par défaut des champs de formulaire -- [textfield, name, '$data.applicant.name', 200|20]
• Contenu d'en-tête et de pied de page -- les références sont résolues dans le contenu répétitif aussi
• Contenu de disposition en colonnes -- les références fonctionnent à l'intérieur des dispositions multi-colonnes

Références non résolues

Si une référence $data pointe vers un chemin qui n'existe pas dans l'objet de données fourni, le texte de la référence est conservé tel quel dans la sortie. Cela signifie que $data.missing.key apparaîtra littéralement sous la forme « $data.missing.key » dans le PDF.

{ "p": "Unresolved ref stays: $data.missing.key" }

Ce comportement garantit que les données manquantes ne causent pas d'échecs de génération, tout en facilitant le repérage des valeurs manquantes dans la sortie.

Références à l'intérieur du formatage en ligne

Les références $data fonctionnent à l'intérieur de n'importe quelle balise de formatage en ligne. La référence est d'abord résolue, puis le formatage est appliqué.

{ "p": "[b]Client:[/b] $data.client.companyName - [color, #CC0000]$data.client.address.city[/color]" }

Avec les données { "client": { "companyName": "Meridian Logistics", "address": { "city": "Denver" } } }, ceci rend :

Client : Meridian Logistics - Denver

Au-delà des références scalaires

DocPayload supporte deux mécanismes de liaison de données supplémentaires pour remplir les collections :

• Fournisseur de données -- Remplir les lignes de tableau à partir de tableaux d'objets et les éléments de liste à partir de tableaux de chaînes.
• Modèles -- Stocker les définitions de documents en tant que modèles réutilisables et générer des PDF en transmettant les données au moment de la demande.
• Variables globales -- Jetons $global.* intégrés pour la date, l'heure, les numéros de page et les métadonnées du document, aucun objet de données requis.

Comparaison rapide

Fonctionnalité	Syntaxe	Cas d'utilisation
Référence scalaire	$data.path.to.value	Remplacer des valeurs individuelles dans le texte
Index de tableau	$data.items[0].name	Accéder à un élément de tableau spécifique par position
Source de tableau	"source": "$data.items"	Générer les lignes du tableau à partir d'un tableau
Source de liste	"source": "$data.notes"	Générer les éléments de liste à partir d'un tableau
Jeton global	$global.NAME	Valeurs intégrées : date, numéros de page, métadonnées