Cómo sobreescribir plantillas

En tu proyecto, es posible que desees sobrescribir una plantilla en otra aplicación Django, ya sea una tercera parte o una contribución como django.contrib.admin. Puedes poner sobrescrituras de plantillas en el directorio de plantillas de tu proyecto o en el directorio de plantillas de una aplicación.

Si tienes directorios de plantillas de aplicaciones y proyectos que contienen ambos sobrescripciones, el cargador de plantillas Django por defecto intentará cargar la plantilla del directorio de nivel de proyecto primero. En otras palabras, DIRS se busca antes que APP_DIRS.

Ver también

Lee sobrescribiendo-plantillas-de-widget-integradas si estás buscando hacer eso.

Sobreescribir desde el directorio de plantillas del proyecto

Primero, exploraremos sobrescribir plantillas creando plantillas de reemplazo en el directorio de plantillas de tu proyecto.

Digamos que estás tratando de sobrescribir las plantillas para una aplicación tercera llamada blog, que proporciona las plantillas blog/post.html y blog/list.html. Las configuraciones relevantes para tu proyecto serían como:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

INSTALLED_APPS = [
    ...,
    "blog",
    ...,
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        # ...
    },
]

La configuración TEMPLATES y BASE_DIR ya existirán si creaste tu proyecto utilizando el modelo de proyecto por defecto. La configuración que necesita modificarse es DIRS.

Estas configuraciones asumen que tienes un directorio templates en la raíz de tu proyecto. Para sobrescribir las plantillas para la aplicación blog, crea una carpeta en el directorio templates y agrega los archivos de plantilla a esa carpeta:

templates/
    blog/
        list.html
        post.html

El cargador de plantillas primero busca plantillas en el directorio DIRS. Cuando las vistas de la aplicación blog piden las plantillas blog/post.html y blog/list.html, el cargador devolverá los archivos que acabas de crear.

Sobreescribiendo desde el directorio de plantillas de una aplicación

Dado que estás sobrescribiendo plantillas ubicadas fuera de alguna de las aplicaciones de tu proyecto, es más común utilizar el primer método y poner las sobrescripciones en un directorio de plantillas del proyecto. Si lo prefieres, sin embargo, también es posible poner las sobrescripciones en el directorio de plantillas de una aplicación.

Primero, asegúrate de que tus configuraciones de plantilla estén comprobando dentro de los directorios de aplicación:

TEMPLATES = [
    {
        # ...
        "APP_DIRS": True,
        # ...
    },
]

Si deseas poner las sobrescripciones de plantilla en una aplicación llamada myapp y las plantillas a sobrescribir se llaman blog/list.html y blog/post.html, entonces tu estructura de directorio será como sigue:

myapp/
    templates/
        blog/
            list.html
            post.html

Con APP_DIRS establecido en True, el cargador de plantilla buscará en el directorio de plantillas de la aplicación y encontrará las plantillas.

Extender una plantilla sobrescrita

Una vez configurados los cargadores de plantilla, puedes extender una plantilla utilizando el etiqueta de plantilla {% extends %} mientras a la vez la sobrescribes. Esto puede permitirte hacer pequeñas personalizaciones sin necesidad de reimplementar toda la plantilla.

Por ejemplo, puedes utilizar esta técnica para agregar un logo personalizado a la plantilla admin/base_site.html:

templates/admin/base_site.html
 {% extends "admin/base_site.html" %}

 {% block branding %}
   <img src="link/to/logo.png" alt="logo">
   {{ block.super }}
 {% endblock %}

Puntos clave a tener en cuenta:

  • El ejemplo crea un archivo en templates/admin/base_site.html que utiliza el directorio de plantillas configurado a nivel de proyecto para sobreescribir admin/base_site.html.

  • La nueva plantilla extiende admin/base_site.html, que es la misma plantilla que se está sobrescribiendo.

  • La plantilla reemplaza solo el bloque branding, agregando un logo personalizado, y utilizando block.super para mantener el contenido anterior.

  • El resto de la plantilla se hereda sin cambios de admin/base_site.html.

Esta técnica funciona porque el cargador de plantillas no considera la plantilla de sobrescritura ya cargada (en templates/admin/base_site.html) al resolver el etiqueta extends. Combinado con block.super es una técnica poderosa para hacer pequeñas personalizaciones.

« previous | up | next »