--- title: "Liquid di Shopify: guida pratica per chi parte da zero" seo_title: "Liquid Shopify: guida pratica a oggetti, tag e filtri" description: "Guida pratica al linguaggio Liquid di Shopify: oggetti, tag e filtri spiegati con esempi veri per leggere e modificare il tema del tuo negozio." url: "https://salvatorepitone.it/liquid-shopify-guida/" type: "BlogPosting" language: "it-IT" published: "2026-10-26T14:13:56+01:00" updated: "2026-10-26T18:12:58+01:00" author: "Salvatore Pitone" categories: - "Shopify" tags: - "Shopify" - "liquid shopify" image: "https://salvatorepitone.it/wp-content/uploads/2026/10/liquid-shopify-guida-copertina.webp" --- # Liquid di Shopify: guida pratica per chi parte da zero Se hai mai aperto “Modifica codice” nel tuo negozio, hai visto file pieni di parentesi graffe e di simboli di percentuale. Quello è **Liquid**, il linguaggio con cui sono scritti tutti i temi: capire Liquid Shopify è il primo passo per leggere un tema senza paura. **In breve:** Liquid è il linguaggio di template di Shopify. Prende i dati del negozio (prodotti, collezioni, carrello, impostazioni del tema) e li trasforma nell’HTML che vede il cliente. Si basa su tre cose: gli **oggetti**, cioè i dati; i **tag**, cioè la logica; i **filtri**, che trasformano quello che stampi. In questa guida ti spiego queste tre cose con esempi corti, presi dal lavoro di tutti i giorni sui temi. Ogni pezzo di codice segue la documentazione ufficiale attuale di Shopify. Se arrivi da WordPress e PHP ti troverai a casa in fretta; se non hai mai scritto codice, ti basta sapere leggere un file di testo. ## Cos’è Liquid e dove si trova nel tema Liquid è un linguaggio creato da Shopify e rilasciato come [progetto open source](https://shopify.github.io/liquid/). Shopify ne usa una versione arricchita, con oggetti e filtri pensati per l’e-commerce, descritti nella [documentazione di riferimento di Liquid](https://shopify.dev/docs/api/liquid). Il codice viene eseguito sui server di Shopify, prima che la pagina arrivi al browser. Per questo non puoi usare PHP: il negozio non è un server tuo, e Liquid è l’unico modo per “parlare” con i dati del tema. Se ti serve un ripasso su come funziona la piattaforma, parti da [cos’è Shopify e come funziona per l’e-commerce](https://salvatorepitone.it/cose-shopify-e-come-funziona-per-le-commerce/). Nel tema trovi Liquid in queste cartelle: - `layout/`: la cornice di tutte le pagine, di solito `theme.liquid`; - `sections/`: i “mattoni” che sposti dall’editor del tema (banner, prodotti in evidenza, testo con immagine); - `blocks/`: nei temi più recenti, i blocchi riutilizzabili dentro le sezioni; - `snippets/`: pezzi di codice richiamati da altri file; - `templates/`: nei temi Online Store 2.0 sono quasi tutti file JSON, cioè l’elenco delle sezioni che compaiono in una pagina. Le cartelle `config/` e `locales/` contengono invece file JSON: impostazioni del tema e traduzioni dei testi. ## Le due “parentesi”: output e logica In Liquid ci sono solo due tipi di delimitatori da ricordare. Tutto il resto del file è HTML normale. ### {{ }} per stampare Le doppie graffe stampano un valore nella pagina. `{{ product.title }}` scrive il nome del prodotto; `{{ product.price | money }}` scrive il prezzo formattato nella valuta del negozio. Il simbolo `|` applica un filtro: ne parlo più sotto. ### {% %} per decidere Graffa e percentuale servono alla logica: condizioni, cicli, variabili. Non stampano niente da sole. Ecco un esempio che uso spesso per spiegare Liquid ai clienti: titolo del prodotto, poi prezzo o scritta “Esaurito”. `sections/main-product.liquid (estratto)` ```

{{ product.title | escape }}

{%- if product.available -%}

{{ product.price | money }}

{%- else -%}

Esaurito

{%- endif -%} ``` Riga per riga: la prima stampa il titolo, con il filtro `escape` che neutralizza eventuali caratteri HTML. La seconda controlla se almeno una variante è disponibile. La terza stampa il prezzo più basso tra le varianti. Il ramo `else` gestisce il prodotto esaurito, e `endif` chiude la condizione. ![Esempio di codice Liquid con output, condizione e filtro money in una pagina prodotto Shopify](https://salvatorepitone.it/wp-content/uploads/2026/10/liquid-shopify-guida-parentesi.webp) _Output, condizione e filtro money: le tre cose che trovi in ogni file Liquid._ ### Il trattino che toglie gli spazi Hai notato `{%-` e `-%}`? Il trattino toglie gli spazi e gli a capo che Liquid lascerebbe nell’HTML al posto del tag. Vale anche per l’output: `{{- valore -}}`. Non cambia cosa vede il cliente, ma tiene pulito il codice della pagina. Io lo metto sempre sui tag di logica. Due tag utili per tenere ordine: `{% comment %}…{% endcomment %}` per i commenti, che non finiscono nella pagina, e `{% liquid %}`, che permette di scrivere più istruzioni di fila senza ripetere le parentesi. ## Gli oggetti che userai sempre Un oggetto è un contenitore di dati. Le sue proprietà si leggono con il punto: `product.title`, `cart.item_count`. Alcuni oggetti sono **globali** e li trovi ovunque (`shop`, `cart`, `settings`, `request`); altri esistono solo in certe pagine, come `product` nella pagina prodotto. L’elenco completo è nella pagina degli [oggetti Liquid](https://shopify.dev/docs/api/liquid/objects). ![Gli oggetti Liquid più usati nei temi Shopify e a cosa servono: product, collection, cart, customer, shop, section, block, settings](https://salvatorepitone.it/wp-content/uploads/2026/10/liquid-shopify-guida-oggetti.webp) _Gli otto oggetti Liquid che trovi in quasi tutti i temi._ ### product e variant `product` contiene titolo, descrizione, immagini, prezzi e varianti. Una cosa che spiazza chi arriva da WordPress: i prezzi sono numeri interi nella **sottounità della valuta**. Un prodotto da 49,00 € vale `4900`: per mostrarlo come prezzo serve il filtro `money`. Quando alla scheda prodotto servono dati che Shopify non prevede, come il materiale o i tempi di consegna, uso i [metafield e i metaobject](https://salvatorepitone.it/metafield-metaobject-shopify/). Le varianti (taglia, colore) sono oggetti `variant`. Per lavorare su quella scelta dal cliente, o sulla prima disponibile, uso `product.selected_or_first_available_variant`: ``` {%- assign variante = product.selected_or_first_available_variant -%}

{{ variante.title }}: {{ variante.price | money }}

``` ### collection Nella pagina di una collezione hai `collection`, con `collection.title` e l’elenco `collection.products`. Attenzione: nella pagina prodotto `collection` c’è solo se il cliente è arrivato da un indirizzo del tipo `/collections/scarpe/products/sneaker-bianca`. Se apre `/products/sneaker-bianca`, l’oggetto è vuoto. ### cart `cart` è il carrello del visitatore ed è disponibile in tutte le pagine: `cart.item_count` dà il numero di articoli, `cart.total_price` il totale dopo gli sconti, sempre in centesimi. ### section, block e settings Qui c’è il cuore dei temi moderni. `section.settings` contiene i valori che il titolare imposta nell’editor per quella sezione; `section.blocks` è l’elenco dei suoi blocchi, ognuno con i propri `block.settings`. `settings`, da solo, contiene le impostazioni generali del tema (colori, caratteri, logo). `sections/vantaggi.liquid (estratto)` ``` {%- for block in section.blocks -%}
{{ block.settings.testo }}
{%- endfor -%} ``` `block.shopify_attributes` aggiunge gli attributi che servono all’editor del tema per riconoscere il blocco quando ci clicchi sopra. Fuori dall’editor non stampa niente. ## Tag: condizioni, cicli e snippet I tag sono le istruzioni tra `{% %}`. L’elenco completo è nella pagina dei [tag Liquid](https://shopify.dev/docs/api/liquid/tags); questi sono quelli che uso ogni giorno. ### if, unless, case `if` esegue un blocco se la condizione è vera, `unless` se è falsa. Gli operatori sono `==`, `!=`, `>`, `<`, `>=`, `<=`, `contains`, più `and` e `or`. Due regole da sapere: le parentesi tonde non sono ammesse, e le condizioni multiple si valutano **da destra verso sinistra**. Altra regola che fa perdere ore: in Liquid sono “falsi” solo `nil` e `false`. Una stringa vuota è vera. Per controllare se un testo è stato compilato usa `!= blank`, come spiega la pagina sulle [basi di Liquid](https://shopify.dev/docs/api/liquid/basics). Quando le possibilità sono tante, `case` è più leggibile di una catena di `if`: ``` {%- case product.type -%} {%- when 'Scarpe' -%} {% render 'guida-taglie-scarpe' %} {%- when 'Maglie', 'Felpe' -%} {% render 'guida-taglie-maglie' %} {%- else -%}

Scrivici per sapere le misure.

{%- endcase -%} ``` ### for e paginate `for` ripete un blocco per ogni elemento di un elenco. Su Shopify un ciclo fa **al massimo 50 giri**: per elenchi più lunghi, come i prodotti di una collezione, si usa `paginate`, che divide l’elenco in pagine da 1 a 250 elementi. `sections/main-collection.liquid (estratto)` ``` {%- paginate collection.products by 24 -%} {%- for product in collection.products -%} {{ product.title | escape }} {%- else -%}

Nessun prodotto in questa collezione.

{%- endfor -%} {{- paginate | default_pagination -}} {%- endpaginate -%} ``` Il ramo `else` dentro `for` si esegue quando l’elenco è vuoto. `default_pagination` stampa i link alle pagine successive come veri link HTML, una cosa utile anche per Google. ### render (e perché non include) `render` inserisce [uno snippet](https://salvatorepitone.it/snippet-liquid-shopify/), cioè un file della cartella `snippets/`. Lo snippet **non vede le variabili** create fuori: quello che gli serve glielo passi tu come parametro. ``` {% render 'card-prodotto', product: product, mostra_prezzo: true %} {% render 'card-prodotto' for collection.products as product %} ``` Nei tutorial vecchi trovi ancora `{% include %}`: Shopify lo ha deprecato perché il modo in cui condivide le variabili rallenta le pagine e rende il codice difficile da seguire. Nei file nuovi usa sempre `render`. ## Filtri: i 10 più utili Un filtro trasforma il valore che lo precede, e i filtri si concatenano da sinistra a destra. Questi sono i dieci che uso di più; gli altri sono nella pagina dei [filtri Liquid](https://shopify.dev/docs/api/liquid/filters). 1. `money`: formatta un prezzo nella valuta del cliente (`money_with_currency` aggiunge il codice, es. EUR); 2. `image_url`: crea l’indirizzo di un’immagine alla misura che chiedi (sostituisce il vecchio `img_url`, deprecato); 3. `image_tag`: crea il tag `` completo a partire da `image_url`; 4. `t`: prende un testo dai file di traduzione in `locales/`; 5. `escape`: rende sicuro un testo dentro l’HTML; 6. `default`: usa un valore di riserva se quello principale è vuoto; 7. `date`: formatta una data; 8. `strip_html`: toglie i tag HTML, per esempio dalla descrizione del prodotto; 9. `truncate`: accorcia un testo a un numero di caratteri; 10. `json`: trasforma un valore in JSON valido, indispensabile quando passi dati a JavaScript o scrivi dati strutturati. ``` {{ product.featured_image | image_url: width: 800 | image_tag: loading: 'lazy' }} {{ product.description | strip_html | truncate: 140 }} {{ article.published_at | date: format: 'abbreviated_date' }} {{ section.settings.titolo | default: 'Novità' | escape }} {{ 'products.product.add_to_cart' | t }} ``` Ci sono anche i filtri matematici `plus`, `minus`, `times` e `divided_by`. Occhio a `divided_by`: tra numeri interi il risultato è intero, quindi `{{ 7 | divided_by: 2 }}` dà 3. Se ti servono i decimali dividi per `2.0`. ## Gli errori più comuni Quando metto le mani su un tema modificato da altri, gli errori sono quasi sempre gli stessi. Eccoli, così li eviti dall’inizio. - **Tag non chiusi**: un `if` senza `endif` o un `for` senza `endfor`. L’editor del codice ti segnala l’errore di sintassi: leggilo, indica la riga. - **Prezzi senza filtro**: `{{ product.price }}` stampa 4900, non 49,00 €. - **Testi vuoti trattati come falsi**: `{% if section.settings.titolo %}` è vero anche con il campo vuoto; usa `!= blank`. - **Codice copiato da guide vecchie**: `include`, `img_url` e i template `.liquid` al posto dei JSON sono segnali di un tutorial superato. - **Variabili che “spariscono” negli snippet**: con `render` vanno passate come parametri. - **Modifiche fatte sul tema pubblicato**: un errore lo vedono subito i clienti. Si lavora sempre su una copia del tema. > **Il mio consiglio:** prima di toccare qualsiasi file, [duplica il tema](https://salvatorepitone.it/modificare-codice-tema-shopify/) da Negozio online > Temi. Fai le prove sulla copia, guardale in anteprima e pubblica solo quando è tutto a posto. ## Domande frequenti ### Liquid è difficile da imparare? No, per le basi bastano pochi giorni. Le regole sono poche: doppie graffe per stampare, graffa e percentuale per la logica, filtri per trasformare i valori. La parte che richiede più tempo è conoscere gli oggetti di Shopify e la struttura del tema che stai modificando, perché ogni tema organizza sezioni e snippet a modo suo. ### Posso usare PHP o JavaScript al posto di Liquid? PHP no: il tema gira sui server di Shopify e accetta solo Liquid. JavaScript sì, ma lavora nel browser, dopo che la pagina è stata generata, e serve per interazioni come il carrello che si aggiorna senza ricaricare. I dati del negozio arrivano nella pagina sempre tramite Liquid, che li stampa nell’HTML. ### Dove trovo l’elenco completo di oggetti e filtri? Nella documentazione ufficiale su shopify.dev, sezione Liquid: ci sono pagine separate per oggetti, tag e filtri, con esempi e note sulle funzioni deprecate. È l’unica fonte che consiglio, perché i tutorial in giro spesso usano sintassi superata come include o img\_url, che oggi non andrebbero più usate. ### Se sbaglio il codice si rompe il negozio? Può succedere, se modifichi il tema pubblicato. Per questo si lavora su una copia: duplichi il tema, fai le modifiche, controlli l’anteprima e pubblichi solo alla fine. L’editor segnala gli errori di sintassi e ogni file ha una cronologia per tornare a una versione precedente. Gli ordini e i prodotti non vengono toccati dal codice del tema. ## Conclusione Liquid si legge in fretta: oggetti per i dati, tag per la logica, filtri per trasformare. Con queste tre idee apri qualsiasi file del tema e capisci cosa sta facendo. Il passo successivo è provare piccole modifiche su una copia del tema, con calma. Quando la modifica è più grande, come [una sezione nuova](https://salvatorepitone.it/creare-sezione-personalizzata-shopify/) o un tema su misura, è il lavoro che faccio nella [realizzazione e migrazione di negozi Shopify](https://salvatorepitone.it/realizzazione-e-migrazione-shopify/); per le correzioni continue c’è l’[assistenza e manutenzione del negozio online](https://salvatorepitone.it/assistenza-e-manutenzione-negozio-online/). Vuoi una modifica al tema ma non hai tempo di imparare Liquid? [**Scrivimi cosa ti serve**](https://salvatorepitone.it/contatti/): ti rispondo io.