Syntaxe de base du langage Liquid (personnalisation des documents 1/2)

Publication : . Dernière mise à jour :

Introduction à la syntaxe de base du langage Liquid des gabarits de documents, ainsi qu’aux tags et filtres spécifiques à iScriba.

Bases

Il existe deux types de balisage en Liquid : le balisage d’affichage “Output” et le balisage de méthode “Tag”.

Le balisage d’affichage est entouré de

{{ deux accolades }} 

Le balisage de méthode est entouré de

{% une accolade et un signe pourcentage %} 

Les balises d'affichage seront toujours remplacées par la variable qu’elles référencent. Par exemple, si votre gabarit est exposé à une variable “account”, vous pouvez afficher le nom de votre société en référençant

{{ account.company.name }} 

Les balises de méthode sont responsables de la logique dans les gabarits. Elles servent par exemple à faire des boucles ou des structures de contrôle tel que If / Else.

Balisage d’affichage (output)

Quelques exemples simple de balisage d’affichage :

Bonjour {{ 'Matthieu' }}
N° de facture liée : {{ document.related_invoice_number }} 
Montants exprimés en {{ document.currency }} ({{ document.currency_name }}) 

Filtres

Les balises d’affichage peuvent accepter des filtres. Les filtres sont des méthodes simples qui peuvent avoir des paramètres optionnels. Lorsque vous utilisez un filtre, l’affichage est toujours effectué à partir de la première valeur à gauche du filtre. La valeur de retour du filtre sera la nouvelle valeur à gauche quand le prochain filtre est exécuté. Lorsqu’il n’y a plus de filtre à exécuter, la chaîne filtrée est affichée.

Bonjour ! Matthieu contient {{ 'Matthieu' | size }} lettres.
Bonjour {{ 'Matthieu Fauveau' | truncatewords: 1 | downcase }} ! 

Liste des filtres spécifiques à Liquid

  • capitalize
    Renvoie une chaîne en majuscules.
  • downcase
    Renvoie une chaîne en minuscules.
  • upcase
    Renvoie une chaîne en majuscules.
  • first
    Renvoie le premier élément d’un tableau.
    Par exemple :
    {{ document.line_items | first }} 
  • last
    Renvoie le dernier élément d’un tableau.
    Par exemple :
    {{ document.line_items | last }} 
  • join
    Rassemble les éléments d’un tableau en une chaîne.
    Par exemple :
    {{ document.line_items | join: '<br />' }} 
  • sort
    Trie les éléments d'un tableau.
  • size
    Renvoie le nombre d’éléments d’un tableau ou le nombre de caractères d’une chaîne.
  • escape
    Ajoute des antislashs dans une chaîne.
  • strip_html
    Supprime les balises HTML dans une chaîne.
  • strip_newlines
    Supprime les nouvelles lignes (\n) dans une chaîne.
  • newline_to_br
    Remplace les nouvelles lignes (\n) par la balise HTML <br /> dans une chaîne.
  • replace
    Remplace toutes les occurrences dans une chaîne.
    Par exemple :
    {{ 'foofoo' | replace:'foo','bar' }} #=> 'barbar' 
  • replace_first
    Remplace la première occurence dans une chaîne.
    Par exemple :
    {{ 'barbar' | replace_first:'bar','foo' }} #=> 'foobar' 
  • remove
    Supprime toutes les occurrences dans une chaîne.
    Par exemple :
    {{ 'foobarfoobar' | remove:'foo' }} #=> 'barbar' 
  • remove_first
    Supprime la première occurence dans une chaîne.
    Par exemple :
    {{ 'barbar' | remove_first:'bar' }} #=> 'bar' 
  • truncate
    Tronque une chaîne d’un nombre de caractères.
    Par exemple :
    {{ 'Lorem ipsum dolor sit amet' | truncate: 8 }} #=> Lorem ip 
  • truncatewords
    Tronque une chaîne d’un nombre de mots.
    Par exemple :
    {{ 'Lorem ipsum dolor sit amet' | truncatewords: 2 }} #=> Lorem ipsum 
  • prepend
    Ajoute une chaîne au début d'un mot.
    Par exemple :
    {{ 'bar' | prepend:'foo' }} #=> 'foobar' 
  • append
    Ajoute une chaîne à la fin d'un mot.
    Par exemple :
    {{ 'foo' | append:'bar' }} #=> 'foobar' 
  • minus
    Soustraction.
    Par exemple :
    {{ 4 | minus:2 }} #=> 2 
  • plus
    Addition.
    Par exemple :
    { '1' | plus:'1' }} #=> '11', {{ 1 | plus:1 }} #=> 2 
  • times
    Multiplication.
    Par exemple :
    {{ 5 | times:4 }} #=> 20 
  • divided_by
    Division.
    Par exemple :
    {{ 10 | divided_by:2 }} #=> 5 
  • split
    Éclate une chaîne par expression rationnelle.
    Par exemple :
    {{ "a~b" | split:~ }} #=> ['a','b'] 
  • modulo
    Le reste (en mathématique).
    Par exemple :
    {{ 3 | modulo:2 }} #=> 1 

Liste des filtres spécifiques à iScriba

  • date_format
    Formate une date.
    Par exemple :
    {{ document.date | date_format: language, 'short' }} 
    {{ document    .date | date_format: language, 'medium' }}
    {{ document    .date | date_format: language, 'long' }}
    {{ document    .date | date_format: language, 'full' }} 

    Le second paramètre peut également prendre des valeurs de format de la fonction PHP strftime(). Ces paramètres sont : %d, %D, %A, %m, %b, %B, %e, %y et %Y.
  • number_format
    Formate un nombre.
    Par exemple :
    {{ 10000 | number_format: 2, ',', ' ' }} 

    Le premier paramètre est le nombre de chiffres décimaux. Le second paramètre est le séparateur de décimal. Le troisième paramètre est le séparateur de centaine.
  • price_format
    Formate un prix.
    Par exemple :
    {{ 10000 | price_format: document.currency }} 
  • tax_format
    Formate un pourcentage de tax. Fonctionne de la même façon que number_format.
  • percentage_format
    Formate un pourcentage. Fonctionne de la même façon que number_format.
  • weight_format
    Formate un poids. Fonctionne de la même façon que number_format mais prend un paramètre d’unité de poids.
    Par exemple :
    {{ 10 | weight_format: document.mass_unit, 2, '.', ' ' }} 

Balisage de méthode (tags)

Les tags sont des méthodes disponibles au sein de vos gabarits.

Affectation de variable

Vous pouvez stocker des données dans vos propres variables que vous pouvez choisir d’afficher ou d’utiliser dans un tag. La façon la plus simple pour affecter une variable est d’utiliser le tag “assign” dont la syntaxe est assez simple :

{% assign name = 'Matthieu' %} 
{% for line_item in document.line_items %} 
    {% if line_item.description == name %} Matthieu ! {% endif %} 
{% endfor %} 

Une autre façon d’y parvenir serait d’attribuer des valeurs de type vrai ou faux à la variable :

{% assign name = false %} 
{% for line_item in document.line_items %}
    {% if line_item.description == name %}{% assign name = true %}{% endif %}
{% endfor %} 

{% if name %} Matthieu ! {% endif %} 

Si vous souhaitez combiner un certain nombre de chaînes de caractères en une chaîne unique et l’enregistrer dans une variable, vous pouvez le faire avec le tag capture. Cette balise est un bloc qui “prend” tout ce qui est exécuté à l’intérieur et l’affecte à la variable donnée plutôt que de l’afficher à l’écran. Voici comment l’utiliser :

{% capture my_string %}
    {{ 10000 | number_format: 2, '.', ',' }} days 
{% endcapture %} 
{{ my_string }} 

Instructions If / Else

L’instruction if est une des plus importantes instructions de tous les langages. Liquid vous permet d’écrire des instructions simples avec If. Par exemple :

{% if client %} Bonjour {{ client.name }} ! {% endif %} 
{% if client.name == 'Matthieu' %} Bonjour Matthieu ! {% endif %}
{% if client.name != 'Matthieu' %} Vous n’êtes pas Matthieu. {% endif %} 
{% if client.address == null %} Pas d’adresse dans nos fichiers. {% endif %} 
{% if document.line_items == empty %} Pas d’articles dans ce document. {% endif %}
{% if document.due_total > 0 %} Vous devez payer ce document. {% else %} Merci d’avoir payer ! {% endif %} 

Instruction Case

L’instruction case équivaut à une série d’instructions. Dans certaines occasions vous pouvez avoir besoin de comparer plusieurs fois la même variable (ou expression) avec un grand nombre de valeurs différentes. C’est à cela que sert Case.

{% case line_item.kind %}
    {% when 1 %} Service 
    {% when 2 %} Heures 
    {% when 3 %} Jours 
    {% when 4 %} Produit 
{% endcase %} 

Instruction Cycle

Vous pourriez avoir besoin d’alterner entre différentes valeurs. C’est ce que permet l’instruction Cycle.

{% cycle 1, 2, 3 %}
{% cycle 1, 2, 3 %}
{% cycle 1, 2, 3 %}
{% cycle 1, 2, 3 %} 

donnera :

1 2 3 1 

Si aucun nom n’est fourni pour le groupe de cycle, alors Liquid assume que les appels multiples avec les mêmes paramètres sont un groupe.

Si vous voulez avoir un contrôle total sur les groupes de cycle, vous pouvez éventuellement spécifier le nom du groupe. Cela peut même être une variable.

{% cycle 'group_1': 1, 2, 3 %} 
{% cycle 'group_1': 1, 2, 3 %} 
{% cycle 'group_2': 1, 2, 3 %}
{% cycle 'group_2': 1, 2, 3 %} 

donnera :

1 2 1 2 

Boucles For

La boucle For est un moyen simple d’implémenter une boucle en Liquid. Dans iScriba, cette instruction est particulièrement utile pour afficher les lignes de documents.

{% for line_item in document.payments.line_items %} 
    {{ line_item.method }} 
    {% if line_item.ref_number %}{{ line_item.ref_number }}{% else %}n/c{% endif %} 
{% endfor %} 

Fragments

Il y a des fragments par défaut dans iScriba mais le système vous permet de créer autant de fragment que vous le souhaitez.

Les fragments vous permettent de réutiliser des parties de code CSS ou HTML (contenant de la syntaxe Liquid) pour les intégrer au sein d’un gabarit. Par exemple, pour afficher les adresses sur un document, iScriba utilise le fragment “default_addresses” :

{% include 'default_addresses' %} 

Voici la liste des fragments disponibles par défaut dans iScriba :

  • default_stylesheet
    Feuille de style par défaut des documents.
  • default_addresses
    Bloc qui affiche les adresses.
  • default_logo_or_company_name
    Bloc qui affiche le nom ou le logo de votre société (si disponible).
  • default_items_table
    Bloc qui affiche le tableau des articles.
  • default_packinglist_items_table
    Bloc qui affiche le tableau des articles pour les bons de livraisons.
  • default_payments_table
    Bloc qui affiche le tableau des paiements.