# Documentation Django 5.2.8

# 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.