> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/wallet/liquid-templating.md).
# Modèles Liquid
## Modélisation Liquid
Liquid combine du texte fixe avec des valeurs dynamiques issues d'une Carte. The Wallet Crew utilise l'implémentation DotLiquid, ainsi que des filtres de date personnalisés et la `minify` balise.
Utilisez cette référence après avoir confirmé les chemins de données requis sur une Carte réelle.
Exemples concrets
* Une carte de fidélité affiche un solde de points sûr et entier.
* Une carte cadeau affiche son identifiant, son montant et sa date d'expiration.
* Un billet d'événement transforme les données de siège en indications pour le lieu.
### Confirmer les données disponibles
Chaque rendu reçoit un contexte de données. Il peut contenir des données de Carte, des données supplémentaires et des valeurs renvoyées par des fournisseurs connectés.
Inspecter **Afficher les données** sur une Carte réelle avant d'écrire un modèle. Cette charge utile est la source de vérité pour les chemins de variables.
Les données supplémentaires conviennent au contenu visible de la Carte. Les métadonnées prennent en charge les opérations et la segmentation. Elles ne doivent pas être considérées comme une source d'affichage du Wallet.
Pour le flux complet de mise à jour et de validation, voir [Mettre à jour les données de Carte dans les modèles](/developers-guides/fr/integration-guides/wallet/update-pass-data-in-templates.md).
Les chemins courants incluent :
| Données | Exemples de chemins |
| ---------------------- | ------------------------------------------------------------------------- |
| Client | `firstName`, `lastName`, `address.city` |
| Carte | `serialNumber`, `tenantId`, `publicUrl`, `authenticationToken` |
| Fidélité | `loyalty.points`, `pendingLoyaltyPoints`, `loyalty.amounts` |
| Carte cadeau | `voucher.amount`, `voucher.currency`, `id.y2.giftCardId` |
| Billet d'événement | `ticket.name`, `ticket.startDate`, `ticket.seatNumber`, `ticket.entrance` |
| Collections | `y2.tickets`, `y2.bons.loyaltyCertificates` |
| Valeurs personnalisées | `additionalData.` |
Les valeurs manquantes s'affichent comme une chaîne vide. Utilisez `default` lorsqu'un repli visible est requis.
```liquid
{{ loyalty.points | default: 0 | floor }}
```
### Notions de base de la syntaxe
Utilisez `{{ ... }}` pour afficher une valeur. Utilisez `{% ... %}` pour la logique qui ne s'affiche pas d'elle-même.
```liquid
Bienvenue {{ firstName | default: "membre" }} !
{% if loyalty.points and loyalty.points > 1000 %}Membre VIP{% endif %}
{% assign label = ticket.priceCategory | strip %}
```
Les filtres s'appliquent de gauche à droite. La notation par points suit la structure imbriquée dans la charge utile des données.
#### Conditions et boucles
Liquid ne considère que `nil` et `false` comme faux. Le nombre `0` et la chaîne `"false"` sont vrais. Comparez explicitement les nombres facultatifs.
```liquid
{% if pendingLoyaltyPoints and pendingLoyaltyPoints > 0 %}
En attente : {{ pendingLoyaltyPoints }} pts
{% endif %}
```
Protégez les boucles avec une vérification de la taille de la collection. Cela évite les titres de section vides.
```liquid
{% if y2.tickets.size > 0 %}
{% for ticket in y2.tickets %}
- #{{ ticket.ticketNumber }} le {{ ticket.startDate | date: "D" }}
{% endfor %}
{% endif %}
```
À l'intérieur d'une boucle, `forloop.index`, `forloop.first`, `forloop.last`, et `forloop.length` sont disponibles.
#### Affectations, branches et espaces
Utilisez `assign` pour réutiliser les valeurs calculées. Utilisez `case` pour les correspondances code-vers-libellé.
```liquid
{% assign category = ticket.priceCategory | strip %}
{% case category %}
{% when "F" %}Tarif plein
{% when "R" %}Réduit
{% else %}{{ category }}
{% endcase %}
```
Utilisez `{%-` et `-%}` pour supprimer les espaces environnants. Cela permet de garder les modèles multilignes compacts dans les champs Wallet étroits.
```liquid
{%- assign alley = ticket.alley | strip -%}
{%- if alley -%}Allée {{ alley }}{%- endif -%}
```
#### Valeurs YAML
Mettez entre guillemets les valeurs Liquid contenant des caractères spéciaux YAML. Utilisez `|-` pour les valeurs multilignes.
```yaml
alternateText: 'À présenter à la caisse : {{ id.y2.customerId }}'
value: |-
{% assign name = firstName | append: " " | append: lastName %}
{{ name }}
```
### Filtres personnalisés
#### Filtres de date
Tous les filtres de date analysent l'entrée comme une valeur de date ou d'heure, appliquent l'opération et renvoient un `DateTimeOffset`. Enchaînez-les avec `| date: "format"` lorsqu'une sortie sous forme de chaîne est nécessaire.
**`add_minutes`**
Ajoute le nombre de minutes spécifié.
```liquid
{{ someDate | add_minutes: 60 }}
{{ someDate | add_minutes: 60 | date: "yyyy-MM-dd HH:mm:ss" }}
```
**`add_hours`**
Ajoute le nombre d'heures spécifié.
```liquid
{{ someDate | add_hours: 24 }}
{{ someDate | add_hours: 24 | date: "yyyy-MM-dd HH:mm:ss" }}
```
**`add_seconds`**
Ajoute le nombre de secondes spécifié.
```liquid
{{ someDate | add_seconds: 3600 }}
{{ someDate | add_seconds: 3600 | date: "yyyy-MM-dd HH:mm:ss" }}
```
**`add_days`**
Ajoute le nombre de jours spécifié.
```liquid
{{ someDate | add_days: 7 }}
{{ someDate | add_days: 7 | date: "yyyy-MM-dd" }}
```
**`add_timespan`**
Ajoute un intervalle au `hh:mm:ss` format.
```liquid
{{ someDate | add_timespan: "02:30:00" }}
{{ someDate | add_timespan: "02:30:00" | date: "yyyy-MM-dd HH:mm:ss" }}
```
Tous les filtres de date utilisent une culture invariante pour l'analyse et le formatage.
#### Filtre de format
**`format`**
Applique une chaîne de format à toute `IFormattable` valeur telle que les nombres, les dates et les énumérations.
```liquid
{{ loyaltyPoints | format: "N0" }}
```
Cela affiche un entier groupé tel que `1,234` en culture invariante.
```liquid
{{ balance | format: "C2" }}
```
Cela affiche une valeur au format monétaire avec deux décimales.
### Balise personnalisée
#### `minify`
Génère une URL de redirection courte à partir d'un lien de Carte généré.
```liquid
{% minify https://yoursite.com/account/{{ customer.id }} %}
```
La balise commence par rendre l'expression imbriquée, puis crée une URL courte via le service de redirection The Wallet Crew, et renvoie finalement la chaîne URL raccourcie.
### Valider et dépanner les modèles
#### Une variable s'affiche vide
Un chemin manquant n'empêche pas le rendu. Il se résout en une chaîne vide. Inspectez **Afficher les données** sur une Carte réelle, puis utilisez `default` où nécessaire.
```liquid
{{ loyalty.points | default: 0 }}
```
{% hint style="warning" %}
Une variable manquante produit généralement un champ vide. Validez les chemins de champ par rapport à un contexte de Carte réel avant de publier une modification de modèle.
{% endhint %}
#### Une date est décalée ou formatée de manière inattendue
Les dates contiennent des informations de fuseau horaire. Formatez explicitement la sortie souhaitée. Utilisez `add_hours` uniquement lorsqu'un décalage connu est requis.
```liquid
{{ ticket.startDate | date: "yyyy-MM-dd" }}
{{ ticket.startDate | add_hours: 2 | date: "HH:mm" }}
```
#### `format` ignore la locale de la Carte
C'est attendu. `format` utilise une culture invariante. Utilisez `date` pour les dates sensibles à la locale. Assemblez, si nécessaire, le texte spécifique à la locale pour les nombres ou les devises dans chaque fichier de langue.
#### Un fichier YAML ne peut pas être analysé
Mettez entre guillemets les valeurs Liquid contenant `:`, `{`, `#`, ou `&`. Utilisez `|-` pour les valeurs multilignes.
#### Une condition se comporte de manière inattendue
Le nombre `0` et la chaîne `"false"` sont vrais. Comparez explicitement les valeurs numériques facultatives.
```liquid
{% if loyalty.points and loyalty.points > 0 %}…{% endif %}
```
#### La sortie comporte des lignes vides
Utilisez des tirets de contrôle des espaces autour des balises.
```liquid
{%- if ticket.alley -%}
Allée {{ ticket.alley }}
{%- endif -%}
```
#### La syntaxe Liquid littérale est requise
Utilisez `raw` et `endraw`.
```liquid
{% raw %}{{ this is literal }}{% endraw %}
```
#### Le modèle contient une erreur de syntaxe
Un Liquid invalide peut afficher un message d'erreur au lieu de la valeur attendue. Considérez les erreurs d'analyse comme des défauts du modèle et corrigez-les avant la publication.
{% hint style="info" %}
Utilisez l'aperçu de la Carte dans le back-office pour tester les expressions Liquid sur de vraies données de Carte avant de déployer une modification de modèle en production.
{% endhint %}
Pour le timing du rendu et la gestion des échecs en dehors de Liquid lui-même, voir [Comment une Carte est rendue](/developers-guides/fr/pass-architecture/how-a-pass-is-rendered.md).
### Filtres standard
Les filtres standard DotLiquid transforment les chaînes, les nombres, les dates et les collections.
#### Chaînes
| Filtre | Exemple |
| ------------------------------------ | ------------------------------------------------ |
| `default` | `{{ loyalty.points \| default: 0 }}` |
| `upcase`, `downcase`, `capitalize` | `{{ firstName \| capitalize }}` |
| `strip`, `lstrip`, `rstrip` | `{{ ticket.name \| strip }}` |
| `append`, `prepend` | `{{ publicUrl \| append: tenantId }}` |
| `replace`, `remove` | `{{ ticket.name \| replace: "VIP", "Premium" }}` |
| `truncate`, `truncatewords`, `slice` | `{{ id.y2.customerId \| slice: 0, 4 }}` |
| `split` | `{{ "a,b,c" \| split: "," }}` |
Utilisez un suffixe de troncature vide pour créer une initiale :
```liquid
{{ firstName | truncate: 1, "" | upcase | append: ". " }}{{ lastName | upcase }}
```
#### Nombres et collections
| Filtre | Exemple |
| ------------------------------------------------ | ------------------------------------------------------- |
| `floor`, `ceil`, `round` | `{{ loyalty.points \| default: 0 \| floor }}` |
| `plus`, `minus`, `times`, `divided_by`, `modulo` | `{{ loyalty.points \| divided_by: 100 \| floor }}` |
| `abs`, `at_least`, `at_most` | `{{ balance \| at_least: 0 }}` |
| `size`, `first`, `last`, `join` | `{{ tags \| join: ", " }}` |
| `sort`, `reverse`, `uniq`, `compact` | `{{ items \| sort \| reverse }}` |
| `map`, `where` | `{{ y2.tickets \| map: "ticketNumber" \| join: ", " }}` |
#### Dates, URL et HTML
Le `date` filtre formate les valeurs de date pour la locale de la Carte.
| Expression | Sortie typique |
| ---------------------------------------------------- | ------------------- |
| `{{ ticket.startDate \| date: "D" }}` | `lundi 27 mai 2026` |
| `{{ ticket.startDate \| date: "d" }}` | `27/05/2026` |
| `{{ ticket.startDate \| date: "M" }}` | `27 mai` |
| `{{ ticket.startDate \| date: "t" }}` | `20:00` |
| `{{ ticket.startDate \| date: "yyyy-MM-dd HH:mm" }}` | `2026-05-27 20:00` |
Utilisez `url_encode` et `url_decode` pour les valeurs d'URL. Utilisez `escape`, `escape_once`, ou `strip_html` pour les valeurs d'e-mail HTML.
Pour la liste complète des filtres, voir la [référence DotLiquid](https://github.com/dotliquid/dotliquid/wiki/DotLiquid-for-Designers).
### Recettes
Les modèles suivants répondent aux besoins courants des cartes de fidélité, des cartes cadeaux et des billets d'événement. Confirmez tous les chemins de données avant utilisation.
#### Cartes de fidélité
**Afficher les points en toute sécurité**
`default` évite un solde vide. `floor` évite les décimales indésirables.
```liquid
{{ loyalty.points | default: 0 | floor }}
```
**Afficher les points en attente séparément**
N'affichez la ligne en attente que lorsque des points attendent validation.
```liquid
Disponible : {{ loyalty.points | default: 0 | floor }} pts
{% if pendingLoyaltyPoints and pendingLoyaltyPoints > 0 %}
En attente : {{ pendingLoyaltyPoints }} pts
{% endif %}
```
**Créer un compteur de tampons récurrent**
`modulo` réinitialise le compteur visible après chaque récompense.
```liquid
{{ additionalData.stampCount | default: 0 | modulo: 10 }} / 10
```
Le même modèle peut sélectionner une image correspondante :
```liquid
stamp_{{ additionalData.stampCount | default: 0 | modulo: 10 }}.png
```
**Afficher la progression vers la prochaine récompense**
Calculez les points restants à partir d'un seuil modifiable.
```liquid
{% assign threshold = additionalData.next_tier_threshold | default: 100 %}
{% assign missing = threshold | minus: loyalty.points %}
{{ missing | at_least: 0 }} pts pour {{ additionalData.next_tier_name | default: "votre prochaine récompense" }}
```
**Déduire un nom de niveau**
Ce modèle fonctionne lorsque la source ne fournit qu'un solde de points.
```liquid
{% assign points = loyalty.points | default: 0 %}
{% if points >= 5000 %}Membre Or
{% elsif points >= 1000 %}Membre Argent
{% else %}Bienvenue membre
{% endif %}
```
**Lister les bons disponibles**
Affichez les bons au dos de la carte. Une `else` branche rend l'état vide plus clair.
```liquid
{% if y2.bons.loyaltyCertificates.size > 0 %}
Vos bons :
{% for voucher in y2.bons.loyaltyCertificates %}
- Bon de {{ voucher.amount }} € (expire le {{ voucher.validity.endDate | date: "D" }})
{% endfor %}
{% else %}
Aucun bon disponible pour le moment.
{% endif %}
```
#### Cartes cadeaux
**Réutiliser un identifiant**
Utilisez la même valeur pour les champs de code-barres et de saisie manuelle.
```yaml
barCodeValue: '{{ id.y2.giftCardId }}'
barCodeAlternateText: '{{ id.y2.giftCardId }}'
cardNumber: '{{ id.y2.giftCardId }}'
```
**Afficher un montant variable**
Cela utilise un montant cadeau facultatif et une solution de repli sûre.
```yaml
value: '{{ additionalData.giftAmount | default: 50 }}'
```
**Séparez le montant et la devise**
Des champs dédiés permettent aux plateformes Wallet d'appliquer le formatage local des devises.
```yaml
value: '{{ voucher.amount }}'
currencyCode: '{{ voucher.currency }}'
```
**Définir la période de validité**
Utilisez les dates sources pour l'expiration et la pertinence.
```yaml
relevantDate: '{{ startDate }}'
expirationDate: '{{ expirationDate }}'
start: '{{ startDate }}'
end: '{{ expirationDate }}'
```
#### Billets d'événement
**Expirer après l'événement**
Une expiration le jour suivant évite les problèmes de fuseaux horaires et d'arrivées tardives.
```yaml
expirationDate: '{{ ticket.startDate | add_days: 1 | date: "d" }}'
```
**Définir une période de pertinence**
Cela aide les plateformes Wallet à afficher le billet au bon moment.
```yaml
start: '{{ ticket.startDate | add_days: 0 | date: "d" }}'
end: '{{ ticket.startDate | add_days: 1 | date: "d" }}'
```
**Afficher la date et l'heure de l'événement**
Des champs distincts permettent à la mise en page du Wallet de donner la priorité à la date ou à l'heure.
```yaml
l$label-date-apple: '{{ ticket.startDate | date: "M" }}'
l$value-date-apple: '{{ ticket.startDate | date: "t" }}'
```
**Mapper les codes de catégorie**
`case` convertit les codes sources en libellés lisibles et spécifiques à la langue.
```liquid
{% assign category = ticket.priceCategory | strip %}
{% case category %}
{% when "F" %}Tarif plein
{% when "R" %}Réduit
{% when "S" %}Étudiant
{% when "C" %}Enfant
{% else %}{{ category }}
{% endcase %}
```
**Créer des indications pour le lieu**
Nettoyez les champs facultatifs avant de les concaténer. Le contrôle des espaces maintient une sortie compacte.
```liquid
{%- assign zone3 = ticket.zone3 | strip -%}
{%- assign zone4 = ticket.zone4 | strip -%}
{%- assign alley = ticket.alley | strip -%}
{%- assign entrance = ticket.entrance | strip -%}
{%- assign location = zone3 | append: " " | append: zone4 -%}
{%- if alley -%}
{%- assign location = location | append: " - Allée " | append: alley -%}
{%- endif -%}
{{ location }}
{% case entrance -%}
{%- when "1", "2", "3", "4", "5", "6" -%}Porte 1 · Ascenseur 2
{%- when "7", "8" -%}Côté porte 1 · Ascenseur 1
{%- when "9", "10", "11", "12" -%}Porte 2 · Ascenseur 4
{%- when "13", "14", "15", "16" -%}Porte 3 · Ascenseur 6
{%- endcase -%}
```
**Lister les billets sur une Carte multi-billets**
Ceci est utile pour les achats groupés et les Cartes multi-événements.
```liquid
{% if y2.tickets.size > 0 %}
Vos billets :
{% for ticket in y2.tickets %}
- n°{{ ticket.ticketNumber }} pour {{ ticket.amount }} € le {{ ticket.creationDate | date: "D" }}
{% endfor %}
{% endif %}
```
**Créer un lien profond authentifié**
N'utilisez ce modèle que lorsque la destination prend en charge le flux d'authentification de la Carte.
```liquid
Mettez à jour votre profil ici.
```
### FAQ
Shopify Liquid est-il entièrement pris en charge ?
Non. La Wallet Crew utilise DotLiquid ainsi que les extensions personnalisées documentées sur cette page. Les extensions spécifiques à Shopify ne doivent pas être considérées comme fonctionnelles, sauf si elles sont documentées ici.
Comment trouver le chemin de variable correct ?
Utilisez une vraie Carte, inspectez **Afficher les données**, puis validez l'expression dans l'aperçu. Cela évite de deviner les noms de champs de mémoire.
Pourquoi un champ s'affiche-t-il vide au lieu d'échouer ?
Les variables manquantes se résolvent généralement en une chaîne vide. Les erreurs de syntaxe Liquid se comportent différemment et doivent être traitées comme des défauts de modèle.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.thewalletcrew.io/developers-guides/fr/integration-guides/wallet/liquid-templating.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.