Dati: Collections e sorgenti REST

Entrambi i tipi di sorgente dati li usi nel template allo stesso modo: data("slug").

9.1 Collections

Una Collection è una struttura dati propria con campi – ad es. Blog con titolo, data, immagine e testo.

Creare: Collections → + Nuova → nome e slug (lo slug è il nome per data("…")). Nella scheda Schema crei i campi:

Tipo di campo	Inserimento	Nel template
Testo, Testo su più righe, URL	Campo di testo	{{ item.feld }}
Markdown	Editor Markdown con anteprima	{{ item.feld|markdown }}
HTML	Editor di codice	{{ item.feld|safe }}
Numero	Campo numerico	{{ item.feld }}, {{ item.feld|floatformat:2 }}
Sì/No	Casella di controllo	{% if item.feld %}…{% endif %}
Data	Campo data (salvato come AAAA-MM-GG)	{{ item.feld }}
Scelta	Elenco di opzioni fisse	{{ item.feld }}
Immagine	Scelta dalla gestione file	{{ image(item.feld) }}
File	Scelta dalla gestione file	{{ file(item.feld).url }}
Collegamento (una voce)	Scelta di una voce di un’altra Collection	{{ item.feld.name }}
Collegamenti (più voci)	Aggiungere, rimuovere, ordinare voci	{% for x in item.feld %}{{ x.name }}{% endfor %}
Blocchi	Editor a moduli per blocchi fatti di moduli (vedi 7.6)	{% blocks item.feld %}

Il nome del campo (ad es. titel) è il nome nel template, l’etichetta è ciò che compare nel modulo. Obbligatorio impone un valore.

Se rinomini un campo, le voci esistenti mantengono i vecchi valori solo fino al successivo salvataggio della voce. Pianifica perciò i nomi dei campi il prima possibile.

Lingua delle voci: Nello schema stabilisci in quale lingua sono le voci di una Collection. Solo allora le voci si possono collegare a voci di altre lingue – vedi Siti multilingue.

Collegamenti tra Collections: con i tipi di campo Collegamento e Collegamenti una voce punta a voci di un’altra (o della stessa) Collection. La Collection di destinazione la scegli nello schema accanto al tipo. Un articolo del blog ha così un autore (1:n), e articoli e tag possono essere associati tra loro in modo multiplo (n:m). Vengono salvati solo gli ID. In data() e item() i collegamenti sono già risolti:

{% for a in data("blog") %}
  <h2>{{ a.titel }}</h2>
  <p>von {{ a.autor.name }} · {% for t in a.tags %}#{{ t.name }} {% endfor %}</p>
{% endfor %}

All’inverso, cioè “tutti gli articoli di questo autore” o “tutti gli articoli con questo tag”, filtri l’altra Collection per ID. Con Collegamenti (più voci) il confronto significa “contiene”, con __ne “non contiene”:

{% for x in data("blog", "autor", autor.id) %}…{% endfor %}
{% for x in data("blog", "tags", tag.id, "sort", "-datum") %}…{% endfor %}

• Viene risolto un livello: i tag di un articolo sono voci complete, ma i loro collegamenti sono solo ID. Così i collegamenti reciproci non formano un ciclo. Un livello più in profondità ci arrivi con data() e il filtro.
• Le voci eliminate e, per i visitatori, quelle non pubblicate vengono omesse. Un Collegamento è allora vuoto, e i Collegamenti contengono solo le voci rimanenti. Nell’anteprima le bozze sono incluse.
• Nella scheda Utilizzo trovi esempi adatti, anche per la direzione inversa (“Collegata da”). Il pannello Dati del template nell’editor delle pagine mostra le voci risolte.
• L’API REST (/collections/…/items) restituisce gli ID. GET /data/{slug} restituisce lo stesso di data() nel template, cioè risolto.
• CSV: l’esportazione scrive gli ID (più ID separati da virgola). L’importazione accetta ID o il valore di un campo di testo della voce di destinazione, preferibilmente lo slug. Così funzionano le esportazioni di Webflow, che emettono i collegamenti come slug. Più valori li separi con virgola o punto e virgola; ciò che è sconosciuto viene segnalato come avviso.

Cartelle: nella scheda Schema puoi assegnare a una Collection una Cartella, ad es. il nome di un progetto. L’elenco a sinistra si raggruppa di conseguenza, e ogni cartella si può comprimere. Le cartelle servono solo per la panoramica e non cambiano nulla in data("…"). Snippets e file CSS/JS hanno lo stesso campo accanto al nome.

Le voci le gestisci nella scheda Voci: + Voce, modifica con un doppio clic o con Modifica, ordine con le frecce, Pubblicato per ogni voce. Le voci non pubblicate compaiono solo nell’anteprima.

Nella scheda Utilizzo la Collection mostra esempi pronti per template e API. Con Leggibile pubblicamente tramite l’API REST i client JavaScript possono recuperare le voci pubblicate senza accesso – anche da altri domini (CORS viene allora abilitato automaticamente).

Importazione ed esportazione CSV: nella scheda Voci, Esporta CSV scarica tutte le voci (bozze incluse) come file CSV – colonne id, published e poi i campi; UTF-8 con BOM, così Excel mostra correttamente i caratteri accentati. Importa CSV accetta un file CSV (UTF-8; vengono riconosciuti come separatori virgola, punto e virgola o tabulazione) e ne associa le colonne ai campi – automaticamente per nome del campo o etichetta, modificabile per ogni colonna. Un’anteprima mostra le prime voci così come verranno salvate ed elenca tutti gli errori con riga e colonna; finché ci sono errori, non viene importato nulla. Si importa tutto o niente, le nuove voci vengono aggiunte in fondo; Sostituisci le voci esistenti elimina prima tutte quelle presenti.

• Abbinamento invece di aggiunta: in Abbinamento scegli un campo con valori univoci, di solito lo slug. Se esiste già una voce con lo stesso valore, viene aggiornata – solo le colonne associate, tutto il resto (anche lo stato, se non è associata una colonna di stato) resta; altrimenti ne viene creata una nuova. Con Elimina le voci non presenti nel file diventa una sincronizzazione completa: le voci mantengono il loro ID, sparisce solo ciò che manca nel file. L’anteprima mostra per ogni riga nuovo o modifica #ID e in alto il risultato (ad es. “1 nuove · 2 aggiornate · 1 eliminate”). Valori doppi nel file o nella Collection sono errori.

• Modificare in Excel: esporta, modifica il file (cambia righe, aggiungi nuove righe con id vuoto, cancella righe) e reimportalo – la colonna id viene riconosciuta automaticamente come ID voce e proposta come abbinamento. Un ID sconosciuto è un errore. Usa per questo un’esportazione recente: se viene eliminata la voce più recente, una creata in seguito può riceverne l’ID.

• Nuova Collection da CSV: Collections → CSV (accanto a + Nuova). IllusionCMS propone nome, slug e per ogni colonna nome del campo e tipo (Numero, Sì/No, Data, URL, HTML, Testo …) – tutto modificabile prima dell’importazione, le colonne si possono ignorare.

• Esportazioni di Webflow: le colonne di gestione (Collection ID, Item ID, Created On …) vengono ignorate, Draft e Archived determinano lo stato (true = bozza). Per altri file puoi usare tu stesso una colonna con sì/no come Stato: online o Stato: bozza; senza una colonna di questo tipo tutte le voci sono pubblicate.

• Valori: i numeri possono essere scritti alla tedesca (1.234,50) o all’inglese (1,234.50) – 1,5 vale 1,5. Sì/No comprende ja/nein, true/false, 1/0, x. Le date vengono convertite in AAAA-MM-GG da 2025-10-02, 02.10.2025, timestamp ISO e dal formato di Webflow. I valori con zero iniziale (codici postali) l’importazione li propone come testo, non come numero.

• Immagini e file: una colonna immagine o file contiene o l’ID di un file o l’indirizzo di un file già ripreso tramite l’importazione di siti web – così gli URL delle immagini di un’esportazione Webflow trovano le immagini importate. Gli altri indirizzi restano vuoti (l’anteprima li mostra come avviso); se vuoi conservare l’indirizzo, usa il tipo URL.

• L’importazione non attiva eventi dei Workflows – con mille righe sarebbero altrimenti mille esecuzioni di Workflow (ad es. notifiche).

Dati live: alcune Collections si riempiono da sole sul server live – ad es. richieste di contatto da un Workflow. Se nello schema spunti Dati live, le loro voci restano sulla destinazione quando carichi un bundle dal locale; le voci di prova della tua istanza locale non vengono trasferite. Lo schema (campi, nome) arriva comunque dalla versione locale. Nell’elenco tali Collections portano il badge Live.

Singleton: per le cose che esistono esattamente una volta – impostazioni del sito, codici colore, dati di contatto, orari di apertura – spunta Singleton nello schema. La Collection contiene allora esattamente una voce; invece di un elenco vedi subito il modulo in Contenuto. Nel template data() restituisce la voce direttamente come oggetto:

{% set s = data("einstellungen") %}
<header style="--primaer: {{ s.primaerfarbe }}">{{ s.firmenname }} · {{ s.telefon }}</header>

Anche l’API (GET /api/v1/collections/einstellungen/items, /api/v1/data/einstellungen) restituisce un oggetto; lo si modifica con PUT /api/v1/collections/einstellungen/item. Una seconda voce non è possibile, e nemmeno un’importazione CSV. Si può attivare o disattivare solo finché la Collection ha al massimo una voce.

Pagina di dettaglio e anteprima: se le voci compaiono su una pagina Catch-All (ad es. /blog/<slug>), selezionala nello schema in Pagina di dettaglio insieme al campo con la parte dell’URL (di solito slug). Quando modifichi una voce, a destra compare allora l’anteprima di questa pagina – con la versione non ancora salvata, quindi dal vivo mentre digiti, commutabile tra Desktop/Tablet/Mobile; Apri ↗ mostra la voce salvata sul sito.

9.2 data() e item()

{% for post in data("blog") %}…{% endfor %}

I parametri seguono come coppie di nome e valore:

Parametro	Effetto	Esempio
sort	Ordina, - = decrescente	data("blog", "sort", "-datum")
limit	Al massimo n voci	data("blog", "limit", 3)
offset	Salta le prime n	data("blog", "offset", 10, "limit", 10)
qualsiasi campo	Filtra per uguaglianza	data("produkte", "kategorie", "schuhe")
feld__gt, __gte, __lt, __lte	Maggiore / maggiore o uguale / minore / minore o uguale. I numeri vengono confrontati come numeri, i campi data (AAAA-MM-GG) in ordine cronologico; le voci senza valore vengono escluse	data("events", "datum__gte", today)
feld__ne	Diverso	data("blog", "kategorie__ne", "intern")

In più ci sono i campi id, _created e _updated (tempo Unix) – ad es. "sort", "-_created" per “prima i più recenti”. Anche i valori da variabili funzionano: data("produkte", "kategorie", route.query.kat).

Una singola voce la trovi con item():

{% with p=item("produkte", "slug", "sneaker-weiss") %}{{ p.name }}{% endwith %}

9.3 Sorgenti REST

Le sorgenti REST collegano qualsiasi API JSON – shop, CRM, sistema di ticketing, headless CMS, servizi propri. Il CMS richiama l’API durante il rendering, estrae la lista e memorizza il risultato per un po’.

Creare: Sorgenti REST → + Nuova:

Campo	Significato
Nome / Slug	Lo slug è il nome per data("…")
Metodo / URL	GET o POST, URL http(s) assoluto
Header	ad es. Authorization: Bearer …
Body	JSON con POST
Percorso della lista	Dove si trova la lista nella risposta, ad es. data.items (vuoto = risposta intera)
Cache	Per quanto tempo il risultato viene riutilizzato (secondi, 0 = mai)
Timeout	Tempo di attesa massimo (1–60 secondi)

I segnaposto rendono flessibili le richieste:

• {name} in URL, body o header viene compilato dal template: URL https://shop.example.com/api/products?cat={kat} → data("produkte", "kat", "schuhe").
• {env.NAME} legge una variabile d’ambiente del server. Così le credenziali non finiscono nel database: header Authorization: Bearer {env.SHOP_TOKEN}, server avviato con SHOP_TOKEN=… ./illusioncms.

Testare: a destra Prova richiesta mostra stato, durata e dati. In Liste nel risultato compaiono tutti i punti in cui la risposta contiene liste – un clic ne riprende il percorso. Sotto c’è un esempio di template pronto con i campi trovati.

Buono a sapersi:

• Se una richiesta non riesce (stato di errore, timeout, JSON non valido), la pagina non può essere renderizzata. Se hai effettuato l’accesso vedi la causa esatta.
• Una pagina con dati REST resta nella cache delle pagine al massimo per la durata di cache della sorgente.
• Chi può creare sorgenti REST può far richiamare al server indirizzi arbitrari – anche nella rete interna.

---