Давайте просто признаемся друг другу... Все мы иногда это делаем. Все мы иногда кастомизируем Django админку. Без четкого понимания того, как построены шаблоны и используемые классы любая попытка кастомизации превращается в пытку.
Этот цикл статей - моя попытка помочь понять и полюбить то, как всё устроено изнутри. Тема длинная, так что начнем с самых азов. Сейчас мы разберем все основные шаблоны и механизм их поиска.
В первую очередь узнаем какие шаблоны есть и из чего они состоят. Из этих шаблонов построен интерфейс административной панели. Они работают на Django Template Language (DTL). Это встроенный механизм для динамической генерации HTML в Django Если вдруг с ним еще не знакомы или нужно освежить память, то почитать можно тут.
Важно отметить, что редактирование шаблонов напрямую - чаще всего не лучшее решение. Для этого в Django есть множество удобных инструментов, о которых мы поговорим в следующих статьях. Тем не менее, понимание структуры важно для полной и понятной картины принципов работы админки.
Основные компоненты шаблонов Django Admin
Шаблоны Django Admin состоят из нескольких основных компонентов, которые можно разделить на следующие категории:
Базовые шаблоны
Шаблоны списка объектов
Шаблоны форм
Шаблоны фильтров, поиска, действий
Другое, но тоже важное
Теперь разберем каждый шаблон по отдельности и рассмотрим основные блоки поближе. Для удобства можно нажать на название файла и изучить подробнее в репозитории Django.
1. Базовые шаблоны
base_site.html Основной шаблон, который задает общую структуру всей административной панели Django. Этот шаблон содержит основные элементы интерфейса, такие как заголовок (header), меню навигации и подвал (footer).
Основные блоки:
{% block title %} — отвечает за заголовок страницы, отображаемый в браузере. По умолчанию он включает название админки и имя текущего сайта.
{% block branding %} — используется для брендинга, например, чтобы добавить логотип и название сайта в верхней части страницы.
{% block nav-global %} — глобальное меню навигации, где отображаются основные ссылки, такие как ссылки на документацию и другие страницы. Здесь будет использован шаблон nav_sidebar.html.
base.html Расширяет base_site.html. Уже на него в свою очередь опираются все остальные страницы админки. Он добавляет дополнительные элементы, необходимые для работы с административными данными. Например, сообщения об ошибках, уведомления, стили и скрипты.
Основные блоки:
{% block content %} — основной контент страницы, где отображаются данные и функциональные элементы.
{% block messages %} — область для отображения уведомлений и сообщений об ошибках, таких как подтверждение действий или предупреждения.
{% block breadcrumbs %} — хлебные крошки (путь навигации), которые помогают пользователю ориентироваться в иерархии страниц.
{% block footer %} — футер страницы, который обычно содержит информацию о версии Django и ссылки на документацию.
2. Шаблоны списка объектов
change_list.html Шаблон для отображения списка объектов модели. Он используется, когда пользователь переходит на страницу, где перечислены все объекты конкретной модели. Этот шаблон организует таблицу с данными, пагинацию, фильтры, поиск и другие элементы, необходимые для управления списком объектов.
Основные блоки:
{% block object-tools %} — содержит элементы управления, такие как кнопки «Добавить», «Импортировать» и другие действия, доступные для модели.
{% block filters %} — фильтры, которые позволяют ограничить выборку по атрибутам модели. Отображается на боковой панели и позволяет пользователю легко находить нужные данные. Сюда будет подставлен шаблон filter.html.
{% block search %} — блок для формы поиска, который позволяет находить объекты по ключевым словам или значениям полей. Сюда будет подставлен шаблон search_form.html.
{% block result_list %} — таблица, в которой отображаются объекты модели. Этот блок может содержать колонки с данными, сортировку и т.д.
{% block pagination %} — отвечает за пагинацию, отображает текущую страницу и позволяет переходить к другим страницам списка. Сюда будет подставлен шаблон paginations.html.
change_list_results.html Шаблон, который отвечает непосредственно за отображение результатов списка объектов в таблице внутри change_list.html. Он занимается рендерингом таблицы с данными, где каждая строка соответствует отдельному объекту модели. Этот шаблон позволяет детально настроить вид таблицы, в которой отображаются поля объектов.
Строки заголовка — цикл {% for header in result_headers %} выводит заголовки таблицы
Строки данных — цикл {% for result in results %} выводит непосредственно объекты из БД.
3. Шаблоны форм
Это тот шаблон, который отвечает за отображение используются для создания и редактирования объектов модели. Они включают в себя формы ввода данных и элементы управления.
change_form.html Шаблон для отображения формы создания и редактирования объекта. Он организует отображение полей модели, добавляет заголовки и обрабатывает поля ввода. Этот шаблон используется и для создания, и для редактирования.
Основные блоки:
{% block content %} — основной блок для отображения формы. В этом блоке происходит рендеринг полей модели и элементов управления.
{% block object-tools-items %} — панель инструментов с кнопками. В этом блоке отображается кнопка "История".
{% block form_top %} — места для добавления кастомного контента перед формой. К примеру Можно добавить общую подсказку/инструкцию на всю форму.
{% block submit_buttons_top %} и {% block submit_buttons_button %} - в них располагаются кнопки сохранения и удаления. Сами блок кнопок будет взят из шаблона submit_line.html и подставлен на место {% submit_row %}
submit_line.html Этот шаблон используется для добавления стандартных кнопок, таких как «Сохранить», «Сохранить и продолжить» и «Сохранить и добавить другой», и позволяет удобно управлять процессом отправки формы. Можем модифицировать его для добавления своих кнопок.
4. Шаблоны фильтров, поиска, действий
search_form.html Шаблон для отображения формы поиска. Включает в себя поле ввода, где пользователь может в��ести запрос для поиска объектов модели.
filter.html Шаблон для отображения формы фильтрации. Он содержит элементы управления для выбора различных критериев фильтрации, таких как категории, даты, статусы и другие параметры, заданные в list_filter модели. Этот шаблон отображает боковую панель фильтров.
actions.html Шаблон для отображения массовых действий над списком объектов. Он включает выпадающий список с доступными действиями, такими как удаление, экспорт, публикация и т.д., а также кнопку для выполнения выбранного действия.
5. Остальные шаблоны
Эти шаблоны не вписываются ни в какую категорию, но все же важно их упомянуть:
nav_sidebar.html Шаблон для отображения боковой панели навигации. Здесь отображаются приложения и модели.
404.html Шаблон для отображения страницы ошибки 404 (страница не найдена). Этот шаблон отображается пользователю, когда он пытается перейти на несуществующую страницу в админке.
login.html Шаблон для отображения формы входа в админку
confirmation.html Шаблон для отображения страницы подтверждения действия,
Это все основные шаблоны, которые с большей вероятностью понадобится изменять.
Полный список шаблонов можно посмотреть в django по следующему пути: django/django/contrib/admin/templates/admin/
Там можно найти директорию widgets, в которой находятся шаблоны для виджетов и edit_inline с шаблонами для инлайнов. Всё это можно модифицировать при необходимости.
Так же Вы уже могли обратить внимание, что в большинстве шаблонов встречаются блоки extrahead и extrastyle. Они используются для добавления дополнительных заголовков и стилей.
Отлично! Шаблоны разобрали. А теперь давайте разберем как же Django находит шаблоны в проекте.
Как Django ищет шаблоны?
Понимание этого механизма критически важно. С первого взгляда он не самый очевидный, но его достаточно просто понять.
Всё начинается с настройки TEMPLATES в settings.py
TEMPLATES = [
{
...
'DIRS': [os.path.join(BASE_DIR, 'templates')],
'APP_DIRS': True,
...
},
]Ключ DIRS содержит список путей, где Django будет искать шаблоны. В нашем случае будет одна корневая папка в директории BASE_DIR/templates. Шаблоны из этой папки будут использованы, если их не переопределит приложение.
Ключ APP_DIRS включает/выключает поиск шаблонов в папках приложений. К примеру, у нас есть приложение Users. В этом приложении своя папка templates. Шаблоны приложения переопределяют шаблоны из DIRS.
Разберем на примере. Есть следующая структура проекта:
django_project/
├── templates/ # Основная папка с шаблонами
└── admin/
└── change_form.html # Наш кастомный шаблон №1
└── users/
└── templates/
└── admin/
└── users/ # Папка с шаблонами приложения users
└── change_form.html # Наш кастомный шаблон №2Для всех моделей внутри приложения users будет применен шаблон django_project/users/templates/admin/users/change_form.html
Для всех остальных приложений будет использован шаблон django_project/templates/admin/change_form.html.
Так же возможно переопределить шаблон только для конкретной модели, если создать папку django_project/users/templates/users/<my_model_in_lower_case>/change_form.html.
Не все шаблоны можно переопределить для конкретной модели или приложения, полный список можно найти в документации.
Заключение
Кастомизация шаблонов — это только начало в настройке Django Admin под конкретные задачи проекта. Мы всё еще не затронули множество других инструментов для кастомизации: создание собственных фильтров, добавление собственных действий, создание своих страниц, не привязанных к конкретному приложению, добавление JavaScript, оптимизацию производительности и многое другое. Увидимся в следующих статьях!
P.S Я веду свой авторский канал о разработке в Telegram. Публикую выжимки с конференций, делюсь рабочей рутиной и полезными идеями/мыслями.
