Partials en plantillas DTL

Qué aporta un partial

Un partial permite declarar un fragmento reutilizable dentro de una plantilla DTL y renderizarlo después con un nombre propio. Esto resulta útil cuando varias partes del mismo archivo comparten estructura y quieres mantener la lógica visual en un solo lugar.

Un partial no sustituye siempre a un template separado. Su ventaja aparece cuando varias piezas de una misma vista tienen alta cohesión y merece la pena mantenerlas juntas.

Esta técnica reduce duplicación y evita que una interfaz sencilla termine repartida en demasiados archivos diminutos. Encaja especialmente bien con flujos modernos como HTMX, Hotwire/Turbo o HTML over the wire, donde el servidor envía trozos de HTML a un fragmento concreto del DOM.

Instalación del paquete

La directiva {% partialdef %} no forma parte del núcleo de Django; la aporta el paquete oficial django-template-partials, mantenido por miembros del Django Software Foundation y usado por proyectos como django-htmx. Su instalación es sencilla:

El siguiente diagrama resume visualmente los conceptos clave introducidos en esta seccion:

graph TD
    A[Plantilla] --> B[load partials]
    B --> C[partialdef nombre]
    C --> D[Bloque HTML reutilizable]
    A --> E[partial nombre]
    E --> D
    A --> F[include otra plantilla]
    A --> G[block extends]
    A --> H[Componentes con django-components]

pip install django-template-partials

INSTALLED_APPS = [
    "template_partials",
    "django.contrib.staticfiles",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": ["templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "builtins": ["template_partials.templatetags.partials"],
        },
    },
]

Con esto las etiquetas {% partialdef %} y {% partial %} quedan disponibles globalmente sin necesidad de hacer {% load partials %} en cada template.

Definición y renderizado

La forma más directa de trabajar con partials es definir el fragmento y reutilizarlo dentro del mismo template:

{% partialdef product_card %}
  <article class="card">
    <h3>{{ product.name }}</h3>
    <p>{{ product.price }}</p>
  </article>
{% endpartialdef %}

<section class="grid">
  {% for product in products %}
    {% partial product_card with product=product %}
  {% endfor %}
</section>

También es posible referenciar un partial con la sintaxis template#partial cuando el flujo de renderizado lo necesita:

from django.shortcuts import render

return render(request, "shop/product_list.html#product_card", {
    "product": product,
})

Esta sintaxis es útil cuando una vista necesita renderizar solo una pieza concreta del template, por ejemplo en una respuesta parcial o en una actualización progresiva de interfaz.

Diferencia con {% include %}

Tanto include como partial permiten reutilizar HTML, pero resuelven problemas distintos:

| Aspecto | {% include %} | {% partial %} | |----------------------------|----------------------------------------------|----------------------------------------------| | Localización del fragmento | Otro archivo independiente | Dentro del mismo template | | Coste de I/O | Una lectura de disco (con caché de loader) | Cero, ya está en el AST del template padre | | Acoplamiento | Bajo: el fragmento se reutiliza en muchas páginas | Alto: el fragmento "pertenece" a la plantilla padre | | Render desde la vista | render(request, "_card.html", ctx) | render(request, "list.html#card", ctx) | | Ideal para | Componentes globales (header, footer, modal) | Ítems repetidos de una pantalla concreta y respuestas parciales HTMX/Turbo |

En la práctica, los proyectos modernos suelen combinar ambos: include para componentes globales y partial para los trozos específicos de cada pantalla.

Caso real: lista paginada que actualiza HTMX

Un patrón muy frecuente es renderizar la primera página con la plantilla completa y, ante un evento HTMX, devolver solo el partial con los siguientes resultados. Esto evita reenviar el chrome de la página y mantiene un único template como fuente de verdad.

{# templates/shop/product_list.html #}
{% extends "base.html" %}

{% partialdef product_row %}
  {% for product in page_obj %}
    <tr>
      <td>{{ product.name }}</td>
      <td>{{ product.price }}</td>
    </tr>
  {% endfor %}
  {% if page_obj.has_next %}
    <tr hx-get="?page={{ page_obj.next_page_number }}"
        hx-trigger="revealed"
        hx-swap="outerHTML">
      <td colspan="2">Cargando mas...</td>
    </tr>
  {% endif %}
{% endpartialdef %}

{% block content %}
  <table>
    <thead><tr><th>Nombre</th><th>Precio</th></tr></thead>
    <tbody id="rows">
      {% partial product_row %}
    </tbody>
  </table>
{% endblock %}

from django.core.paginator import Paginator
from django.shortcuts import render
from .models import Product

def product_list(request):
    page_obj = Paginator(Product.objects.all(), 25).get_page(request.GET.get("page"))
    template = "shop/product_list.html"
    if request.headers.get("HX-Request"):
        template += "#product_row"
    return render(request, template, {"page_obj": page_obj})

La misma vista atiende la petición completa y la petición HTMX cambiando solo el sufijo del template. El partial es la única fuente que renderiza filas, así que cualquier cambio se refleja en ambos flujos sin duplicación.

Cuándo usar partials y cuándo no

Los partials funcionan bien cuando la plantilla tiene un componente visual repetible con pocos puntos de variación. Un caso típico es una cuadrícula de tarjetas, una fila de tabla o una celda enriquecida.

Suele ser mejor mantener un archivo independiente cuando:

• 1. El fragmento crece demasiado y empieza a tener bloques, includes o lógica visual propia.
• 2. El mismo componente se usa en varias pantallas sin relación directa.
• 3. El equipo necesita una separación más clara entre piezas para revisar cambios o trabajar en paralelo.

En la práctica, la decisión más acertada es la que mantiene la lectura del template clara. Si el archivo principal sigue siendo comprensible, el partial aporta orden. Si empieza a volverse denso, conviene extraerlo a un template separado.