Templates

Jede Seite im Admin ist ein Jinja2-Template, das Sie überschreiben können. Ändern Sie eine einzelne Listenseite, die Tabellenzelle eines Feldes oder ein Dashboard-Widget, ohne den integrierten Template-Baum zu forken.

Funktionsweise des Template-Loaders

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 erzeugt einen Jinja2-ChoiceLoader, der zuerst Ihr templates_dir und danach das integrierte Paketverzeichnis starlette_admin/templates/ durchsucht. Legen Sie eine Datei unter my_templates/ mit demselben relativen Pfad ab, den sie innerhalb von starlette_admin/templates/ hat, so überlagert Ihre Datei die integrierte Version. Alle übrigen Templates werden weiterhin aus dem integrierten Verzeichnis gerendert.

Verzeichnisübersicht der Templates

Überschreiben eines einzelnen Seiten-Templates

my_templates/
└── list.html   ← überlagert das integrierte list.html

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

{% block content %}
  <div class="alert alert-info">Eigener Banner oberhalb der Liste.</div>
  {{ super() }}
{% endblock %}

{% extends "list.html" %} würde zurück auf Ihr eigenes my_templates/list.html aufgelöst, weil templates_dir zuerst geprüft wird – und diese zirkuläre Referenz löst einen Fehler wegen unendlicher Rekursion aus. Das Präfix @starlette-admin/ zeigt immer auf die integrierte Kopie; daher muss jedes extends und include innerhalb einer Überlagerung dieses Präfix verwenden statt des bloßen Dateinamens.

Überschreibbare Blöcke

Jede integrierte Seite erweitert layout.html, das wiederum base.html erweitert. Überschreiben Sie einen einzelnen {% block %} statt einer ganzen Datei, um ein Fragment zu ändern, ohne den Rest der Seite zu duplizieren:

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

{% block list_toolbar_extra %}
  {{ super() }}
  <a class="btn btn-outline-primary" href="/reports/export">Eigener Bericht</a>
{% endblock %}

base.html

layout.html

list.html

detail.html

create.html / edit.html

login.html

index.html

error.html

Beispiel: Ersetzen des Sidebar-Logos durch ein Inline-SVG

Das Übergeben einer URL an Admin(logo_url=...) ist der schnellste Weg, ein Logo zu setzen, und deckt die meisten Fälle ab – auch externe .svg-Dateien. Da das integrierte Template diese URL jedoch innerhalb eines <img>-Tags rendert, kann das SVG keine CSS-Eigenschaften von der umgebenden Seite erben.

Überschreiben Sie den Block brand mit Inline-<svg>-Markup, wenn das Logo auf die restliche Benutzeroberfläche reagieren soll.

Implementierung

Erstellen Sie eine Datei layout.html in Ihrem Templates-Verzeichnis. Jede Seite im Admin erbt von layout.html, sodass diese eine Überlagerung sitewide greift.

{# 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 %}

Überschreiben von Feld-Templates

Jeder Feldkontext verwendet drei Unterverzeichnisse:

Sie können die Listenzelle für Textfelder überschreiben, ohne das Formular oder die Detailanzeige anzupassen:

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

Um eine einzelne Feldinstanz auf Ihr Template zu verweisen, statt den Typ überall zu überschreiben, setzen Sie list_template, detail_template, form_template, null_template oder empty_template direkt am Feld:

from starlette_admin.fields import StringField

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

null_template (Standard "fields/detail/_null.html") und empty_template (Standard "fields/detail/_empty.html") sind eigene Slots. Die Listen- und Detailseiten rendern sie anstelle von list_template bzw. detail_template, wann immer der Wert des Feldes None oder eine leere Liste bzw. ein leeres Tupel ist:

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

Überschreiben von Widget-Templates

Widgets folgen demselben Überlagerungsmuster. Legen Sie Ihre Dateien unter dem Verzeichnis widgets/ ab:

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

Globale Template-Variablen

Diese Variablen sind in jedem Template verfügbar, ohne dass sie übergeben werden müssen. Admin installiert sie einmalig während des Setups als Jinja2-Globals:

Kontextvariablen pro Seite

Zusätzlich zu den Globals oben übergibt jede Seite ihr eigenes Kontext-Wörterbuch an TemplateResponse.

list.html

detail.html

create.html / edit.html

Eigene Globals und Filter hinzufügen

Um eigene Variablen und Funktionen zu den Templates hinzuzufügen, subclassen Sie Admin und überschreiben __init__. Rufen Sie zunächst super().__init__() auf, damit self.templates existiert, bevor Sie etwas ergänzen:

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")

Integrierte Jinja2-Filter

Jede Admin-Instanz registriert diese Filter während _setup_templates:

Nächste Schritte

• Formularlayouts: Teilen Sie die Erstellungs- und Bearbeitungsformulare in betitelte, optional einklappbare Gruppen auf, und überschreiben Sie _form_group.html, um deren Markup zu ändern.
• Eigene Themes: Gestalten Sie den Admin um, ohne einzelne Templates anzufassen.
• Eigene Felder: Kombinieren Sie die Python-Klasse eines Feldes mit dessen eigenem list_template oder form_template.
• Erweiterungspunkte: Die vollständige Liste der pluggable Oberflächen jenseits der Templates.