Plantillas¶

Django básico

Las plantillas en Django se utilizan para preparar el contenido final (habitualmente HTML) que se hará llegar al usuario de la aplicación web.

Las plantillas constituyen la capa de presentación del modelo por capas visto en la introducción al desarrollo web.

Ubicación¶

Cuando hacemos referencia a una plantilla —habitualmente desde una vista— mediante una ruta (relativa), Django utiliza la siguiente estrategia para localizar la plantilla indicada:

1. Siempre y cuando la variable APP_DIRS definida en settings.py esté a True:
   main/settings.py

   TEMPLATES = [
       {
           'BACKEND': 'django.template.backends.django.DjangoTemplates',
           'DIRS': [],
           'APP_DIRS': True,
           'OPTIONS': {
               'context_processors': [
                   'django.template.context_processors.request',
                   'django.contrib.auth.context_processors.auth',
                   'django.contrib.messages.context_processors.messages',
               ],
           },
       },
   ]
   

2. Las «otras» ubicaciones de plantillas se pueden indicar mediante la variable DIRS definida en settings.py.

   main/settings.py

   TEMPLATES = [
       {
           'BACKEND': 'django.template.backends.django.DjangoTemplates',
           'DIRS': [],
           'APP_DIRS': True,
           'OPTIONS': {
               'context_processors': [
                   'django.template.context_processors.request',
                   'django.contrib.auth.context_processors.auth',
                   'django.contrib.messages.context_processors.messages',
               ],
           },
       },
   ]
   

Supongamos por ejemplo que estamos en un proyecto de «blog» con las aplicaciones actions, comments, posts. Solicitamos a Django una plantilla con ruta 'posts/index.html':

flowchart TD
    t1["¿Existe posts/index.html en actions/templates?"]
    t2["¿Existe posts/index.html en comments/templates?"]
    t3["¿Existe posts/index.html en posts/templates"]
    t1 -->|No| t2
    t1 -->|Sí| r1(["Se devuelve actions/templates/posts/index.html"])
    t2 -->|No| t3
    t2 -->|Sí| r2(["Se devuelve comments/templates/posts/index.html"])
    t3 -->|No| s["¿Existe en otros directorios definidos en settings.py?"]
    t3 -->|Sí| r3(["Se devuelve posts/templates/posts/index.html"])
    s -->|No| err{{TemplateDoesNotExist}}
    s -->|Yes| r4(["Se devuelve el fichero correspondiente"])

Los espacios de nombres son muy importantes a la hora de organizar las plantillas de nuestro proyecto Django. Ya lo dice el Zen de Python: «Namespaces are one honking great idea -- let's do more of those!».

Una tabla resumen que puede aclarar distintos escenarios:

Variables¶

Para usar variables en una plantilla Django debemos rodear su nombre con dobles llaves {{}}

Por ejemplo si queremos mostrar un determinado «post» de un «blog» en una plantilla, podríamos usar la siguiente plantilla:

<h2>{{ post.title }}</h2><!--(1)!-->
<p>{{ post.content }}</p>

1. También podríamos haber usado directamente {{ post }} siempre y cuando se haya implementado convenientemente el método __str__() de la clase Post.

Desde la correspondiente vista, tendremos que renderizar la plantilla anterior mediante el siguiente fragmento de código:

from django.shortcuts import render


def post_detail(request, post_slug: str):
    # ...
    return render(request, 'posts/post/detail.html', {'post': post})#(1)!

1. En el contexto se fija el «post» que vamos a utilizar en la plantilla.

<h2>post.title.upper</h2>

Salida vacía¶

En una plantilla de Django, cuando la variable (o función) a la que estamos accediendo no existe no se produce ningún error. En tal caso, no se muestra nada por pantalla. Hay que tenerlo en cuenta para saber cómo proceder.

Esto se debe a que la opción string_if_invalid de main/settings.py establece lo que se muestra cuando no existe la variable (o función) y por defecto su valor es la cadena vacía ''.

Si queremos modificar ese comportamiento bastaría con modificar la configuración indicada.

Supongamos por ejemplo que ahora queremos mostrar el mensaje Missing variable: <variable> cada vez que una variable (o función) no estuviera definida. Para ello haríamos:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
            'string_if_invalid': 'Missing variable: %s',#(1)!
        },
    },
]

1. El modificador '%s' hace referencia a la variable que estamos intentando renderizar.

Etiquetas¶

Django proporciona una serie de etiquetas para usar en plantillas. Estas etiquetas ofrecen distintas funcionalidades y se caracterizan por usar sintaxis {% tag %}.

A continuación veremos los distintos tipos de etiquetas de plantilla que ofrece Django.

Bucles¶

Para recorrer estructuras de datos iterables en una plantilla se usa la etiqueta {% for %} análoga al bucle for de Python.

Veamos un ejemplo de plantilla en la que recorremos todos los «posts» de un blog:

<ul>
    {% for post in posts %}<!--(1)!-->
        <li>{{ post }}</li><!--(2)!-->
    {% endfor %}<!--(3)!-->
</ul>

1. En esta línea podemos usar directamente las variables sin usar doble .
2. Aquí si tenemos que acceder a la variable con doble .
3. Hay que terminar el bucle con esta sentencia.

Desde la correspondiente vista, tendremos que renderizar la plantilla anterior mediante el siguiente fragmento de código:

from django.shortcuts import render


def post_list(request):
    # ...
    return render(request, 'posts/post/list.html', {'posts': posts})#(1)!

1. En el contexto se fijan los «posts» que vamos a utilizar en la plantilla.

Desempaquetado¶

Los bucles en plantillas Django admiten también el desempaquetado de secuencias tal y como se hacen en Python «tradicional».

Por ejemplo con tuplas representando puntos en el espacio, tendríamos:

<div class="points">
{% for x, y in points %}
    <p>{{ x }},{{ y }}</p>
{% endfor %}
</div>

Variables especiales¶

Cuando usamos un bucle en una plantilla Django tenemos acceso a ciertas variables especiales que nos pueden facilitar la lógica a implementar.

Podríamos por ejemplo numerar los «posts» de nuestro «blog»:

<ul>
    {% for post in posts %}
        <li>{{ forloop.counter }}. {{ post }}</li>
    {% endfor %}
</ul>

Vacío¶

El bucle {% for %} admite la cláusula {% empty %} que se ejecuta cuando el iterable a recorrer está vacío o no existe.

En el ejemplo de los «posts» de un «blog», podríamos mostrar un mensaje en el caso de que no exisitera ningún «post»:

<ul>
    {% for post in posts %}
        <li>{{ post }}</li>
    {% empty %}
        <p>No posts so far!</p>
    {% endfor %}
</ul>

Ciclo¶

La etiqueta {% cycle %} puede ser útil dentro de un bucle ya que nos permite ir «alternando» entre distintos valores.

Por ejemplo imaginemos que queremos alternar el color de fondo de los distintos «posts» del «blog»:

<ul>
    {% for post in posts %}
        <li style="background-color: {% cycle 'LightBlue' 'LightPink' %}">
            {{ post }}
        </li>
    {% endfor %}
</ul>

Django ofrece la etiqueta {% resetcycle %} para reiniciar un ciclo {% cycle %} y que vuelva a empezar por su primer valor.

Condicionales¶

Django proporciona la etiqueta {% if %} para llevar a cabo comprobaciones en el código de una plantilla. Funciona de manera análoga a la sentencia if de Python.

En el siguiente ejemplo se muestra un mensaje diferente para el primer «post» del «blog»:

{% for post in posts %}
    <li>
    {% if forloop.first %}<!--(1)!-->
        <em>{{ post }}</em>
        <strong>(Post más antiguo)</strong>
    {% else %}<!--(2)!-->
        {{ post }}
    {% endif %}<!--(3)!-->
    </li>
{% endfor %}

1. Aplicamos una condición sobre el número de iteración.
2. No es obligatorio el uso de {% else %}.
3. Hay que terminar la condición con esta sentencia.

Operadores¶

Para construir condiciones más complejas podemos hacer uso de los mismos operadores lógicos que en Python «tradicional»: and, or y not.

Además tenemos disponibles otros operadores habituales:

URL¶

Ya hemos visto que las URLs definidas en urls.py pueden deben disponer de un nombre que las identifique.

En una plantilla usaremos la etiqueta {% url %} para renderizar la URL de un determinado recurso y no tener que escribirla directamente.

Como ejemplo vamos a mostrar la manera de ingresar la URL de acceso a todos los «posts» del blog o a uno en concreto. Se diferencian —por tanto— estos dos casos:

<a href="{% url 'posts:post-list' %}"><!--(1)!-->
    Ver todos los posts
</a>

<a href="{% url 'posts:post-detail' post.slug %}"><!--(1)!-->
    {{ post.title }}
</a>

Herencia¶

Cuando diseñamos una página web, hay ciertos componentes que son comunes a todas las «pantallas». Véase la cabecera («header»), el pie («footer») o las distintas barras de navegación («sidebar»). No parece muy razonable, reescribir estos componentes en todas las plantillas que hagamos. Siguiendo la filosofía DRY deberíamos poder «refactorizar» estas secciones y sólo añadir el contenido propio de cada página.

La herencia de plantillas se basa en definir una plantilla base desde la que derivamos otras plantillas. En la plantilla base se definen ciertos bloques que serán sobreescritos por las plantillas derivadas.

flowchart TB
    base[Plantilla base]
    base e1@--> p1[Plantilla derivada 1]
    base e2@--> p2[Plantilla derivada 2]
    base e3@--> p3[Plantilla derivada 3]
    base e4@--> p4[Plantilla derivada 4]
    e1@{ animate: true }
    e2@{ animate: true }
    e3@{ animate: true }
    e4@{ animate: true }

El elemento fundamental sobre el que trabaja la herencia es la etiqueta {% block %}. Nos permite definir un bloque (con nombre) para luego reutilizarlo en la jerarquía de plantillas.

Supongamos un ejemplo en el que estamos definiendo plantillas para un «blog». Lo primero será establecer una plantilla base:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{% if title %}{{ title }} | {% endif %}Blog</title><!--(1)!-->
  </head>

  <body>
    <div class="container">
        {% block content %}{% endblock %}<!--(2)!-->
    </div>
  </body>
</html>

1. • <title>Technology | Blog</title> si se envía título en el contexto {'title': 'Technology'} de la vista.
   • <title>Blog</title> si no se envía título en el contexto {} de la vista.

2. Se define un bloque para el contenido propio de la página.

Ahora vamos a crear una plantilla derivada (desde esta plantilla base) que se encargue de mostrar todos los «posts» del blog:

{% extends "base.html" %}<!--(1)!-->

{% block content %}<!--(2)!-->
    {% for post in posts %}
        <h3>{{ post }}</h3>
        <p>Read more <a href="{% url 'posts:post-detail' post.slug %}">here</a></p>
    {% endfor %}
{% endblock %}

1. • Extendemos de la plantilla base.
   • La sentencia {% extends %} debe ser la primera línea de la plantilla. En caso contrario se lanzará el siguiente error: <ExtendsNode: extends "base.html"> must be the first tag in the template.
2. • Sobreescribimos el bloque de contenido correspondiente a esta página.
   • Usar bloques sólo tiene sentido cuando estamos extendiendo de alguna plantilla base.

Inclusión¶

Django nos permite externalizar partes de una plantilla a un fichero, para luego incluirlo desde la propia plantilla. Para ello se utiliza la etiqueta {% include %}.

Supongamos por ejemplo que disponemos de la siguiente plantilla para mostrar la cabecera («header») de un «blog»:

<div class="header">
    <h1>The ultimate blog</h1>
    <h2>{{ subtitle }}</h1><!--(1)!-->
</div>

1. Es perfectamente válido utilizar variables o etiquetas dentro de las plantillas a incluir.

Django nos ofrece dos modos de incluir la plantilla anterior:

{% include "header.html" %} 
...

{% include "header.html" with subtitle="Don't miss the cutting edge info!" %} 
...

Otras etiquetas¶

A continuación se muestran otras etiquetas de plantilla disponibles en Django:

{% comment "Comentario opcional" %}
    <p>This won't be rendered</p>
{% endcomment %}

{% debug %}

{% firstof var1 var2 var3 %}<!--(1)!-->

{% lorem %}<!--(1)!-->
{% lorem 20 w %}<!--(2)!-->
{% lorem 3 p %}<!--(3)!-->

{% now "c" %}<!--(1)!-->
{% now "d-m-Y" %}<!--(2)!-->
{% now "l M/j/y" %}<!--(3)!-->

{% spaceless %}<!--(1)!-->
    <p>
        <a href="posts/">Post list</a>
    </p>
{% endspaceless %}

{% verbatim %}
    <p>This won't be {{ var }} rendered</p>
{% endverbatim %}

Etiquetas personalizadas¶

Django avanzado

Django permite crear etiquetas personalizadas más allá de las predefinidas («built-in»).

Aunque hay otros tipos, el caso de uso más habitual de una etiqueta personalizada es la de incluir una plantilla que requiere de cierto procesamiento previo. Es lo que Django denomina «inclusion tags» (etiquetas de inclusión).

Supongamos un ejemplo en el que queremos crear una etiqueta personalizada para listar todos los «posts» de nuestro «blog» que superen una determinada valoración.

El modelo del que partimos es el siguiente:

from django.db import models


class Post(models.Model):
    title = models.CharField(max_length=256)
    slug = models.SlugField(max_length=256, unique=True)
    content = models.TextField()
    rating = models.FloatField(default=0)

    def __str__(self):
        return self.title

Empezaremos por crear la plantilla que vamos a renderizar:

{% for post in posts %}
    <h1>{{ post.title }}</h1>
    <p>{{ post.content }}</p>
{% endfor %}

A continuación definimos la etiqueta:

from django import template
from posts.models import Post

register = template.Library()


@register.inclusion_tag('posts/includes/list.html')#(1)!
def post_list(min_rating: int = 0):#(2)!
    posts = Post.objects.filter(rating__gte=min_rating)#(3)!
    return {'posts': posts}#(4)!

1. • Es necesario registrar la etiqueta usando el decorador @register.
   • En este tipo de etiquetas se define la plantilla que se va a renderizar.
   • El argumento takes_context=True haría que dispusiéramos del parámetro context en post_list() para acceder al contexto de la petición.
2. • Esta etiqueta recibe un único parámetro que indica el mínimo «rating» a filtrar.
   • Las etiquetas personalizadas admiten cualquier número de parámetros.
3. Consulta de los «posts» que cumplen la condición.
4. Debemos retornar un diccionario que se convertirá en el contexto para renderizar la plantilla.

Lo que nos quedaría es utilizar la etiqueta creada en alguna plantilla:

{% load post_extras %}<!--(1)!-->

<div class="posts">
    {% post_list 5 %}<!--(2)!-->
</div>

1. Para poder utilizar la etiqueta debemos cargar el módulo en cuestión.
2. Dado que min_rating tiene un valor por defecto, podríamos usar la etiqueta sin argumentos: {% post_list %} (si queremos todos los «posts»).

Filtros¶

Django nos proporciona una enorme cantidad de filtros para utilizar en plantillas. Estos filtros ofrecen funcionalidades muy interesantes dependiendo del contexto que queramos abordar.

Hay dos tipos de filtros:

1. Aquellos que no admiten argumentos, cuya sintaxis es: {{ value|filter }}
2. Aquellos que sí admiten argumentos, cuya sintaxis es: {{ value|filter:"argument" }}

En la siguiente tabla se muestran todos los filtros de plantilla que ofrece Django clasificados por el tipo de dato que manejan:

Filtros personalizados¶

Django avanzado

Django permite crear filtros personalizados más allá de los predefinidos («built-in»).

A diferencia de las etiquetas los filtros deben recibir un argumento (y eventualmente otro). El primer argumento es el valor de la variable a la que aplicamos el filtro y el segundo argumento es opcional y permite modificar el comportamiento predefinido.

A continuación planteamos un ejemplo en el que se crea un filtro personalizado para calcular el «tamaño» de un «post» en función de varias métricas:

from django import template

from posts.models import Post

register = template.Library()


@register.filter#(1)!
def post_size(post: Post, metric: str = 'by-words') -> int:#(2)!
    match metric:
        case 'by-words':
            size = len(post.content.split())
        case 'by-chars':
            size = len(post.content)
        case _:
            size = 0
    return size#(3)!

1. • Es necesario registrar el filtro usando el decorador @register.
   • Es posible pasar un parámetro name (como str) al decorador para indicar el nombre del filtro. Si no se pasa, el nombre del filtro será el nombre de la función. Por ejemplo @register.filter(name='psize')
2. Los parámetros, en este caso son:
   • «Post» sobre el que vamos a calcular el tamaño.
   • Tipo de métrica:
     • 'by-words' para contar el número de palabras.
     • 'by-chars' para contar el número de caracteres.
   • La función (filtro) devuelve un número entero.
3. Retornamos el tamaño calculado según la lógica de negocio correspondiente.

Lo que nos quedaría es utilizar el filtro creado en alguna plantilla:

{% load post_extras %}<!--(1)!-->

<div class="posts">
    {% for post in posts %}
        <div class="post">
            {{ post|post_size }}<!--(2)!-->
        </div>
    {% endfor %}
</div>

1. Para poder utilizar el filtro debemos cargar el módulo en cuestión.
2. • La variable post se pasa como primer argumento. En este caso no hay segundo argumento.
   • Si quisiéramos una métrica por caracteres, podríamos haber escrito: {{ post|post_size:"by-chars" }}

Devolviendo HTML¶

Hay ocasiones en las que nos interesa implementar un filtro que devuelva código HTML. En principio lo haríamos de la misma forma que se ha visto anteriormente devolviendo una cadena de texto con el código HTML correspondiente.

Pero hay que tener en cuenta ciertos aspectos de seguridad:

1. Si el código HTML que vamos a devolver desde el filtro contiene potencial información proveniente del usuario (vía formulario por ejemplo), es altamente recomendable utilizar la función format_html que se encarga de escapar sus argumentos. Evitaríamos por ejemplo ataques XSS.
2. Si el código HTML que vamos a devolver contiene información confiable, necesitamos «marcarlo como seguro» para que Django realmente lo renderice en la plantilla final. Para ello haríamos uso de la función mark_safe.

Un ejemplo podría ser mostrar un determinado «post» con un formato HTML destacado:

from django import template
from django.utils.html import format_html#(1)!


from posts.models import Post

register = template.Library()


@register.filter
def post_link(post: Post) -> str:
    return format_html(
        '<a href="{}">{}</a>',
        post.get_absolute_url(),
        post.title,
    )#(2)!

{% load post_extras %}

<div class="posts">
    {% for post in posts %}
        <div class="post">
            {{ post|post_link }}
        </div>
    {% endfor %}
</div>

Procesadores de contexto¶

Django avanzado

La explicación de que en las plantillas tengamos acceso a los datos de depuración, a la petición HTTP, a la autenticación o a los mensajes, es que existen unos artefactos llamados procesadores de contexto que se encargan de inyectar cierta información en el contexto de la plantilla.

Estos procesadores de contexto se especifican en el fichero de configuración del proyecto —TEMPLATES → OPTIONS → context_processors— y por defecto es una lista que toma los siguientes valores:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Procesadores de contexto personalizados¶

Django nos permite implementar nuestros propios procesadores de contexto con el objetivo de inyectar en «todas» las plantillas ciertos datos comunes.

Planteamos un ejemplo en el que estamos diseñando un «blog» y queremos tener acceso en todo momento al último «post» que se ha publicado.

Un procesador de contexto no es más que una función que vive en algún lugar (aplicación) de nuestro proyecto:

from posts.models import Post


def last_post(request) -> dict:#(1)!
    if post := Post.objects.last():#(2)!
        return {'last_post': post}#(3)!
    return {}#(4)!

1. • Función que actúa como procesador de contexto.
   • Siempre recibe request (petición HTTP).
   • Siempre devuelve un diccionario.
2. • Lógica del procesador de contexto.
   • En este caso se busca el último «post» de la base de datos.
3. • Se devuelve un diccionario.
   • El objeto last_post estará disponible en todas las plantillas de forma automática.
4. En caso de errores se devuelve el diccionario vacío.

Para que Django «conozca» la existencia de este procesador de contexto debemos indicar su ruta completa en el fichero settings.py del proyecto:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [],
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
                'posts.context_processors.last_post',
            ],
        },
    },
]

De esta forma, en todas las plantillas del proyecto tendremos disponible el objeto last_post con el último «post» publicado en el «blog»:

<header>
    <h1>The ultimate blog</h1>
</header>

<section class="last-post">
    {{ last_post }}
</section>