Templates

Chaque page de l'admin est un template Jinja2 que vous pouvez remplacer. Modifiez une seule page de liste, la cellule d'un champ dans le tableau, ou un widget du dashboard sans dupliquer l'arborescence des templates intégrés.

Fonctionnement du loader de templates

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 construit un ChoiceLoader Jinja2 qui interroge d'abord votre templates_dir, puis le répertoire intégré du package starlette_admin/templates/. Placez un fichier sous my_templates/ au même chemin relatif qu'il occupe dans starlette_admin/templates/ et votre fichier masquera celui intégré. Tous les autres templates continuent d'être rendus depuis le répertoire intégré.

Cartographie des répertoires de templates

Remplacer le template d'une seule page

my_templates/
└── list.html   ← remplace le list.html intégré

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

{% block content %}
  <div class="alert alert-info">Bannière personnalisée au-dessus de la liste.</div>
  {{ super() }}
{% endblock %}

{% extends "list.html" %} résoudrait vers votre propre my_templates/list.html, car templates_dir est interrogé en premier, et cette référence circulaire provoque une erreur de récursion infinie. Le préfixe @starlette-admin/ pointe toujours vers la copie intégrée : chaque extends et include dans un fichier de remplacement doit donc l'utiliser plutôt que le nom de fichier seul.

Blocs remplaçables

Chaque page intégrée étend layout.html, qui étend lui-même base.html. Remplacez un seul {% block %} plutôt qu'un fichier entier pour modifier un fragment sans dupliquer le reste de la page :

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

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

base.html

layout.html

list.html

detail.html

create.html / edit.html

login.html

index.html

error.html

Exemple : remplacer le logo de la sidebar par un SVG en ligne

Passer une URL à Admin(logo_url=...) est le moyen le plus rapide de définir un logo et couvre la plupart des cas, y compris les fichiers .svg externes. Cependant, le template intégré affiche cette URL dans une balise <img>, si bien que le SVG ne peut pas hériter des propriétés CSS de la page environnante.

Remplacez le bloc brand avec du balisage <svg> en ligne lorsque vous avez besoin que le logo réponde au reste de l'interface.

Implémentation

Créez un fichier layout.html dans votre répertoire de templates. Chaque page de l'admin hérite de layout.html, ce remplacement s'applique donc à l'ensemble du site.

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

Remplacer les templates de champs

Le contexte de chaque champ utilise trois sous-répertoires :

Vous pouvez remplacer la cellule de liste pour les champs textuels sans toucher au formulaire ni à l'affichage détaillé :

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

Pour pointer une instance de champ précise vers votre template au lieu de remplacer le type partout, définissez list_template, detail_template, form_template, null_template ou empty_template directement sur le champ :

from starlette_admin.fields import StringField

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

null_template (par défaut "fields/detail/_null.html") et empty_template (par défaut "fields/detail/_empty.html") sont des emplacements distincts. Les pages de liste et de détail les affichent à la place de list_template ou detail_template chaque fois que la valeur du champ est None ou une liste ou un tuple vide :

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

Remplacer les templates de widgets

Les widgets suivent le même motif de remplacement. Placez vos fichiers sous le répertoire widgets/ :

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

Variables globales de template

Ces variables sont disponibles dans chaque template sans avoir à être passées explicitement. Admin les installe comme variables globales Jinja2 une seule fois lors de la configuration :

Variables de contexte par page

En plus des variables globales ci-dessus, chaque page transmet son propre dictionnaire de contexte à TemplateResponse.

list.html

detail.html

create.html / edit.html

Ajouter vos propres globals et filtres

Pour ajouter vos propres variables et fonctions aux templates, créez une sous-classe d'Admin et redéfinissez __init__. Appelez d'abord super().__init__(), afin que self.templates existe avant que vous ne le complétiez :

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

Filtres Jinja2 intégrés

Chaque instance de l'admin enregistre ces filtres durant _setup_templates :

Pour aller plus loin

• Mises en page de formulaire : Divisez les formulaires de création et d'édition en groupes titrés, éventuellement repliables, et remplacez _form_group.html pour modifier leur balisage.
• Thèmes personnalisés : Redonnez du style à l'admin sans toucher aux templates individuels.
• Champs personnalisés : Associez la classe Python d'un champ à son propre list_template ou form_template.
• Points d'extension : La liste complète des surfaces extensibles au-delà des templates.