Modèles Liquid

Restituez des champs de cartes dynamiques, formatez des valeurs et créez du contenu de cartes Wallet avec 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.

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

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

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.

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

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

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

{%- 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 un intervalle au hh:mm:ss format.

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

{{ loyaltyPoints | format: "N0" }}

Cela affiche un entier groupé tel que 1,234 en 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 généré.

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

{{ loyalty.points | default: 0 }}

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.

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

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

Utilisez raw et endraw.

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

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.

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

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

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.

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

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.

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

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

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

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.

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.

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

Définir la période de validité

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

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.

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.

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.

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.

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

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

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

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