Plantillas

Cada página del admin es una plantilla de Jinja2 que usted puede sobrescribir. Modifique una única página de lista, la celda de tabla de un campo o un widget del panel de control sin tener que bifurcar el árbol de plantillas integrado.

Cómo funciona el cargador de plantillas

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 construye un ChoiceLoader de Jinja2 que consulta primero su templates_dir y después el directorio del paquete integrado starlette_admin/templates/. Coloque un archivo bajo my_templates/ en la misma ruta relativa que tiene dentro de starlette_admin/templates/ y su archivo ocultará al integrado. Todas las demás plantillas seguirán renderizándose desde el directorio integrado.

Mapa del directorio de plantillas

Sobrescribir una plantilla de página individual

my_templates/
└── list.html   ← oculta el list.html integrado

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

{% block content %}
  <div class="alert alert-info">Banner personalizado sobre la lista.</div>
  {{ super() }}
{% endblock %}

{% extends "list.html" %} resolvería de nuevo a su propio my_templates/list.html, porque templates_dir se consulta primero, y esa referencia circular provoca un error de recursión infinita. El prefijo @starlette-admin/ apunta siempre a la copia integrada, por lo que cada extends e include dentro de una sobrescritura debe usarlo en lugar del nombre de archivo simple.

Bloques sobrescribibles

Cada página integrada extiende layout.html, que a su vez extiende base.html. Sobrescriba un único {% block %} en lugar de un archivo completo para modificar un fragmento sin duplicar el resto de la página:

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

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

base.html

layout.html

list.html

detail.html

create.html / edit.html

login.html

index.html

error.html

Ejemplo: reemplazar el logotipo de la barra lateral con un SVG en línea

Pasar una URL a Admin(logo_url=...) es la forma más rápida de establecer un logotipo y cubre la mayoría de los casos, incluidos los archivos .svg externos. No obstante, la plantilla integrada renderiza esa URL dentro de una etiqueta <img>, por lo que el SVG no puede heredar propiedades CSS de la página circundante.

Sobrescriba el bloque brand con marcado <svg> en línea cuando necesite que el logotipo responda al resto de la interfaz.

Implementación

Cree un archivo layout.html en su directorio de plantillas. Cada página del admin hereda de layout.html, por lo que esta única sobrescritura se aplica a todo el sitio.

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

Sobrescribir plantillas de campos

Cada contexto de campo utiliza tres subdirectorios:

Puede sobrescribir la celda de lista para los campos de texto sin tocar el formulario ni la visualización de detalle:

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

Para apuntar una instancia de campo concreta a su plantilla en lugar de sobrescribir el tipo en todas partes, establezca list_template, detail_template, form_template, null_template o empty_template en el propio campo:

from starlette_admin.fields import StringField

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

null_template (por defecto "fields/detail/_null.html") y empty_template (por defecto "fields/detail/_empty.html") son ranuras independientes. Las páginas de lista y de detalle los renderizan en lugar de list_template o detail_template siempre que el valor del campo sea None o una lista o tupla vacía:

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

Sobrescribir plantillas de widgets

Los widgets siguen el mismo patrón de sobrescritura. Coloque sus archivos bajo el directorio widgets/:

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

Variables globales de plantilla

Estas variables están disponibles en todas las plantillas sin necesidad de pasarlas explícitamente. Admin las instala como globales de Jinja2 una sola vez durante la configuración:

Variables de contexto por página

Además de las globales anteriores, cada página pasa su propio diccionario de contexto a TemplateResponse.

list.html

detail.html

create.html / edit.html

Añadir sus propias variables globales y filtros

Para añadir sus propias variables y funciones a las plantillas, cree una subclase de Admin y sobrescriba __init__. Llame primero a super().__init__(), de modo que self.templates exista antes de añadirle elementos:

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

Filtros de Jinja2 integrados

Cada instancia del admin registra estos filtros durante _setup_templates:

Qué sigue

• Diseños de formulario: Divida los formularios de creación y edición en grupos con título, opcionalmente plegables, y sobrescriba _form_group.html para cambiar su marcado.
• Temas personalizados: Restilice el admin sin tocar plantillas individuales.
• Campos personalizados: Empareje la clase Python de un campo con su propia list_template o form_template.
• Puntos de extensión: La lista completa de superficies conectables más allá de las plantillas.