Conditions et boucles

La plupart du temps, vous aurez besoin d’afficher certaines portions de contenu en fonction de la valeur d’un ou plusieurs éléments de données, ou de répéter du contenu pour chaque entrée d’une liste. Voyons comment cela se fait avec Liquid.

Utiliser un simple « if »

La condition la plus simple que vous pouvez utiliser est une instruction if :

{% if client.isNewClient == true %}
  <p>Félicitations pour votre première commande !</p>
{% endif %}

Le contenu sera affiché uniquement lorsque la condition est vraie.

Combiner des conditions

Vous pouvez également combiner plusieurs conditions en utilisant and et or :

{% if client.isExistingClient == true and client.orderedRecently == true %}
  <p>Un fan de notre marque, n’est-ce pas ? :D</p>
{% endif %}

{% if client.isNewClient == true or client.orderedALongTimeAgo == true %}
  <p>Félicitations pour votre première commande de l’année !</p>
{% endif %}

Condition inverse avec « unless »

Si vous souhaitez inverser la condition, unless est votre allié :

{% unless client.isNewClient %}
  <p>Ravi de vous revoir !</p>
{% endunless %}

Dans ce cas, le code serait équivalent à :

{% if client.isNewClient != true %}
  <p>Ravi de vous revoir !</p>
{% endif %}

Les deux cas avec « if … else »

Un peu plus fréquent que unless, l’instruction if ... else permet de spécifier les deux cas :

{% if client.isNewClient == true %}
  <p>Félicitations pour votre première commande !</p>
{% else %}
  <p>Ravi de vous revoir !</p>
{% endif %}

Conditions multiples avec « if … elsif … else »

Il peut arriver que vous deviez vérifier plusieurs conditions pour trouver le bon contenu. Pour ces cas, l’instruction if ... elsif ... else est la solution :

{% if client.isNewClient == true %}
  <p>Félicitations pour votre première commande !</p>
{% elsif client.fullName == "Pierre Dupont" %}
  <p>Bon retour Spide... hum... M. Dupont.</p>
{% else %}
  <p>Ravi de vous revoir {{client.fullName}} !</p>
{% endif %}

Dispatcher selon une seule variable

Si vous souhaitez insérer du contenu selon la valeur d’une seule variable, vous pouvez remplacer l’instruction if ... elsif ... else par une simple instruction case ... when ... end :

{% case client.fullName %}
  {% when "Pierre Dupont" %}
    <p>Bon retour Spide... hum... M. Dupont.</p>
  {% when "Diana Prince" %}
    <p>Ravie de vous revoir WonderW... enfin... Mlle Prince.</p>
  {% else %}
    <p>Rebonjour {{client.fullName}} !</p>
{% endcase %}

Boucles

Itérer sur des listes est un besoin très fréquent. Voici les aspects essentiels de l’itération, mais vous pouvez en apprendre davantage dans la documentation officielle.

for

Utilisons les données que nous avons définies dans une section précédente :

{
  "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 }
  ]
}

Nous pouvons itérer sur le tableau lineItems pour lister nos produits en utilisant une boucle for. Elle répétera le code pour chaque élément du tableau :

<table>
  <tr>
    <th>Produit</th>
    <th>Quantité</th>
    <th>Prix unitaire</th>
    <th>Total</th>
  </tr>

  {% for item in lineItems %}
    <tr>
      <td>{{item.product}}</td>
      <td>{{item.quantity}}</td>
      <td>${{item.price | with_delimiter, precision: 2}}</td>
      <td>${{item.price | times: item.quantity | with_delimiter, precision: 2}}</td>
    </tr>
  {% endfor %}
</table>

Le HTML résultant ressemblera à ceci :

<table>
  <tr>
    <th>Produit</th>
    <th>Quantité</th>
    <th>Prix unitaire</th>
    <th>Total</th>
  </tr>

  <tr>
    <td>Soie ultra résistante<td>
    <td>100</td>
    <td>$123.45</td>
    <td>$12,345.00</td>
  </tr>

  <tr>
    <td>Composants électroniques</td>
    <td>12</td>
    <td>$12.34</td>
    <td>$148.08</td>
  </tr>
</table>

L’objet forloop

À l’intérieur d’une boucle for, vous avez accès à un objet spécial qui stocke l’état actuel de la boucle. Il peut être utile pour construire des cas particuliers pour la première ou la dernière itération, par exemple.

{% for item in lineItems %}
  {% if forloop.first == true %}
    <p>{{item.product}} est le premier article.</p>
  {% elsif forloop.last == true %}
    <p>{{item.product}} est le dernier article.</p>
  {% else %}
    <p>{{item.product}} est un article.</p>
  {% endif %}
{% endfor %}

Limiter et décaler

Vous pouvez contrôler le nombre d’éléments sur lesquels une boucle itère en utilisant limit et offset :

{% for item in lineItems limit: 1 %}
  <p>Premier article : {{item.product}}</p>
{% endfor %}

{% for item in lineItems offset: 1 %}
  <p>Articles restants : {{item.product}}</p>
{% endfor %}

Vous pouvez également itérer dans l’ordre inverse :

{% for item in lineItems reversed %}
  <p>{{item.product}}</p>
{% endfor %}

Filtres associés

Lorsque vous travaillez avec des boucles, ces filtres PDFMonkey sont particulièrement utiles :

• Le filtre slice_by (découpe un tableau en groupes de N éléments)
• Le filtre where_exp (filtre un tableau en utilisant une expression)

Questions fréquentes

Comment utiliser des conditions dans les modeles PDFMonkey ?

Utilisez les balises conditionnelles Liquid : {% if condition %}, {% elsif %}, {% else %} et {% endif %} pour afficher ou masquer du contenu. Vous pouvez aussi utiliser {% unless %} pour les conditions inversees et {% case %} / {% when %} pour la logique a branches multiples.

Comment iterer sur des donnees dans les modeles PDFMonkey ?

Utilisez la balise {% for item in list %} pour repeter du HTML pour chaque element d’un tableau provenant du payload de votre document. A l’interieur de la boucle, accedez a l’objet forloop pour l’index courant, la longueur et les indicateurs first/last.

Peut-on combiner plusieurs conditions dans les modeles Liquid PDFMonkey ?

Oui. Utilisez "and" pour exiger que toutes les conditions soient vraies, ou "or" pour exiger qu’au moins une le soit. Par exemple : {% if client.isNewClient == true and order.total > 100 %}.