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

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

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

Предположим, вы хотите переопределить шаблоны стороннего приложения под названием 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.

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