Шаблоны

Каждая страница административной панели — это шаблон Jinja2, который вы можете переопределить. Измените отдельную страницу списка, ячейку таблицы одного поля или виджет дашборда, не создавая форк встроенного дерева шаблонов.

Как работает загрузчик шаблонов

from sqlalchemy import create_engine
from starlette_admin.contrib.sqla import Admin

engine = create_engine("sqlite:///admin.sqlite")
admin = Admin(engine, title="My Admin", templates_dir="my_templates/")

Admin создает загрузчик Jinja2 ChoiceLoader, который сначала проверяет ваш templates_dir, а затем встроенный каталог пакета starlette_admin/templates/. Поместите файл в my_templates/ по тому же относительному пути, что и внутри starlette_admin/templates/, — и ваш файл затмит встроенный. Все остальные шаблоны продолжат рендериться из встроенного каталога.

Карта каталога шаблонов

Переопределение шаблона одной страницы

my_templates/
└── list.html   ← затмевает встроенный list.html

{# my_templates/list.html #}
{% extends "@starlette-admin/list.html" %}

{% block content %}
  <div class="alert alert-info">Пользовательский баннер над списком.</div>
  {{ super() }}
{% endblock %}

Запись {% extends "list.html" %} разрешилась бы обратно в ваш собственныйmy_templates/list.html, посколькуtemplates_dirпроверяется первым, а такая циклическая ссылка вызывает ошибку бесконечной рекурсии. Префикс@starlette-admin/всегда указывает на встроенную копию, поэтому каждыйextendsиinclude` внутри переопределения должен использовать именно его вместо имени файла без префикса.

Переопределяемые блоки

Каждая встроенная страница расширяет layout.html, который в свою очередь расширяет base.html. Вместо замены целого файла переопределите один {% block %}, чтобы изменить отдельный фрагмент, не дублируя остальную часть страницы:

{# my_templates/list.html #}
{% extends "@starlette-admin/list.html" %}

{% block list_toolbar_extra %}
  {{ super() }}
  <a class="btn btn-outline-primary" href="/reports/export">Пользовательский отчет</a>
{% endblock %}

base.html

layout.html

list.html

detail.html

create.html / edit.html

login.html

index.html

error.html

Пример: замена логотипа боковой панели на inline SVG

Передача URL в Admin(logo_url=...) — самый быстрый способ задать логотип, подходящий для большинства случаев, включая внешние .svg-файлы. Однако встроенный шаблон отображает этот URL внутри тега <img>, поэтому SVG не может наследовать CSS-свойства окружающей страницы.

Переопределите блок brand разметкой inline <svg>, если вам нужно, чтобы логотип реагировал на остальной интерфейс.

Реализация

Создайте файл layout.html в вашем каталоге шаблонов. Каждая страница админ-панели наследуется от layout.html, поэтому это одно переопределение действует на всем сайте.

{# my_templates/layout.html #}
{% extends "@starlette-admin/layout.html" %}

{% block brand %}
  <svg class="navbar-logo" viewBox="0 0 32 32" fill="currentColor">
    <path d="M16 2 L30 9 L30 23 L16 30 L2 23 L2 9 Z" />
  </svg>
{% endblock %}

Переопределение шаблонов полей

Контекст каждого поля использует три подкаталога:

Вы можете переопределить ячейку списка для текстовых полей, не затрагивая форму или отображение детализации:

my_templates/
└── fields/
    └── list/
        └── text.html

Чтобы указать одному экземпляру поля использовать ваш шаблон вместо переопределения типа повсюду, задайте атрибут list_template, detail_template, form_template, null_template или empty_template у самого поля:

from starlette_admin.fields import StringField

StringField("status", list_template="fields/list/status_badge.html")

Атрибуты null_template (по умолчанию "fields/detail/_null.html") и empty_template (по умолчанию "fields/detail/_empty.html") являются отдельными слотами. Страницы списка и детализации рендерят их вместо list_template или detail_template всякий раз, когда значение поля равно None либо является пустым списком или кортежем:

StringField("status", null_template="fields/detail/_status_null.html")

Переопределение шаблонов виджетов

Виджеты следуют тому же шаблону переопределения. Поместите свои файлы в каталог widgets/:

my_templates/
└── widgets/
    └── stat_widget.html

Глобальные переменные шаблонов

Эти переменные доступны в каждом шаблоне без явной передачи. Admin регистрирует их как глобальные переменные Jinja2 один раз во время инициализации:

Контекстные переменные отдельных страниц

Помимо перечисленных выше глобальных переменных, каждая страница передает собственный словарь контекста в TemplateResponse.

list.html

detail.html

create.html / edit.html

Добавление собственных глобальных переменных и фильтров

Чтобы добавить собственные переменные и функции в шаблоны, создайте подкласс Admin и переопределите __init__. Сначала вызовите super().__init__(), чтобы self.templates существовал до ваших изменений:

from sqlalchemy import create_engine
from starlette_admin.contrib.sqla import Admin


class MyAdmin(Admin):
    def __init__(self, *args, **kwargs) -> None:
        super().__init__(*args, **kwargs)
        self.templates.env.globals["site_name"] = "My App"
        self.templates.env.filters["currency"] = lambda v: f"${v:,.2f}"


engine = create_engine("sqlite:///admin.sqlite")
admin = MyAdmin(engine, title="My Admin")

Встроенные фильтры Jinja2

Каждый экземпляр админ-панели регистрирует эти фильтры во время _setup_templates:

Что дальше

• Макеты форм: Разделите формы создания и редактирования на озаглавленные, опционально сворачиваемые группы и переопределите _form_group.html, чтобы изменить их разметку.
• Пользовательские темы: Измените оформление админ-панели, не трогая отдельные шаблоны.
• Пользовательские поля: Свяжите Python-класс поля с его собственным list_template или form_template.
• Точки расширения: Полный список подключаемых поверхностей помимо шаблонов.