> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Utilisation de la syntaxe Liquid

> Personnalisez le contenu des e-mails, push, SMS, in-app et Live Activity avec des balises, filtres, conditionnels et boucles Liquid — alimenté par les sources de données OneSignal comme les balises, propriétés, données personnalisées et Data Feeds.

Liquid est un langage de template pris en charge par OneSignal pour personnaliser les messages sur tous les canaux, y compris l'e-mail, le push, les SMS, l'in-app et les Live Activities. Il utilise des balises, des filtres et des conditionnels pour personnaliser dynamiquement le contenu des messages.

Pour en savoir plus sur la syntaxe Liquid, consultez la [documentation Liquid officielle](https://shopify.github.io/liquid/basics/introduction/).

## Syntaxe de base

Liquid utilise deux structures de syntaxe principales :

1. **Balises de sortie** : `{{ ... }}` — Affiche les données d'une variable ou d'un objet.
2. **Balises logiques** : `{% ... %}` — Exécute des instructions conditionnelles ou des boucles.

## Conditionnels

### Opérateurs

* `==`, `!=`, `>`, `<`, `>=`, `<=`
* `and`, `or`
* `contains` (chaîne ou tableau)

```text liquid theme={null}
{% if true or false and false %}
  This is true.
{% endif %}
```

### `if`, `elsif`, `else`

```text liquid theme={null}
{%- assign userLang = subscription.language -%}
{% if userLang == "es" -%}
Hola {{ first_name }}!
{%- elsif userLang == "fr" -%}
Bonjour {{ first_name }}!
{%- else -%}
Hello {{ first_name }}!
{%- endif %}
```

### `unless`

```text liquid theme={null}
{% unless level == "1" %}
  Great job getting past the first level!
{% endunless %}
```

***

## Filtres

Appliquez des filtres en utilisant `{{ variable | filter }}` pour ajuster la façon dont les données sont affichées.

### `default`

Attribue une valeur par défaut si la propriété est vide ou n'existe pas.

```text liquid theme={null}
Hello {{ first_name | default: "there" }}.
```

### `date`

Le filtre date convertit un timestamp en un autre format de date. Le format de cette syntaxe est le même que [strftime](https://strftime.net/). L'entrée utilise le même format que la méthode [Time.parse](https://ruby-doc.org/stdlib-2.4.1/libdoc/time/rdoc/Time.html) de Ruby.

Définissez les dates comme un timestamp unix en secondes avec des tags. Cela permet d'utiliser à la fois la personnalisation avec la syntaxe Liquid et la segmentation avec les [Opérateurs de temps](./time-operators). Par exemple, un tag pourrait ressembler à : `bill_due : 1687968776`

```text liquid theme={null}
{{ bill_due | date: "%a, %b %d, %y" }}
{{ "now" | date: "%Y-%m-%d %H:%M" }}
```

```text Result theme={null}
Wed, Jun 28, 23
```

```text liquid theme={null}
{{ bill_due | date: "%Y" }}
```

```text Result theme={null}
2023
```

Le formatage de date fonctionne sur les chaînes si elles contiennent des dates bien formatées.

```text liquid theme={null}
{{ "March 14, 2016" | date: "%b %d, %y" }}
```

```text Result theme={null}
Mar 14, 16
```

Pour obtenir l'heure actuelle, passez le mot spécial `now` (ou `today`) avec le filtre date.

```text liquid theme={null}
This message was sent at {{ "now" | date: "%Y-%m-%d %H:%M" }}.
```

```text Result theme={null}
This message was sent at 2022-11-02 14:39.
```

<Info>
  L'heure actuelle sera affichée dans le message en fonction du moment où le message est
  envoyé au destinataire. Si vous testez le message, vous verrez l'heure
  actuelle comme étant celle de l'envoi du message de test.
</Info>

### `capitalize`

Ce filtre met en majuscule le premier caractère d'une chaîne et convertit les caractères restants en minuscules.

```text liquid theme={null}
{{ "my GREAT title" | capitalize }}
```

```text Result theme={null}
My great title
```

### `round`

Ce filtre arrondit un nombre à l'entier le plus proche ou, si un nombre est passé en argument, à ce nombre de décimales.

```text liquid theme={null}
{{ 1.2 | round }}
  {{ 2.7 | round }}
{{ 183.357 | round: 2 }}
```

```text Result theme={null}
1
3
183.36
```

### `pluralize`

Ce filtre retourne la forme singulière ou plurielle d'une chaîne en fonction d'un nombre donné. Le nombre doit être un nombre entier et peut être fourni sous forme de chaîne. Les formes singulière et plurielle d'une chaîne doivent être fournies.

```text liquid theme={null}
{{ 1 | pluralize: "singular", "plural" }}
{{ 2 | pluralize: "singular", "plural" }}
1 {{ 1 | pluralize: "person", "people" }}
2 {{ 2 | pluralize: "person", "people" }}
2 {{ "2" | pluralize: "person", "people" }}
```

```text Result theme={null}
singular
plural
1 person
2 people
2 people
```

***

## Itération

### Boucles `for`

Exécute à plusieurs reprises un bloc de code. Pour une liste complète des attributs disponibles dans une boucle `for`, consultez la [documentation de la boucle `for` Liquid](https://shopify.github.io/liquid/tags/iteration/).

```text liquid theme={null}
{% for product in message.custom_data.products %}
  - {{ product.name }}
  {% else %}
    Sorry, we're sold out of all products.
  {% endfor %}
```

```json Request Body theme={null}
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "custom_data": {
    "products": [
      { "name": "Sweater" },
      { "name": "Hat" },
      { "name": "Shirt" }
    ]
  }
}
```

```text Result theme={null}
- Sweater
- Hat
- Shirt

(Si message.custom_data.products est vide)
Désolé, nous n'avons plus aucun produit en stock.
```

<Warning>
  Bien que puissante et flexible, l'utilisation de boucles `for` dans la syntaxe Liquid peut
  entraîner de mauvaises performances de livraison de notifications dans certains cas rares. Soyez
  attentif à votre utilisation des boucles `for`. Notez également que nous empêchons l'utilisation de
  boucles `for` dans quelques champs du canal Push : `contents`, `headings`, `subtitle`,
  `apns_alert` et `url`
</Warning>

### `limit` & `offset`

Limite la boucle au nombre d'itérations spécifié. Par exemple, si vous voulez uniquement afficher 4 produits dans un message, vous pouvez utiliser Limits et Offsets pour spécifier le nombre de produits affichés.

```text Data theme={null}
great_numbers = [1,2,3,4,5,6]
```

```text liquid theme={null}
{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}
```

```text Result theme={null}
1 2
```

Pour commencer la boucle à l'index spécifié, ajoutez une valeur offset :

```text Data theme={null}
great_numbers = [1,2,3,4,5,6]
```

```text liquid theme={null}
{% for number in great_numbers limit: 3 %}
  {{ number }}
{% endfor %}

{% for number in great_numbers limit: 3 offset: 3 %}
  {{ number }}
{% endfor %}
```

```text Result theme={null}
1 2 3
4 5 6
```

### `where`

Crée un tableau incluant uniquement les objets avec une valeur de propriété donnée, ou toute valeur vraie 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 ayant un `type` de `kitchen`.

```text Data theme={null}
products = [
  {name:"Vacuum", type:"electronics"},
  {name:"Spatula", type:"kitchen"},
  {name:"Television", type:"electronics"},
  {name:"Garlic press", type:"kitchen"}
]
```

```text liquid theme={null}
All products:
{% for product in products %}
- {{ product.name }}
{% endfor %}

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

Kitchen products:
{% for product in kitchen_products %}
- {{ product.name }}
{% endfor %}
```

```text Result theme={null}
All products:
  - Vacuum
  - Spatula
  - Television
  - Garlic press

Kitchen products:
- Spatula
- Garlic press
```

***

## Manipulation de chaînes

Appliquez des filtres de chaîne pour ajuster la façon dont les valeurs de balises ou les chaînes en ligne sont affichées dans les messages.

| Commande        | Description                                                                                             | Exemple                                                  | Sortie d'exemple |
| --------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ---------------- |
| `replace`       | Remplace une sous-chaîne par une autre chaîne.                                                          | `{{ 'hello world' \| replace: 'world', 'there' }}`       | hello there      |
| `capitalize`    | Met en majuscule la première lettre d'une chaîne.                                                       | `{{ 'hello' \| capitalize }}`                            | Hello            |
| `upcase`        | Convertit une chaîne en majuscules.                                                                     | `{{ 'hello' \| upcase }}`                                | HELLO            |
| `downcase`      | Convertit une chaîne en minuscules.                                                                     | `{{ 'HELLO' \| downcase }}`                              | hello            |
| `strip`         | Supprime les espaces blancs de début et de fin d'une chaîne.                                            | `{{ ' hello ' \| strip }}`                               | hello            |
| `strip_html`    | Supprime toutes les balises HTML d'une chaîne.                                                          | `{{ '<p>hello</p>' \| strip_html }}`                     | hello            |
| `truncate`      | Raccourcit une chaîne à une longueur spécifiée, en ajoutant des points de suspension (…) si nécessaire. | `{{ 'This is a long sentence' \| truncate: 10 }}`        | This is a…       |
| `truncatewords` | Tronque une chaîne après un certain nombre de mots.                                                     | `{{ 'This is a long sentence' \| truncatewords: 2 }}`    | This is…         |
| `replace_first` | Remplace la première occurrence d'une sous-chaîne.                                                      | `{{ 'hello world' \| replace_first: 'world', 'there' }}` | hello there      |
| `prepend`       | Ajoute une chaîne au début d'une autre chaîne.                                                          | `{{ 'world' \| prepend: 'hello ' }}`                     | hello world      |
| `append`        | Ajoute une chaîne à la fin d'une autre chaîne.                                                          | `{{ 'hello' \| append: ' world' }}`                      | hello world      |
| `lstrip`        | Supprime les espaces blancs de début d'une chaîne.                                                      | `{{ ' hello' \| lstrip }}`                               | hello            |
| `rstrip`        | Supprime les espaces blancs de fin d'une chaîne.                                                        | `{{ 'hello ' \| rstrip }}`                               | hello            |

***

## FAQ

### Pourquoi la substitution ne fonctionne-t-elle pas ?

* Les messages in-app ne prennent pas en charge la substitution de propriétés.
* La substitution de tags ne fonctionne pas lors de l'utilisation de « Send Test Message ».
* Les clés de tags doivent être alphanumériques, ou utiliser \_ et - (pas de points ni d'espaces).
* La substitution n'apparaît pas en mode aperçu — envoyez un vrai message pour tester.

### Quand dois-je utiliser `default` plutôt que `if/else` ?

Utilisez le **filtre `default`** lorsque seule la valeur de la variable nécessite un fallback et que le texte environnant reste le même.

```text liquid theme={null}
Hello {{ name | default: "there" }}!
```

```text Result (name = "Jon") theme={null}
Hello Jon!
```

```text Result (name est vide) theme={null}
Hello there!
```

Utilisez la **logique conditionnelle `if/else`** lorsque le texte environnant, la ponctuation ou la structure de la phrase doit également changer selon que la variable existe ou non.

```text liquid theme={null}
{% if name %}{{ name }}, shop your favorites!{% else %}Shop your favorites!{% endif %}
```

```text Result (name = "Jon") theme={null}
Jon, shop your favorites!
```

```text Result (name est vide) theme={null}
Shop your favorites!
```

<Warning>
  N'utilisez pas `default` lorsque la structure de la phrase change. Par exemple, `{{ name | default: "Shop your favorites" }}, shop your favorites` rendrait « Shop your favorites, shop your favorites » lorsque le nom est vide. Si le fallback change plus que juste la variable, utilisez `if/else`.
</Warning>

### Comment contrôler les espaces blancs et les sauts de ligne ?

Utilisez des tirets : `{{- ... -}}`, `{%- ... -%}` pour supprimer les espaces blancs environnants.
Consultez [Contrôle des espaces blancs](https://shopify.github.io/liquid/basics/whitespace/) pour plus de détails.

### Comment gérer le contenu généré par l'utilisateur ?

Enveloppez le texte généré par l'utilisateur dans `{% raw %}` et `{% endraw %}` pour empêcher l'analyse Liquid. Consultez [syntaxe "raw"](https://shopify.dev/docs/api/liquid/tags/raw).

```json theme={null}
{
  "contents": {
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}"
  }
}
```

***

## Pages associées

<Columns cols={2}>
  <Card title="Personnalisation des messages" icon="wand-magic-sparkles" href="./message-personalization">
    Vue d'ensemble de toutes les options de personnalisation, y compris Liquid, Data Feeds et les événements personnalisés.
  </Card>

  <Card title="Data Feeds" icon="database" href="./data-feeds">
    Récupérez des données en temps réel depuis vos API dans les messages au moment de l'envoi.
  </Card>

  <Card title="Balises" icon="tag" href="./add-user-data-tags">
    Stockez des paires clé-valeur sur les utilisateurs pour la segmentation et la personnalisation Liquid.
  </Card>

  <Card title="Modèles" icon="file-lines" href="./templates">
    Créez des modèles de messages réutilisables avec la personnalisation Liquid intégrée.
  </Card>
</Columns>