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](http://msdn.microsoft.com/en-us/library/8kb3ddd4(v=vs.110).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: 27/01/2025