Formater et transformer les données

Les filtres sont des transformateurs de données que vous appliquez à une valeur en utilisant la syntaxe pipe (|). Ils prennent la valeur à gauche, la traitent et produisent le résultat. Vous pouvez chaîner plusieurs filtres pour des transformations plus complexes.

Vous pouvez trouver la liste complète des filtres intégrés dans la documentation officielle de Liquid.

Filtres intégrés

append

Lire la documentation complète de append.

Ajoute la chaîne de caractères spécifiée à la fin d’une autre chaîne.

{{"/my/fancy/url" | append: ".html"}}
→ /my/fancy/url.html

date

Lire la documentation complète de date.

Convertit un timestamp dans un autre format de date. Le format de cette syntaxe est le même que strftime. L’entrée utilise le même format que Time.parse de Ruby.

{{article.published_at | date: "%a, %b %d, %y"}}
→ Fri, Jul 17, 22

{{article.published_at | date: "%Y"}}
→ 2022

date fonctionne sur les chaînes de caractères si elles contiennent des dates bien formatées :

{{"March 14, 2022" | date: "%b %d, %y"}}
→ Mar 14, 22

Pour obtenir l’heure actuelle, passez le mot spécial "now" (ou "today") à date :

Dernière mise à jour : {{"now" | date: "%Y-%m-%d %H:%M"}}
→ Dernière mise à jour : 2022-03-14 12:34

default

Lire la documentation complète de default.

Définit une valeur par défaut pour toute variable sans valeur assignée. default affichera sa valeur si l’entrée est nil, false ou vide.

Quand product_price n’est pas défini, la valeur par défaut est utilisée :

{{product_price | default: 2.99}}
→ 2.99

Quand product_price est défini, la valeur par défaut n’est pas utilisée :

{% assign product_price = 4.99 %}
{{product_price | default: 2.99}}
→ 4.99

Quand product_price est vide, la valeur par défaut est utilisée :

{% assign product_price = "" %}
{{product_price | default: 2.99}}
→ 2.99

newline_to_br

Lire la documentation complète de newline_to_br.

Insère un saut de ligne HTML (<br />) devant chaque retour à la ligne () dans une chaîne de caractères.

{{"Hello\nWorld" | newline_to_br}}
→ Hello<br />
  World

where

Lire la documentation complète de where.

Crée un tableau contenant uniquement les objets ayant une valeur de propriété donnée, ou toute valeur truthy par défaut.

Dans cet exemple, supposons que vous ayez une liste de produits et que vous souhaitiez afficher vos produits de cuisine séparément. En utilisant where, vous pouvez créer un tableau contenant uniquement les produits qui ont un "type" de "kitchen".

Tous les produits :
{% for product in products %}
- {{ product.title }}
{% endfor %}

{% assign kitchen_products = products | where: "type", "kitchen" %}

Produits de cuisine :
{% for product in kitchen_products %}
- {{ product.title }}
{% endfor %}

Tous les produits :
- Aspirateur
- Spatule
- Télévision
- Presse-ail

Produits de cuisine :
- Spatule
- Presse-ail

Filtres PDFMonkey

Filtres de tableaux

push

Ajoute un élément à un tableau.

{% assign arr = "terre vent" | split: " " %}
{% assign arr = arr | push: "feu" %}

{{arr | to_sentence}}
→ terre, vent and feu

slice_by

Découpe un tableau en groupes de N éléments.

{% assign reindeers = "Dasher Dancer Prancer Vixen Comet Cupid Donner Blitzen Rudolph" | split: " " %}
{% assign reindeerPairs = reindeers | slice_by: 2 %}

{% for reindeerPair in reindeerPairs %}
  Paire :
  {% for reindeer in reindeerPair %}
    - {{reindeer}}
  {% endfor %}
{% endfor %}

  Paire :
    - Dasher
    - Dancer
  Paire :
    - Prancer
    - Vixen
  Paire :
    - Comet
    - Cupid
  Paire :
    - Donner
    - Blitzen
  Paire :
    - Rudolph

sum

Retourne la somme d’un tableau de nombres.

Supposons que vous ayez ceci dans vos données :

{
  "array": [1, 2, 3, 4, 5]
}

{{array | sum}}
→ 15

to_sentence

Convertit le tableau en une phrase séparée par des virgules où le dernier élément est relié par un mot de liaison.

{% assign arr = "terre vent" | split: " " %}
{% assign arr = arr | push: "feu" %}

{{arr | to_sentence}}
→ terre, vent and feu

{{arr | to_sentence: ' - '}}
→ terre - vent and feu

{{arr | to_sentence: ' - ', 'et enfin '}}
→ terre - vent et enfin feu

where_exp

Similaire au filtre where de Liquid, mais accepte une expression.

Commençons par les données :

{
  "products": [
    { "name": "Produit 1", "price": 1.00 },
    { "name": "Produit 2", "price": 2.00 },
    { "name": "Produit 3", "price": 3.00 },
    { "name": "Produit 4", "price": 2.00 },
    { "name": "Produit 5", "price": 1.00 }
  ]
}

{% assign cheapProducts = products | where_exp: "prod", "prod.price < 1" %}

{% for product in cheapProducts %}
- {{product.name}}
{% endfor %}

- Produit 1
- Produit 5

Filtres de date et heure

in_time_zone

Décale une date vers le fuseau horaire donné avant le formatage.

{{"2050-01-02 12:34:56" | in_time_zone: "Pacific/Galapagos" | date: "%Y-%m-%d %H:%M"}}
→ 2050-01-02 06:34

Filtres d’URL

ensure_protocol

Il peut arriver que vous receviez des URLs d’assets sans protocole. Malheureusement, notre moteur de rendu ne prend pas en charge ce type d’URL. C’est pourquoi nous fournissons ensure_protocol qui ajoutera un protocole si nécessaire :

{{"//example.com/some-picture.jpg" | ensure_protocol}}
→ https://example.com/some-picture.jpg

{{"//example.com/some-picture.jpg" | ensure_protocol: "http"}}
→ http://example.com/some-picture.jpg

{{"http://example.com/some-picture.jpg" | ensure_protocol}}
→ http://example.com/some-picture.jpg

Filtres de nombres

Voir aussi Faire des calculs pour les filtres arithmétiques et des exemples pratiques de calcul.

format

Le filtre format est utile pour le formatage avancé de nombres. Pour un formatage plus simple, préférez with_delimiter.

{{5 | format: "%05d"}}
→ 00005

{{5 | format: "%08.3f"}}
→ 0005.000

{{5 | format: "%.2f"}}
→ 5.00

{{5.1234 | format: "%.2f"}}
→ 5.12

with_delimiter

Pour le formatage basique de nombres comme les montants monétaires par exemple, le filtre with_delimiter vous aidera à définir un séparateur de milliers, un séparateur décimal et la précision.

Utilisation de base — ajoute une virgule tous les trois chiffres par défaut :

{{12345678 | with_delimiter}}
→ 12,345,678

{{1234.567 | with_delimiter}}
→ 1,234.567

Le texte non numérique n’est pas modifié :

{{'12345a' | with_delimiter}}
→ 12345a

Séparateur personnalisé — changer le séparateur de milliers :

{{12345678 | with_delimiter, delimiter: " "}}
→ 12 345 678

Précision — contrôler le nombre de décimales :

{{12345678 | with_delimiter, precision: 2}}
→ 12,345,678.00

{{1234.567 | with_delimiter, precision: 2}}
→ 1,234.57

Supprimer les zéros non significatifs :

{{12345678 | with_delimiter, precision: 2, strip_insignificant_zeros: true}}
→ 12,345,678

{{1234.567 | with_delimiter, precision: 2, strip_insignificant_zeros: true}}
→ 1,234.57

Combinaison d’options — par exemple, un formatage à l’européenne :

{{1234.567 | with_delimiter,
  delimiter: " ",
  separator: ",",
  precision: 2,
  strip_insignificant_zeros: true
}}
→ 1 234,57

{{1234.003 | with_delimiter,
  delimiter: " ",
  separator: ",",
  precision: 2,
  strip_insignificant_zeros: true
}}
→ 1 234

Filtres HTML

entities

Ce filtre peut être très utile si vous devez gérer des caractères accentués ou spéciaux dans l’en-tête ou le pied de page. Il convertira tout caractère non-latin en son entité HTML.

{{"Marie Skłodowska Curie" | entities}}
→ Marie Skłodowska Curie

Filtres JSON

json

Si vous avez besoin d’insérer des données dynamiques dans leur format JSON d’origine (comme nous le faisons pour les graphiques par exemple), le filtre json est ce qu’il vous faut. Notez qu’il retourne une chaîne de caractères, pas l’objet lui-même.

{{'banana, apple' | split: ', ' | json}}
→ ["banana", "apple"]

parse_json

Transforme une chaîne JSON en objet ou tableau utilisable. Ce filtre est particulièrement utile lorsqu’une intégration (comme Glide ou un webhook) ne peut envoyer que des valeurs textuelles simples : vous transmettez les données structurées sous forme de chaîne JSON et les analysez dans le modèle.

{% assign obj = ‘{ "key": "value" }’ | parse_json %}
{{obj.key}}
→ value

Vous pouvez aussi analyser des tableaux et les parcourir en boucle :

{% assign items = ‘[{"name":"Waffle","qty":12},{"name":"Donut","qty":5}]’ | parse_json %}
{% for item in items %}
  {{item.name}} x{{item.qty}}
{% endfor %}
→ Waffle x12
  Donut x5

Si l’entrée est vide ou n’est pas du JSON valide, parse_json renvoie nil par défaut. Vous pouvez fournir une valeur de repli en argument :

{% assign data = invalidVariable | parse_json: "fallback" %}
{{data}}
→ fallback

Questions fréquentes

Comment formater des nombres avec des séparateurs de milliers dans PDFMonkey ?

Utilisez le filtre with_delimiter. Par exemple, {{ 12345678 | with_delimiter }} produit 12,345,678. Vous pouvez personnaliser le délimiteur, le séparateur décimal et la précision avec des arguments nommés.

Comment formater des dates dans un template Liquid PDFMonkey ?

Utilisez le filtre date avec les codes de format strftime. Par exemple, {{ article.published_at | date: "%b %d, %Y" }}. Pour convertir dans un fuseau horaire spécifique d’abord, chaînez le filtre in_time_zone avant date.

Comment parser une chaîne JSON dans un template PDFMonkey ?

Utilisez le filtre parse_json pour convertir une chaîne JSON en objet ou tableau que vous pouvez parcourir. Par exemple : {% assign items = jsonString | parse_json %}. C’est particulièrement utile quand des intégrations comme Glide ne peuvent envoyer que des valeurs sous forme de chaînes de caractères.

Comment gérer les caractères accentués dans les en-têtes et pieds de page PDFMonkey ?

Utilisez le filtre entities pour convertir les caractères non-latins en entités HTML. Par exemple, {{ company.name | entities }} convertit « é » en é, ce qui s’affiche correctement dans les en-têtes et pieds de page via les paramètres.