Кастомизация Django Admin. Часть 1: Структура шаблонов

Давайте просто признаемся друг другу… Все мы иногда это делаем. Все мы иногда кастомизируем Django админку. Без четкого понимания того, как построены шаблоны и используемые классы любая попытка кастомизации превращается в пытку.
Этот цикл статей — моя попытка помочь понять и полюбить то, как всё устроено изнутри. Тема длинная, так что начнем с самых азов. Сейчас мы разберем все основные шаблоны и механизм их поиска.

В первую очередь узнаем какие шаблоны есть и из чего они состоят. Из этих шаблонов построен интерфейс административной панели. Они работают на Django Template Language (DTL). Это встроенный механизм для динамической генерации HTML в Django Если вдруг с ним еще не знакомы или нужно освежить память, то почитать можно тут.

Важно отметить, что редактирование шаблонов напрямую — чаще всего не лучшее решение. Для этого в Django есть множество удобных инструментов, о которых мы поговорим в следующих статьях. Тем не менее, понимание структуры важно для полной и понятной картины принципов работы админки.

Основные компоненты шаблонов Django Admin

Шаблоны Django Admin состоят из нескольких основных компонентов, которые можно разделить на следующие категории:

1. Базовые шаблоны

2. Шаблоны списка объектов

3. Шаблоны форм

4. Шаблоны фильтров, поиска, действий

5. Другое, но тоже важное

Теперь разберем каждый шаблон по отдельности и рассмотрим основные блоки поближе. Для удобства можно нажать на название файла и изучить подробнее в репозитории 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. Публикую выжимки с конференций, делюсь рабочей рутиной и полезными идеями/мыслями.