Modélisation Liquid

Rendez les champs dynamiques de la Carte, formatez les valeurs et construisez le contenu de la Carte Wallet avec Liquid.

Gabarit Liquid

Liquid combine du texte fixe avec des valeurs dynamiques provenant 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 vraie Carte.

Exemples concrets

• Une carte de fidélité affiche un solde de points sûr, 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 les fournisseurs connectés.

Inspecter Voir les données sur une vraie Carte avant d’écrire un gabarit. 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 traitées comme une source d’affichage Wallet.

Pour le flux complet de mise à jour et de validation, voir Mettre à jour les données de la Carte dans les gabarits.

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.<key>

Les valeurs manquantes s’affichent comme une chaîne vide. Utilisez default lorsqu’un repli visible est nécessaire.

{{ loyalty.points | default: 0 | floor }}

Bases de la syntaxe

Utilisation {{ ... }} pour afficher une valeur. Utilisez {% ... %} pour la logique qui ne s’affiche pas d’elle-même.

Bienvenue {{ firstName | default: "member" }} !
{% if loyalty.points and loyalty.points > 1000 %}membre VIP{% endif %}
{% assign label = ticket.priceCategory | strip %}

Les filtres s’exécutent de gauche à droite. La notation pointée suit la structure imbriquée de la charge utile de données.

Conditions et boucles

Liquid considère uniquement nil et false comme faux. Le nombre 0 et la chaîne "false" sont considérés comme vrais. Comparez explicitement les nombres facultatifs.

{% 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.

{% if y2.tickets.size > 0 %}
  {% for ticket in y2.tickets %}
    - #{{ ticket.ticketNumber }} le {{ ticket.startDate | date: "D" }}
  {% endfor %}
{% endif %}

Dans une boucle, forloop.index, forloop.first, forloop.last, et forloop.length sont disponibles.

Affectations, branches et espaces

Utilisation assign pour réutiliser les valeurs calculées. Utilisez case pour les correspondances code-libellé.

{% assign category = ticket.priceCategory | strip %}
{% case category %}
  {% when "F" %}Plein tarif
  {% when "R" %}Réduit
  {% else %}{{ category }}
{% endcase %}

Utilisation {%- et -%} pour supprimer les espaces autour. Cela permet de garder des gabarits multilignes compacts dans des champs Wallet étroits.

{%- 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.

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é.

{{ someDate | add_minutes: 60 }}
{{ someDate | add_minutes: 60 | date: "yyyy-MM-dd HH:mm:ss" }}

add_hours

Ajoute le nombre d’heures spécifié.

{{ someDate | add_hours: 24 }}
{{ someDate | add_hours: 24 | date: "yyyy-MM-dd HH:mm:ss" }}

add_seconds

Ajoute le nombre de secondes spécifié.

{{ someDate | add_seconds: 3600 }}
{{ someDate | add_seconds: 3600 | date: "yyyy-MM-dd HH:mm:ss" }}

add_days

Ajoute le nombre de jours spécifié.

{{ someDate | add_days: 7 }}
{{ someDate | add_days: 7 | date: "yyyy-MM-dd" }}

add_timespan

Ajoute une durée au format hh:mm:ss .

{{ 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 la culture invariante pour l’analyse et le formatage.

Filtre de format

format

Applique une chaîne de formatage à toute valeur IFormattable de type IFormattable, comme les nombres, les dates et les énumérations.

{{ loyaltyPoints | format: "N0" }}

Cela affiche un entier groupé tel que 1,234 dans la culture invariante.

{{ 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 rendu.

{% minify https://yoursite.com/account/{{ customer.id }} %}

La balise affiche d’abord l’expression imbriquée, puis crée une URL courte via le service de redirection The Wallet Crew, et enfin renvoie la chaîne d’URL raccourcie.

Valider et dépanner les gabarits

Une variable s’affiche vide

Un chemin manquant ne fait pas échouer le rendu. Il se résout en chaîne vide. Inspectez Voir les données sur une vraie Carte, puis utilisez default là où c’est nécessaire.

{{ loyalty.points | default: 0 }}

Une variable manquante produit généralement un champ vide. Validez les chemins de champ par rapport à un contexte de vraie Carte avant de publier une modification de gabarit.

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.

{{ 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 la culture invariante. Utilisez date pour les dates tenant compte de la locale. Assemblez le texte numérique ou monétaire spécifique à la locale dans chaque fichier de locale lorsque c’est nécessaire.

Un fichier YAML ne s’analyse pas

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 considérés comme vrais. Comparez explicitement les valeurs numériques facultatives.

{% 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.

{%- if ticket.alley -%}
  Allée {{ ticket.alley }}
{%- endif -%}

La syntaxe Liquid littérale est requise

Utilisation raw et endraw.

{% raw %}{{ this is literal }}{% endraw %}

Le gabarit contient une erreur de syntaxe

Un Liquid invalide peut afficher un message d’erreur au lieu de la valeur souhaitée. Considérez les erreurs d’analyse comme des défauts de gabarit et corrigez-les avant la publication.

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 gabarit en production.

Pour le timing du rendu et la gestion des échecs en dehors de Liquid lui-même, voir Comment une Carte est rendue.

Filtres standard

Les filtres DotLiquid standard 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 troncation vide pour créer une initiale :

{{ 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

Utilisation 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.

Recettes

Les modèles suivants répondent aux besoins courants des cartes de fidélité, cartes-cadeaux et 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.

{{ loyalty.points | default: 0 | floor }}

Afficher séparément les points en attente

N’affichez la ligne en attente que lorsque des points attendent validation.

Available: {{ loyalty.points | default: 0 | floor }} pts
{% if pendingLoyaltyPoints and pendingLoyaltyPoints > 0 %}
En attente : {{ pendingLoyaltyPoints }} pts
{% endif %}

Créer un compteur de tampons répétitif

modulo réinitialise le compteur visible après chaque récompense.

{{ additionalData.stampCount | default: 0 | modulo: 10 }} / 10

Le même modèle peut sélectionner une image correspondante :

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.

{% assign threshold = additionalData.next_tier_threshold | default: 100 %}
{% assign missing = threshold | minus: loyalty.points %}
{{ missing | at_least: 0 }} pts jusqu’à {{ additionalData.next_tier_name | default: "votre prochaine récompense" }}

Déduire un nom de niveau

Ce modèle fonctionne lorsque la source fournit uniquement un solde de points.

{% assign points = loyalty.points | default: 0 %}
{% if points >= 5000 %}Membre Or
{% elsif points >= 1000 %}Membre Argent
{% else %}Membre de bienvenue
{% endif %}

Lister les bons disponibles

Affichez les bons au dos de la carte. Un sinon branche rend l’état vide explicite.

{% 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 l’instant.
{% endif %}

Cartes-cadeaux

Réutiliser un identifiant

Utilisez la même valeur pour les champs du code-barres et de saisie manuelle.

barCodeValue: '{{ id.y2.giftCardId }}'
barCodeAlternateText: '{{ id.y2.giftCardId }}'
cardNumber: '{{ id.y2.giftCardId }}'

Afficher un montant variable

Cela utilise un montant cadeau facultatif et un repli sûr.

value: '{{ additionalData.giftAmount | default: 50 }}'

Conservez le montant et la devise séparés

Des champs dédiés permettent aux plateformes Wallet d'appliquer un formatage local de la devise.

value: '{{ voucher.amount }}'
currencyCode: '{{ voucher.currency }}'

Définissez la fenêtre de validité

Utilisez les dates sources pour l'expiration et la pertinence.

relevantDate: '{{ startDate }}'
expirationDate: '{{ expirationDate }}'
start: '{{ startDate }}'
end: '{{ expirationDate }}'

Billets d'événement

Expire après l'événement

Une expiration le jour suivant évite les problèmes de fuseau horaire et d'arrivée tardive.

expirationDate: '{{ ticket.startDate | add_days: 1 | date: "d" }}'

Définissez une fenêtre de pertinence

Cela aide les plateformes Wallet à afficher le billet au bon moment.

start: '{{ ticket.startDate | add_days: 0 | date: "d" }}'
end: '{{ ticket.startDate | add_days: 1 | date: "d" }}'

Affichez la date et l'heure de l'événement

Des champs séparés permettent à la mise en page Wallet de prioriser la date ou l'heure.

l$label-date-apple: '{{ ticket.startDate | date: "M" }}'
l$value-date-apple: '{{ ticket.startDate | date: "t" }}'

Associez les codes de catégorie

case convertit les codes sources en libellés lisibles et spécifiques à la locale.

{% assign category = ticket.priceCategory | strip %}
{% case category %}
  {% when "F" %}Plein tarif
  {% when "R" %}Réduit
  {% when "S" %}Étudiant
  {% when "C" %}Enfant
  {% else %}{{ category }}
{% endcase %}

Construisez les indications pour le lieu

Nettoyez les champs facultatifs avant de les concaténer. Le contrôle des espaces blancs maintient une sortie compacte.

{%- 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é de la porte 1 · Ascenseur 1
  {%- when "9", "10", "11", "12" -%}Porte 2 · Ascenseur 4
  {%- when "13", "14", "15", "16" -%}Porte 3 · Ascenseur 6
{%- endcase -%}

Répertoriez les billets sur une Carte multi-billets

Ceci est utile pour les achats groupés et les Cartes multi-événements.

{% if y2.tickets.size > 0 %}
  Vos billets :
  {% for ticket in y2.tickets %}
    - #{{ ticket.ticketNumber }} pour {{ ticket.amount }} € le {{ ticket.creationDate | date: "D" }}
  {% endfor %}
{% endif %}

Créez un lien profond authentifié

N'utilisez ce modèle que lorsque la destination prend en charge le flux d'authentification de Carte.

Mettez à jour votre profil <a href="{{ publicUrl }}{{ tenantId }}/mobile?neo.authToken={{ authenticationToken }}">ici</a>.

FAQ

Shopify Liquid est-il entièrement pris en charge ?

Non. Wallet Crew utilise DotLiquid ainsi que les extensions personnalisées documentées sur cette page. Il ne faut pas supposer que les extensions spécifiques à Shopify fonctionnent, sauf si elles sont documentées ici.

Comment trouver le bon chemin de variable ?

Utilisez une vraie Carte, inspectez Voir 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.