Come sovrascrivere i templates

Nel tuo progetto, puoi voler fare override del template in un’altra applicazione Django, che sia una applicazione di terze parti o una applicazione contrib come django.contrib.admin. Puoi mettere gli override di template nella directory di template del tuo progetto o nella directory di template dell’applicazione.

Se hai directory di template di app e di progetto che fanno entrambe override, il template loader di default di Django proverà a caricare prima quello a livello di progetto. In altre parole, DIRS viene ricercata prima di APP_DIRS.

Vedi anche

Leggi Overriding built-in widget templates se stai cercando di fare questo.

Sovrascrivere la directory dei template del progetto

Innanzitutto, esploreremo come fare override i template creando modelli sostitutivi nella directory dei template del tuo progetto.

Diciamo che stai cercando di fare override del template di una applicazione di terza parte chiamata blog, che offre i template blog/post.html e blog/list.html. Le impostazioni rilevanti avranno questo aspetto:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

INSTALLED_APPS = [
    ...,
    "blog",
    ...,
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        # ...
    },
]

Le impostazioni TEMPLATES e BASE_DIR esisteranno già se hai creato il tuo progetto usando il template di default del progetto. L’impostazione che necessita di essere modificata è DIRS.

Queste impostazioni presumono che tu abbia una directory templates nella radice del progetto. Per fare override dei template per l’app blog, crea un foldere nella directory templates ed aggiungi i file di template a quella cartella:

templates/
    blog/
        list.html
        post.html

Il template loader cerca prima i template nella directory DIRS. Quando le viste nell’app blog richiedono i template blog/post.html e blog/list.html, il loader restituirà i file che hai appena creato.

Sovrascrivere la directory dei template di un’app

Dal momento che stai facendo override dei template situati fuori delle app di progetto, è più comune usare il primo metodo e mettere i template override nella cartella di template del progetto. Se preferisci, comunque, è anche possibile mettere gli override nella directory di template dell’app.

Innanzitutto, assicurati che le impostazioni dei template stiano controllando all’interno delle directory dell’app:

TEMPLATES = [
    {
        # ...
        "APP_DIRS": True,
        # ...
    },
]

Se vuoi mettere gli override di template in una app chiamata myapp ed i template da sovrascrivere sono chiamati blog/list.html e blog/post.html allora la struttura della directory sarà:

myapp/
    templates/
        blog/
            list.html
            post.html

Con APP_DIRS impostato a True, il template loader cercherà nella directory di template dell’applicazione e troverà i template.

Estendere un template sovrascritto

Con i tuoi template loader configurati, puoi estendere un template usando il tag di template {% extends %} sovrascrivendolo allo stesso tempo. Questo ti permette di fare piccole personalizzazioni senza necessità di reimplementare l’intero template.

Per esempio, puoi utilizzare questa tecnica per aggiungere un logo personalizzato al template admin/base_site.html:

templates/admin/base_site.html

 {% extends "admin/base_site.html" %}

 {% block branding %}
     <img src="link/to/logo.png" alt="logo">
     {{ block.super }}
 {% endblock %}

Punti chiave da notare:

• Questo esempio crea un file in templates/admin/base_site.html che usa la directory configurata a livello di template templates per fare override di admin/base_site.html.
• Il nuovo template estende admin/base_site.html, che è lo stesso template che è stato sovrascritto.
• Il template sostituisce solo il blocco branding, aggiungendo un logo personalizzato e utilizzando block.super per mantenere il contenuto precedente.
• Il resto del template è ereditato invariato da admin/base_site.html.

Questa tecnica funziona perchè il template loader non considera il template in override già caricato (in templates/admin/base_site.html) quando risolve il tag extends. In combinazione con block.super è una potente tecnica per fare piccole personalizzazioni.