Guida a Liquid - template e newsletter dinamiche in stampa unione

Liquid è un metalinguaggio per creare contenuti dinamici all’interno di email e stampe del CRM ideato per il motore di e-commerce Shopify).

Esistono due tipi di markup in Liquid: output e i tag.

Output markup (che si traduce nel testo corrispondente) è racchiuso tra graffe

{{ nomeutente }}

Tag markup (che è un commando) è racchiuso tra graffe e parentesi

{% if <CONDITION> %} ... {% endif %}

Output

Le espressioni sono affermazioni che hanno dei valori. I template scritti in Liquid possono usare le espressioni in diversi punti; più spesso nelle istruzioni di output, ma anche come argomenti per alcuni tag o filtri.

Senza entrare in esempi troppo complicati, vediamo come gestire Variabili, Stringe e interi.

Un esempio di stringa è:

Ciao {{ 'Utente' }}

Chiaramente questo esempio è poco utile perchè stamperà

Ciao Utente

ma fa capire come funziona il linguaggio. Ad esempio se utilizziamo una variabile invece:

Ciao {{ Name }}

il sistema cercherà la variabile name nella rubrica e stamperà

Ciao Stefano

E' poi possibile applicare dei filtri alle variabili concatenandole con il simboolo | (pipe). Eventuali parametri vanno inseriti dopo i : (duepunti).
Ad esempio:

{{ now | date: 'yyyy' }} => 2020
{{ name | default: 'ignoto' }} => Stefano o se non definito (vuoto) ignoto
Ciao {{ 'Utente' | upcase }} => UTENTE
{{ 'buon' | append:'giorno' }} => buongiorno

e così via. I filtri supportati sono molti, ma riportiamo in fondo alla guida quelli più utilizzati.

Tag

I tag vengono utilizzati per la logica nel vostro template.

{% if name == 'stefano' %}
  Benvenuto Comandante
{% else %}
  Benvenuto utente
{% endif %}

Di solito le condizioni sono sufficienti per l'uso quotidiano, comunque sono state implementate tutte le logiche del linguaggio Liquid:

assign - assegna un valore ad una variabile
capture - cattura il testo contenuto nel blocco e lo assegna ad una variabile
case - è lo standard case ... when
cycle - è utilizzato per ciclare dei valori all'interno di un loop (utile per alternare i colori ad ogni riga in una tabella)
for - il classico ciclo for
if - la codizione if/else
unless - la codizione inversa di if/else
include - include un altro template - {% include nomefile.html %}
comment - non stampa il contenuto
ifchanged - è utilizzato all'interno di un loop per stampare solo se il dato è cambiato

Maggiori dettagli nella guida originale.

Filtri

I filtri implementati sono:

date - formatta la data con la sintassi .Net.aspx)
capitalize - Capitalizza tutte la parole
downcase - converte il testo in minuscolo
upcase - converte il testo in maiuscolo
first - restituisce il primo valore di un array
last - restituisce l'ultimo valore di un array
join - unisce gli elementi di un array intramezzando un carattere
sort - ordina gli elementi di un array
map -mappa un array su una specifica propietà
size - restituisce la dimensione di un array di stringhe
escape - l'escape di una string
escape_once - esegue l'escape di una string html senza modificare gli elementi già convertiti.
strip_html - rimuove i tag html da una stringa
strip_newlines - rimuove gli 'a capo' (\n) da una stringa
newline_to_br - sostituisce gli 'a capo' (\n) con un break html
replace - sostituisce ogni occorrenza
replace_first - sostituisce la prima occorrenza
remove - rimuove ogni occorrenza
remove_first - rimuove la prima occorrenza
truncate - tronca la stringa a n caratteri
truncatewords - tronca la stringa a n parole
prepend - prepone alla stringa il valore
append - accoda alla stringa il valore
minus - sottrae il valore
plus - somma il valore
times - moltiplica il valore
divided_by - divide il valore
sum - somma il valore considerando le come numeri e restituendo un valore decimale
multiply - moltiplica il valore considerando le come numeri e restituendo un valore decimale
divide - divide il valore considerando le come numeri e restituendo un valore decimale
subtract - sottrae il valore considerando le come numeri e restituendo un valore decimale
format_as_money - formatta il dato numerico arrotondando al secondo decimale
empty_cell - inserisce una cella vuota nel caso il risultato sia un valore nullo
split - divide la stringa in due stringhe divise
format_date - formatta la stringa in formato data
is_date - verifica se la stringa è di tipo data
chars - conta il numero di caratteri
newline_to_br - nel caso di un campo testo con più righe, serve per mandare a capo come nella formattazione originale del testo
capitalize_all - restituisce la stringa in maiuscolo
format_as_percentage - restituisce la stringa formattata in percentuale
format_discount_formula - formatta la formula di sconto nei preventivi
format_time - formatta la stringa in formato ora
format_decimal - formatta la stringa in formato decimale (con un numero decimali a piacere)
default - se la stringa da stampare risulta vuota, questo funzione stampa un valore predefinito
discount - ritorna la formula di sconto dell'oggetto
str_len - calcola la lunghezza della stringa
now - Restituisce la data odierna

Aggiornato il: 26/12/2020