Introduction à Liquid le moteur de template de Jekyll

8 minutes de lecture art

Voici la liste des fonctionnalités les plus utiles de Liquid, le langage de templating utilisé par Jekyll. Il a été créé à l’origine par Shopify, en Ruby. Mais étant donné la popularité et l’efficacité de ce moteur de templating, il en existe d’autres implémentations, en Javascript par example.

L’un des aspects qui ont popularisé l’utilisation de Liquid, c’est l’interdiction de Github d’utiliser des plug-ins Jekyll écrits en Ruby sur Github Pages. Et au lieu d’utiliser des gems en Ruby, tout un tas de développeurs s’est mis à concocter des “plugins” en utilisant Liquid.

Il faut savoir qu’il y a plusieurs versions de Liquid, avec quelques variations, notamment entre la version originale de Shopify et celle utilisée par jekyll.

Qu’est-ce qu’un langage de templating ?

Les graphistes et développeurs sont parfois amenés à utiliser un langage de templating pour construire des pages contenant du contenu statique, qui est la même sur de multiples pages, ou du contenu dynamique, qui change - lui - d’une page à l’autre.

Un langage de template permet d’utiliser à de multiples endroits des éléments statiques qui définiront l’architecture d’une page web, en reprenant les données de votre site. Les éléments statiques sont écris en HTML, et la partie dynamique en Liquid.

Les éléments Liquid d’un fichier sont exécutés et compilés en html, pour être servis ensuite de manière statique par le serveur.

Introduction

Le code Liquid peut être subdivisé en variables, tags et filtres.

Variables

L’affichage d’une variable se fait avec des doubles accolades. Un exemple simple de variable :

Hello {{page.author}}

Résultat:

Hello art

Dans ce cas, Liquid génère le contenu d’une variable appelée user.name, et la variable contient le texte Arthur.

Tags

Les tags sont représentés par des accolades avec un signe pourcent : {% et %}. Ils permettent d’insuffler une logique algorithmique.

Les tags ne produisent aucun texte visible : vous pouvez mofifier des variables, créer des conditions, cette partie du code ne sera jamais affiché sur votre page finale.

{% if page %}
  Bonjour {{ page.author }} !
{% endif %}

Rendu :

Bonjour art !

Les tags peuvent être catégorisés en 3 types :

Vous pouvez en lire davantage dans les sections respectives.

Filtres

Les filtres modifient le resultat d’une variable. Ils sont utilisés dans une variables et séparés par un |.

Filtrer les variables :

Le mot 'anticonstitutionnellement'
comprend {{ 'anticonstitutionnellement' | size }} lettres !
Nous sommes en {{ 'now' | date: "%Y" }}.

Résultat :

Le mot 'anticonstitutionnellement' comprend 25 lettres !
Nous sommes en 2017.

Il est possible de multiplier les filtres, ils sont alors appliqués de gauche à droite.

{{ "oublié un mot !" | capitalize | prepend: "J'ai " }}

Résultat :

J'ai Oublié un mot !

Tags

Commentaires

Pour ne pas afficher du contenu temporairement, la balise commentest parfaite, de plus, le code Liquid ne sera pas executé.

Nous avons fait 1 million d'euros {% comment %} de perte {% endcomment %} cette année.

Résultat :

Nous avons fait 1 million d'euros  cette année.

Si la modification est permanente, autant enlever vraiment le texte.

Conditions

If

Il est possible d’effectuer de simples conditions tel que if/unless, elsif (et pas elseif !) et else.

{% if page.author == "Hugo" %}
    Hello {{ page.author }} !
{% elsif page.author == "art" %}
    Bonjour maître !
{% else %}
    Who are you?
{% endif %}

Resultat :


    Bonjour maître !

Unless

C’est le contraire de if, il s’execute si la condition n’est pas respecté.

{% unless user.name == "Medor" and user.race == "humain" %}
    Bonjour non-humain non-Medor
{% endunless %}

Resultat

Bonjour non-humain non-Medor

Avec des tableaux :

# array: [1,2,3]
{% if array contains 2 %}
    array includes 2
{% endif %}

Case

L’équivalent d’un switch case est aussi possible, pour gérer un nombre important de conditions d’une même variable. case initialise la condition, et when compare les valeures :

{% case condition %}
    {% when 1 %}
        hit 1
    {% when 2 or 3 %}
        hit 2 or 3
    {% else %}
        don't hit
{% endcase %}

La boucle for

La boucle d’une collection de tableaux :

{% for item in array %}
    {{ item }}
{% endfor %}

Une boucle itérative simple :

{% for i in (1..10) %}
    {{ i }}
{% endfor %}

There are helper variables for special occasions:

  • forloop.length – longueur de la boucle
  • forloop.index – index de l’itération courante
  • forloop.index0 – index de l’itération courante (base zero)
  • forloop.rindex – combien d’éléments reste-il ?
  • forloop.rindex0 – combien d’éléments reste-il ? (base zero)
  • forloop.first – est-ce la première itération ?
  • forloop.last – est-ce la dernière itération ?

Il est possible de délimiter le périmètre d’action de la boucle avec :

  • limit pour le nombre d’élement à traiter
  • offest pour sélectionner la position de début
# array: [1,2,3,4,5,6]
{% for item in array limit:2 offset:2 %}
    {{ item }}
{% endfor %}

Vous pouvez aussi inverser la boucle :

{% for item in array reversed %}
...

Raw

Désactiver les tags :

{% raw %}
    Si j'utilise des {{ tag }} ici, ils ne seront pas interprétés.
{% endraw %}

Résultat :

Si j'utilise des {{ tag }} ici, ils ne seront pas interprétés.

Variable

Assign

Il est possible de créer une nouvelle variable avec assign.

{% assign ma_variable = false %}
{% if ma_variable != true %}
  Ceci est valide
{% endif %}

Resultat :

Ceci est valide

Pour déclarer une chaine, il faut ajouter des guillemets à la variable :

{% assign foo = "bar" %}
{{ foo }}
bar

Capture

Il est aussi possible de combiner plusieurs chaines dans une variables ainsi :

{% assign name = "Arthur" %}
{% assign surname = "Lacoste" %}
{% capture full-name %}{{ name }} {{ surname }}{% endcapture %}
{{ full-name }}

Resultat :

 Arthur Lacoste

Il est ainsi possible de créer des chaînes complexes.

Increment

Pour ajouter 1 à une variable numérique :


{% increment my_counter %}
{% increment my_counter %}
{% increment my_counter %}

Résultat :

0
1
2

Filtres

Voici une liste des filtres les plus communs :

  • where – sélectionne des éléments depuis un tableau pour certaines valeurs : {{ site.posts | where:"category","foo" }}
  • group_by – groupe les éléments depuis un tableau : {{ site.posts | group_by:"category" }}
  • markdownify – convertir le markdown en HTML
  • jsonify – convertir des données en JSON: {{ site.data.dinosaurs | jsonify }}
  • date – reformater une date
  • capitalize – mettre la première lettre en capitale
  • downcase – mettre la phrase en bas de casse
  • upcase – mettre la phrase entière en capitale
  • first – récupérer le premier élément d’un tableau
  • last – récupérer le dernier élément d’un tableau
  • join – joindre les éléments d’un tableau avec certains caractères entre eux
  • sort – trier les éléments d’un tableau : {{ site.posts | sort: 'author' }}
  • size – retourne la taille d’un tableau ou d’une chaîne
  • strip_newlines – enlève tous les retours à la ligne (\n) d’une chaîne
  • replace – remplace toutes les occurences : {{ 'foofoo' | replace:'foo','bar' }}
  • replace_first – remplacer la première occurrence: {{ 'barbar' | replace_first:'bar','foo' }}
  • remove – supprimer chaque occurence : {{ 'foobarfoobar' | remove:'foo' }}
  • remove_first – supprimer la première occurrence: {{ 'barbar' | remove_first:'bar' }}
  • truncate – tronquer la chaîne de x caractères
  • truncatewords – tronquer la chaîne de x mots
  • prepend – ajouter au début d’une chaîne : {{ 'bar' | prepend:'foo' }}
  • append – ajouter à la fin d’une chaîne : {{ 'foo' | append:'bar' }}
  • minus, plus, times, divided_by, modulo – travailler avec les chiffres : {{ 4 | plus:2 }}
  • split – diviser une chaîne selon un motif : {{ "a~b" | split:~ }}

Example

Voici un exemple très utile permettant en utiliant where de filtrer un élément de _data :


{% assign currentItem = site.data.foo | where:"slug","bar" %}
{{ newArray[0].name }}

Permaliens

Les permaliens sont conçu selon le template :

/:categories/:year/:month/:day/:title.html

Voici les variables disponibles :

  • year – année selon le nom du fichier
  • short_year – en version 2 chiffres
  • month – mois selon le nom du fichier
  • i_month – pareil mais sans les zéros de début
  • day – jour selon le nom du fichier
  • i_day – pareil mais sans les zéros de début
  • title – titre selon le nom du fichier
  • categories– catégorie du billet

Erreurs récurrentes

Sur Windows vous pouvez avoir cette erreur en lançant vos commandes :

Liquid Exception: incompatible character encodings: UTF-8 and IBM437 in index.html

C’est que vous devez définir le code-page d’abord :

chcp 65001

Tags :

Catégories :

Dernière mise à jour :

Laisser un commentaire

Votre adresse email ne sera pas visible. Les champs obligatoires sont marqués *

Chargement...
Reçevoir les prochains commentaires de cet article.