Utiliser les données dynamiques

Lorsque vous générez un Document avec PDFMonkey, vous envoyez généralement des données à utiliser avec le Template que vous avez sélectionné. Les données de test d’un Template sont des données fictives qui ressemblent à celles que vous utiliseriez lors de la génération d’un Document. Leur but est de vous aider à construire le Template et à tester différents scénarios.

Il est généralement plus efficace de travailler avec des données de test que de construire votre Template et de le tester en générant des Documents de test. Vous obtenez une boucle de rétroaction plus courte et ne consommez pas votre quota mensuel.

Par commodité, vos données de test sont copiées comme payload du Document lors de la génération d’un Document via le dashboard. En dehors de cela, elles ne sont jamais utilisées lors de la génération de Documents via l’API.

Définir les données de test

Définissez vos données de test dans l’onglet Données de test de l’éditeur de Template. Cela remplit deux fonctions :

• Vous aider à définir la structure que vous souhaitez utiliser pour vos données
• Fournir des données de test que vous pouvez manipuler lors de la construction de votre Template

Les données dans PDFMonkey, qu’il s’agisse de données de test pour un Template ou du payload d’un Document, sont exprimées en utilisant la syntaxe JSON.

Prenons l’exemple d’une commande e-commerce. Vous pourriez imaginer quelque chose comme ceci :

{
  "orderId": 1234,
  "orderStatus": "pending",
  "invoiceId": null,
  "client": {
    "civility": "M.",
    "fullName": "Pierre Dupont",
    "isNewClient": true
  },
  "lineItems": [
    { "product": "Soie ultra résistante",    "quantity": 100, "price": 123.45 },
    { "product": "Composants électroniques", "quantity": 12,  "price": 12.34 }
  ]
}

Examinons ce que nous avons.

Nous avons des données liées à la commande avec orderId et orderStatus. Elles utilisent différents types de données, un integer et un string.

Ensuite, nous avons un invoiceId qui est null pour indiquer une valeur vide. Étant donné que notre commande est en attente, elle n’a pas encore de facture, ce qui est logique.

Les choses deviennent intéressantes avec client car c’est une structure imbriquée (généralement appelée « objet ») contenant ses propres données. Vous remarquerez un nouveau type de données pour isNewClient qui est un booléen, une valeur qui peut être true ou false.

Et enfin nous avons lineItems qui est une liste (généralement appelée « tableau ») de, sans surprise, lignes de commande représentées par des objets avec des propriétés pour product, quantity et price.

Utiliser vos données de test dans le Template

Une fois que vous avez défini vos données de test, vous les appelez dans votre Template en utilisant Liquid.

Étant donné les données que nous avons définies ci-dessus, notre HTML pourrait commencer par quelque chose comme ceci :

<p>Commande n° {{orderId}} est actuellement {{orderStatus}}.</p>
<p>Client : {{client.civility}} {{client.fullName}}.</p>

Comme vous pouvez le voir, nous pouvons référencer nos éléments de données directement et utiliser un point (.) pour accéder aux éléments imbriqués. Ce code générerait le HTML suivant :

<p>Commande n° 1234 est actuellement pending.</p>
<p>Client : M. Pierre Dupont</p>

Dans les guides suivants, nous apprendrons comment afficher du contenu selon une condition ou comment parcourir notre liste de lignes de commande et l’afficher correctement.

Nommer vos variables

Les clés de votre payload ne doivent jamais contenir de point ni d’espace et ne doivent jamais être uniquement un nombre.

{
  // Clés valides
  "someVariable": "Une valeur",              // {{someVariable}}
  "some_variable": "Une valeur",             // {{some_variable}}
  "some-variable": "Une valeur",             // {{some-variable}}
  "SomeVariable": "Une valeur",              // {{SomeVariable}}
  "somevariable": "Une valeur",              // {{somevariable}}
  "some": { "variable": "Une valeur" },      // {{some.variable}}
  "2words": "Bonjour le monde",              // {{2words}}

  // Clés invalides
  "some.variable": "Une valeur",
  "some variable": "Une valeur",
  "(someVariable)": "Une valeur",
  "'someVariable'": "Une valeur",
  "{{someVariable}}": "Une valeur",
  "2": "Une valeur",
  "$someVariable": "Une valeur"
}

Voici comment vous appelleriez les clés valides dans un template :

{{someVariable}}
{{some_variable}}
{{some-variable}}
{{SomeVariable}}
{{somevariable}}
{{some}}
{{2words}}

Créer des variables dans les templates

Les tags de variables créent de nouvelles variables Liquid. Voici les deux tags les plus courants, mais vous pouvez en découvrir davantage dans la documentation officielle.

assign

Lire la documentation complète de assign.

Crée une nouvelle variable nommée.

{% assign foo = "bar" %}
{{foo}}

bar

capture

Lire la documentation complète de capture.

Capture la chaîne de caractères entre les balises d’ouverture et de fermeture et l’assigne à une variable. Les variables créées avec capture sont stockées sous forme de chaînes de caractères.

{% assign favorite_food = "pizza" %}
{% assign age = 35 %}

{% capture about_me %}
J’ai {{age}} ans et mon plat préféré est la {{favorite_food}}.
{% endcapture %}

{{about_me}}

J’ai 35 ans et mon plat préféré est la pizza.

Questions fréquentes

Comment transmettre des données dynamiques à un template PDFMonkey ?

Définissez vos données sous forme d’objet JSON et envoyez-les comme payload du document via l’API ou une intégration. Dans le template, accédez aux valeurs avec la syntaxe Liquid : {{ nomVariable }} pour les clés de premier niveau, {{ objet.propriete }} pour les valeurs imbriquées et {% for item in tableau %} pour les tableaux.

À quoi servent les données de test dans PDFMonkey ?

Les données de test sont un objet JSON défini dans l’onglet Données de test de l’éditeur de template. Elles simulent le payload que vous enverriez via l’API, vous permettant de prévisualiser le template en temps réel sans consommer votre quota mensuel de documents.

Peut-on utiliser des objets JSON imbriqués et des tableaux dans les templates PDFMonkey ?

Oui. PDFMonkey prend en charge le JSON profondément imbriqué. Accédez aux valeurs imbriquées avec la notation par points (ex. {{ client.fullName }}) et parcourez les tableaux avec {% for item in lineItems %}. Vous pouvez imbriquer des objets dans des tableaux et inversement.