Surcharge des gabarits

Dans votre projet, vous pourriez vouloir surcharger un gabarit d’une autre application Django, que ce soit une application tierce ou une application « contrib » telle que django.contrib.admin. Vous pouvez soit placer les gabarits surchargés dans le répertoire des gabarits de votre projet, ou les placer dans le répertoire de gabarits d’une application.

Si vous avez à la fois des gabarits surchargés dans les répertoires du projet et d’une application, le chargeur de gabarits par défaut de Django va essayer de charger le gabarit en commençant par le répertoire du projet. En d’autres termes, la recherche dans DIRS est prioritaire par rapport à APP_DIRS.

Voir aussi

Lisez Redéfinition des gabarits des composants intégrés si vous cherchez à faire cela.

Surcharge à partir du répertoire des gabarits du projet

Tout d’abord, nous allons examiner la surcharge des gabarits en créant les gabarits à remplacer dans le répertoire des gabarits de votre projet.

Admettons que vous essayiez de surcharger les gabarits d’une application tierce appelée blog, qui fournit les gabarits blog/post.html et blog/list.html. Les réglages appropriés du projet ressembleraient à

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 réglage TEMPLATES et BASE_DIR existent déjà si vous avez créé votre projet à partir du modèle de projet par défaut. Le réglage devant être modifié est DIRS.

Ces réglages supposent qu’un répertoire templates se trouve à la racine du projet. Pour surcharger les gabarits de l’application blog, créez un dossier dans le répertoire templates et ajoutez les fichiers de gabarit dans ce dossier :

templates/
    blog/
        list.html
        post.html

Le chargeur de gabarits cherche d’abord les gabarits dans le répertoire DIRS. Lorsque les vues de l’application blog demanderont les gabarits blog/post.html et blog/list.html, le chargeur renverra les fichiers que vous venez de créer.

Surcharge à partir du répertoire des gabarits d’une application

Comme vous surchargez des gabarits situés en dehors des applications de votre projet, il est plus courant d’utiliser la première méthode et de placer les gabarits à surcharger dans le dossier des gabarits du projet. Cependant, si vous préférez placer ces gabarits dans le répertoire des gabarits d’une application, c’est aussi possible.

Commencez par vous assurer que les réglages des gabarits sont configurés pour rechercher dans les répertoires des applications

TEMPLATES = [
    {
        ...,
        'APP_DIRS': True,
        ...
    },
]

Si vous souhaitez placer les gabarits surchargés dans une application nommée myapp et que les gabarits à surcharger sont nommés blog/list.html et blog/post.html, votre structure de répertoires ressemblera à :

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

Lorsque APP_DIRS vaut True, le chargeur de gabarits recherche dans les répertoires de gabarits des applications et va donc trouver ces gabarits.

Extension d’un gabarit surchargé

Lorsque les chargeurs de gabarits sont configurés, vous pouvez étendre un gabarit en utilisant la balise de gabarit {% extends %} tout en le surchargeant en même temps. Cela peut vous permettre de faire de petites personnalisations sans avoir besoin de réécrire le gabarit en entier.

Par exemple, vous pouvez utiliser cette technique pour ajouter un logo personnalisé au gabarit 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 %}

Points clés à relever :

• L’exemple crée un fichier templates/admin/base_site.html qui utilise le répertoire templates configuré dans le projet afin de surcharger admin/base_site.html.
• Le nouveau gabarit étend admin/base_site.html, qui est le même gabarit que celui qui est surchargé.
• Le gabarit ne fait que remplacer le bloc branding, ajoutant un logo personnalisé et utilisant block.super pour appeler le contenu d’origine.
• Le reste du gabarit est hérité tel quel de admin/base_site.html.

Cette technique fonctionne car le chargeur de gabarits ne considère pas le gabrit surchargé déjà chargé (à templates/admin/base_site.html) lorsqu’il résoud la balise extends. Combiné à block.super, c’est une technique puissante pour appliquer de petits ajustements.