Как переопределять шаблоны

В вашем проекте вы можете захотеть переопределить шаблон в другом приложении Django, будь то приложение стороннего разработчика или приложение contrib, например, django.contrib.admin. Вы можете разместить переопределения шаблонов в каталоге templates вашего проекта или в каталоге templates приложения.

Если у вас есть каталоги шаблонов приложения и проекта, которые оба содержат переопределения, по умолчанию загрузчик шаблонов Django попытается загрузить шаблон из каталога проекта в первую очередь. Другими словами, DIRS будет просмотрен перед APP_DIRS.

Переопределение из каталога шаблонов проекта

Сначала мы рассмотрим переопределение шаблонов путем создания шаблонов-заменителей в каталоге шаблонов вашего проекта.

Допустим, вы пытаетесь переопределить шаблоны для приложения стороннего разработчика, называемого blog, которое предоставляет шаблоны blog/post.html и blog/list.html. Соответствующие настройки вашего проекта будут выглядеть так:

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,
        ...
    },
]

Настройка TEMPLATES и BASE_DIR уже существуют, если вы создали свой проект, используя шаблон проекта по умолчанию. Необходимо изменить настройку DIRS.

Эти настройки предполагают, что у вас есть каталог templates в корне вашего проекта. Чтобы переопределить шаблоны приложения blog, создайте папку в каталоге templates и добавьте файлы шаблонов в эту папку:

templates/
    blog/
        list.html
        post.html

Загрузчик шаблонов сначала ищет шаблоны в каталоге DIRS. Когда представления в приложении blog запрашивают шаблоны blog/post.html и blog/list.html, загрузчик вернёт только что созданные вами файлы.

Переопределение из каталога шаблонов приложения

Поскольку вы переопределяете шаблоны, расположенные вне одного из приложений вашего проекта, чаще всего используется первый метод, и переопределения шаблонов размещаются в папке шаблонов проекта. Однако, если вы предпочитаете, вы также можете поместить переопределения в каталог шаблонов приложения.

Сначала убедитесь, что ваши настройки шаблонов проверяют каталоги приложений:

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

Если вы хотите разместить переопределения шаблонов в приложении, называемом myapp, и шаблоны, которые нужно переопределить, называются blog/list.html и blog/post.html, структура каталогов будет выглядеть следующим образом:

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

При установке APP_DIRS в значение True, загрузчик шаблонов будет искать шаблоны в каталоге шаблонов приложения и найдёт их.

Расширение переопределённого шаблона

При настройке загрузчиков шаблонов вы можете расширить шаблон с помощью тега шаблона {% extends %}, одновременно переопределяя его. Это позволяет внести небольшие изменения без необходимости переписывать весь шаблон.

Например, вы можете использовать этот метод, чтобы добавить пользовательский логотип в шаблон admin/base_site.html:

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

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

Ключевые моменты:

• В примере создаётся файл в templates/admin/base_site.html, который использует настроенный каталог шаблонов проекта templates для переопределения admin/base_site.html.
• Новый шаблон расширяет admin/base_site.html, что соответствует переопределяемому шаблону.
• Шаблон заменяет только блок branding, добавляя пользовательский логотип и используя block.super, чтобы сохранить предыдущее содержимое.
• Остальная часть шаблона наследуется без изменений из admin/base_site.html.

Этот метод работает, потому что загрузчик шаблонов не рассматривает уже загруженный шаблон-переопределение (в templates/admin/base_site.html) при разрешении тега extends. В сочетании с block.super это мощный метод для внесения небольших изменений.