I template con Jinja2

Un template è un file HTML con dei "buchi" che Flask riempie con i dati prima di mandarlo al browser. Il motore che fa questo lavoro si chiama Jinja2 ed è incluso in Flask.

Il kit della lezione

• flask5-02-template.zipBacheca con etichette colorate per categoria, filtro per le date in italiano, pezzo riutilizzabile _scheda.html e pagina per categoria

Rispetto al kit 1 trovate: le etichette colorate, le date scritte in italiano ("5 novembre 2026"), i filtri per categoria in cima all'elenco (/categoria/evento), il testo degli annunci accorciato nelle schede, l'anno nel piè di pagina.

Dal Python al browser

  app.py                          templates/annuncio.html               browser
  ──────                          ───────────────────────               ───────
  render_template(                <h1>{{ annuncio.titolo }}</h1>  ──►   <h1>Uscita didattica</h1>
    "annuncio.html",              <p>{{ annuncio.testo }}</p>            <p>Visita al Museo...</p>
    annuncio=a)

return render_template("annuncio.html", annuncio=a)

• il primo argomento è il file dentro templates/;
• gli altri sono le variabili che il template potrà usare. Il nome a sinistra dell'uguale è il nome dentro il template; quello a destra è il valore in Python.

Il browser riceve solo l'HTML finito: non vede mai le parentesi graffe né il codice Python. Provate: tasto destro → Visualizza sorgente pagina.

Le tre sintassi di Jinja2

Si scrive	Serve a	Esempio
{{ ... }}	stampare un valore	{{ annuncio.titolo }}
{% ... %}	comandi: condizioni, cicli, blocchi	{% for a in annunci %}
{# ... #}	commenti, non arrivano al browser	{# da sistemare #}

Per leggere i campi di un dizionario si può scrivere annuncio["titolo"] oppure, più comodo, annuncio.titolo.

Le condizioni

{% if not annunci %}
  <p class="vuoto">Nessun annuncio.</p>
{% else %}
  <p class="meta">{{ annunci | length }} annunci</p>
{% endif %}

Si possono usare elif, gli operatori ==, !=, <, >=, e and, or, not. A differenza di Python, il blocco si chiude sempre con {% endif %}: le rientranze non contano.

I cicli

<div class="griglia">
  {% for a in annunci %}
    {% include "_scheda.html" %}
  {% endfor %}
</div>

Dentro un ciclo esiste la variabile speciale loop:

Variabile	Valore
loop.index	1, 2, 3… (numero del giro)
loop.index0	0, 1, 2…
loop.first / loop.last	True al primo / all'ultimo giro
loop.length	quanti giri in tutto

Per ciclare su un dizionario si usa .items(), come in Python. Nel kit è così che si disegnano i filtri per categoria:

{% for nome, colore in categorie.items() %}
  <a class="etichetta {{ colore }}" href="{{ url_for('categoria', nome=nome) }}">{{ nome }}</a>
{% endfor %}

I filtri

Un filtro trasforma un valore; si scrive dopo una barra verticale | e si possono mettere in fila.

Filtro	Esempio	Risultato
length	{{ annunci | length }}	3
upper, lower	{{ "ciao" | upper }}	CIAO
capitalize	{{ "evento" | capitalize }}	Evento
truncate(n)	{{ a.testo | truncate(60) }}	il testo tagliato a 60 caratteri, con ...
default(x)	{{ a.autore | default("anonimo") }}	anonimo se manca
round(n)	{{ 7.456 | round(1) }}	7.5

Un filtro fatto da noi

Le date nel kit sono scritte come "2026-11-05" (il formato che useremo anche nel database), ma sulla pagina compaiono come "5 novembre 2026". Il merito è di un filtro personalizzato, definito in app.py:

MESI = ["gennaio", "febbraio", "marzo", ...]

@app.template_filter("data_it")
def data_it(testo):
    d = date.fromisoformat(testo)              # "2026-11-05" → oggetto data
    return f"{d.day} {MESI[d.month - 1]} {d.year}"

E nel template: {{ a.data | data_it }}. Il decoratore @app.template_filter("data_it") registra la funzione come filtro con quel nome.

Variabili per tutti i template

Le categorie servono in tante pagine (elenco, scheda, menu…). Invece di passarle ogni volta a render_template, le diamo a tutti i template una volta sola:

CATEGORIE = {"avviso": "gialla", "compito": "rossa", "evento": "verde"}

@app.context_processor
def variabili_comuni():
    return {"categorie": CATEGORIE, "anno": date.today().year}

Il dizionario restituito viene "aggiunto" a ogni template. Ecco perché in base.html potete scrivere {{ anno }} senza averlo mai passato.

CATEGORIE collega ogni categoria al nome di una classe CSS (gialla, rossa, verde) già definita in style.css. Così il colore dell'etichetta si decide in un posto solo: class="etichetta {{ categorie[a.categoria] }}".

L'ereditarietà dei template

Tutte le pagine hanno la stessa testata, lo stesso menu e lo stesso piè di pagina. Li scriviamo una volta in base.html e lasciamo dei blocchi da riempire:

<!-- base.html -->
<title>{% block titolo %}Home{% endblock %} · Bacheca della classe</title>
...
<main>
  {% block contenuto %}{% endblock %}
</main>
<footer class="piede">Bacheca della classe · TPSIT 5ª · {{ anno }}</footer>

Ogni pagina "figlia" dichiara da chi eredita e riempie i blocchi:

<!-- annuncio.html -->
{% extends "base.html" %}

{% block titolo %}{{ annuncio.titolo }}{% endblock %}

{% block contenuto %}
  <article class="scheda">
    <h1>{{ annuncio.titolo }}</h1>
    <p class="meta">{{ annuncio.data | data_it }}</p>
    <p>{{ annuncio.testo }}</p>
  </article>
{% endblock %}

  base.html                       annuncio.html                   pagina finale
  ┌──────────────────────┐        ┌─────────────────────┐         ┌──────────────────────┐
  │ testata e menu       │        │ extends "base.html" │         │ testata e menu       │
  │ ┌──────────────────┐ │   +    │ block contenuto:    │   =     │ <h1>Uscita…</h1>     │
  │ │ block contenuto  │ │        │   <h1>…</h1>        │         │ <p>Visita al…</p>    │
  │ └──────────────────┘ │        │   <p>…</p>          │         │ piè di pagina        │
  │ piè di pagina        │        └─────────────────────┘         └──────────────────────┘
  └──────────────────────┘

Le regole da ricordare:

• {% extends %} deve essere la prima riga del file figlio;
• nel figlio, tutto quello che sta fuori dai blocchi viene ignorato;
• un blocco non riempito tiene il contenuto che ha in base.html (il titolo "Home", per esempio).

Pezzi riutilizzabili: include

La scheda di un annuncio serve nell'elenco generale e nell'elenco per categoria. La scriviamo una volta in _scheda.html:

<div class="scheda">
  <a class="etichetta {{ categorie[a.categoria] }}" href="{{ url_for('categoria', nome=a.categoria) }}">{{ a.categoria }}</a>
  <h3><a href="{{ url_for('annuncio', id=a.id) }}">{{ a.titolo }}</a></h3>
  <p class="meta">{{ a.data | data_it }}</p>
  <p>{{ a.testo | truncate(60) }}</p>
</div>

e la inseriamo con {% include "_scheda.html" %}. Il pezzo incluso vede le variabili della pagina che lo include: per questo dentro il ciclo funziona a. Il trattino basso iniziale è solo una convenzione: ricorda che non è una pagina intera.

	extends	include
Idea	"questa pagina è fatta come base.html"	"metti qui questo pezzo"
Quante volte	una sola, in cima	quante ne volete

Un template, due pagine

Guardate la route per categoria:

@app.route("/categoria/<nome>")
def categoria(nome):
    if nome not in CATEGORIE:
        abort(404)
    scelti = [a for a in annunci if a["categoria"] == nome]
    return render_template("index.html", annunci=scelti, categoria_scelta=nome)

Usa lo stesso index.html della home, passando una lista filtrata e una variabile in più, categoria_scelta. Nel template un {% if categoria_scelta %} cambia il titolo. Una pagina in più, zero HTML in più.

I file statici

CSS, immagini e JavaScript stanno in static/ e si collegano con url_for:

<link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
<img src="{{ url_for('static', filename='img/logo.png') }}" alt="Logo">

Sicurezza gratis: l'escape automatico

Se un utente scrivesse come titolo <script>alert("hackerato")</script>, Jinja2 lo mostrerebbe come testo, non lo eseguirebbe: trasforma automaticamente < in < e > in >. È la prima difesa contro l'attacco XSS (Cross-Site Scripting), che vedremo nel laboratorio di sicurezza. Non disattivatela mai (il filtro | safe la spegne: si usa solo per HTML scritto da voi).

Gli errori più comuni

Errore	Causa
TemplateNotFound	nome del file sbagliato, o cartella templates rinominata
UndefinedError: 'annuncio' is undefined	variabile non passata con render_template (o nome diverso)
TemplateSyntaxError: … endfor	manca un {% endfor %} o un {% endif %}
La pagina figlia è vuota	il contenuto è fuori da {% block contenuto %}
BuildError	in url_for c'è un nome di funzione che non esiste

Missioni