IllusionCMS
IT
Manuale · 8

File e immagini

Caricare e organizzare

In File: trascina i file nell’area con il drag & drop oppure fai clic su Carica (fino a 64 MB per file). Le cartelle servono solo per la panoramica – spostare o rinominare non cambia mai l’URL di un file. Per spostare un file, trascinalo su una cartella a sinistra.

A destra, per ogni file: nome, testo alternativo, misure, varianti, copia URL, copia tag template, elimina.

Pulizia

Dopo nuove importazioni o ristrutturazioni restano spesso immagini e file CSS/JS che nulla usa più. Pulizia… (in File e in CSS & JS) li elenca – le immagini con anteprima, tutto preselezionato. Deseleziona ciò che deve restare, poi Elimina selezionati; prima viene chiesta una conferma. L’eliminazione è definitiva, insieme alle varianti delle immagini e alle versioni WebP.

Un file è considerato usato se pagine (HTML, Head, campi SEO), snippet, CSS/JS, voci di Collection, Workflows, Pens o sorgenti REST vi fanno riferimento – tramite il suo indirizzo (anche una variante dell’immagine o la versione WebP), tramite image(ID)/file(ID), un campo immagine o file, come icona del sito o immagine di anteprima. Un CSS/JS è considerato usato se è associato a una pagina o incluso con asset_url(ID); un foglio di stile inutilizzato non conta come uso delle immagini al suo interno. Poco prima dell’eliminazione il server controlla ancora una volta e lascia stare tutto ciò che nel frattempo è stato usato.

Non sono riconoscibili i riferimenti dall’esterno (altri siti web, newsletter che puntano direttamente a /media/…) e da versioni vecchie nella cronologia delle versioni – chi riporta una pagina a una versione vecchia non vi troverà più le immagini eliminate. Nel dubbio, deseleziona.

Varianti delle immagini e srcset

Per JPEG e PNG IllusionCMS genera automaticamente al caricamento versioni ridotte con larghezza di 320, 640, 960, 1280 e 1920 px (solo larghezze inferiori all’originale). Così i browser caricano solo l’immagine che serve loro. GIF, WebP e SVG vengono salvati invariati.

Ecco come le immagini arrivano nella pagina:

  1. Pulsante Immagine nell’editor – inserisce un <img> con srcset, sizes, larghezza/altezza, testo alternativo e loading="lazy"; per JPEG/PNG dentro un <picture> con versioni WebP (vedi sotto).

  2. Tag template – resta aggiornato se cambiano testo alternativo o file:

    {{ image(12) }}
{{ image(12, "(min-width: 900px) 50vw, 100vw") }}
{{ image(12, "100vw", "hero-bild") }}

  3. Informazioni sul file per costruzioni personalizzate:

    {% with f=file(12) %}
  <div class="hero" style="background-image:url('{{ f.url }}')"></div>
{% endwith %}

Impostare correttamente sizes: il valore dice al browser quanto è larga l’immagine visualizzata nella pagina. 100vw per la larghezza piena, (min-width: 960px) 50vw, 100vw per un’immagine che da desktop è larga la metà. Nella finestra dell’immagine ci sono dei modelli.

I testi alternativi descrivono l’immagine per screen reader e motori di ricerca. Curali nella gestione file – image() li riprende automaticamente.

WebP e dimensioni tramite URL

Per ogni JPEG e PNG – originale e tutte le varianti – esiste automaticamente una versione WebP, di solito grande circa la metà. image() e la finestra dell’immagine mettono perciò l’immagine in un <picture>: i browser che supportano WebP (tutti quelli attuali) caricano il file WebP, tutti gli altri il consueto <img>:

<picture>
  <source type="image/webp" srcset="/media/2026/10/foto-ab12-320w.jpg.webp 320w, …, /media/2026/10/foto-ab12.jpg.webp 1600w" sizes="100vw">
  <img src="/media/2026/10/foto-ab12.jpg" srcset="…" sizes="100vw" width="1600" height="900" alt="…" loading="lazy" decoding="async">
</picture>

Il file WebP si chiama come l’immagine con .webp aggiunto e viene creato alla prima richiesta (una sola volta, una frazione di secondo), poi resta come file accanto all’originale – anche per le immagini già presenti, senza che tu debba fare nulla. Se un’immagine viene sostituita (reimportazione), viene ricreato.

Per HTML e CSS personalizzati ci sono i parametri URL:

URL restituisce
/media/…/foto.jpg?w=500 la variante più piccola con almeno 500 px di larghezza (qui 640 px), altrimenti l’originale
/media/…/foto.jpg?format=webp la versione WebP dell’originale
/media/…/foto.jpg?w=500&format=webp entrambe le cose combinate

w sceglie sempre una delle larghezze fisse (320, 640, 960, 1280, 1920) – dimensioni arbitrarie non vengono generate, così nessuno può riempire lo spazio di archiviazione. In file() il srcset WebP si trova in .webp_srcset. L’esportazione statica contiene i file WebP usati.

File privati

Un file può essere privato: i visitatori del sito non lo vedono – /media/… risponde loro “non trovato” (404), come se il file non esistesse. Vale per l’originale, tutte le varianti dell’immagine e le versioni WebP. Possono vederlo:

  • gli utenti connessi – nell’admin (sessione) e con un token API, anche di sola lettura (Authorization: Bearer … o ?token=…),
  • chiunque abbia un link firmato.

È pensato per PDF riservati, bozze o materiale da inviare ai clienti tramite link.

Attivare: in File clicca sul file e attiva Privato a destra – l’effetto è immediato. Per caricare subito come privato, spunta Privato accanto a Carica. I file privati mostrano nella griglia un lucchetto con “Privato”; le finestre di selezione (inserisci immagine, collega file) mostrano un avviso.

Link firmati: per un file privato scegli la validità sotto l’interruttore (1 ora, 1 giorno, 7 giorni, 30 giorni) e clicca su Copia link. L’indirizzo completo finisce negli appunti e il messaggio indica la data di scadenza. Il link ha questo aspetto: /media/2026/10/offerta-ab12.pdf?exp=…&sig=… – vale per il file con varianti e versioni WebP e non può essere né prolungato né trasferito ad altri file. I singoli link non si possono revocare: le firme restano valide fino alla scadenza, anche se nel frattempo rendi il file pubblico e poi di nuovo privato. Scegli quindi una validità breve. Le risposte per i file privati non vengono memorizzate nella cache (Cache-Control: private, no-store) né indicizzate (X-Robots-Tag: noindex), e i download non contano nelle statistiche.

Anteprima: nell’anteprima dell’editor delle pagine, con ?preview=1 e nei link di anteprima le immagini private compaiono comunque – image(), file() (.url, .srcset, .webp_srcset), icona del sito e immagine di anteprima restituiscono lì indirizzi firmati (validi circa una o due ore). Sulla pagina pubblicata gli indirizzi restano non firmati, quindi i visitatori non vedono l’immagine. file(ID).private indica se un file è privato, per esempio per mostrare un link solo per i file pubblici:

{% with f=file(12) %}{% if not f.private %}<a href="{{ f.url }}">{{ f.name }}</a>{% endif %}{% endwith %}

Limite: vengono firmati solo gli indirizzi di image()/file(). I percorsi scritti a mano nell’HTML (<img src="/media/…">, anche dalla finestra immagine senza Inserisci come tag del template) restano come sono – nell’anteprima l’immagine manca. Per le immagini private usa quindi il tag del template (la finestra immagine lo preseleziona per i file privati). L’esportazione statica esclude sempre i file privati.