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

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

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

Переопределение из директории templates проекта

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

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

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

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 это мощная техника для внесения небольших изменений.