Skip to content

4. Plantillas y formularios

Hasta ahora, las vistas generaban sus propias respuestas: texto, JSON y algunas etiquetas HTML escritas como una cadena. En una aplicación MVC, generar la página es la función de la V, que [Django] delega en una plantilla: un archivo que describe la página, con marcadores de posición para los datos que le pasa la vista, el contexto de la plantilla (el modelo M de MVC; véase la introducción).

[Django] tiene su propio motor de plantillas y su propio lenguaje de plantillas, DTL (Django Template Language). También puede usar otros motores, como [Jinja2], el que utiliza [Flask] (ajuste [TEMPLATES]); este documento se centra en DTL, que usan todas las aplicaciones de [Django]. Una plantilla es un archivo de texto, en este caso HTML (dada la extensión [.html]), almacenado en una carpeta llamada [templates], en la que se interpretan en el servidor tres tipos de etiquetas:

  • [{{ variable }}]: el valor de una variable del contexto, insertado en la página;
  • [{% tag %}]: una etiqueta que controla el motor: condición ([{% if %}]), bucle ([{% for %}]), herencia de plantillas ([{% extends %}], [{% block %}]), inclusión ([{% include %}]), creación de una URL ([{% url %}])...;
  • [{# comment #}]: un comentario que no aparece en la página generada. Cabe en una sola línea; un comentario de varias líneas se escribe entre las etiquetas [{% comment %}] y [{% endcomment %}].

Todo lo demás se copia literalmente. Las expresiones no se escriben en [Python], sino en el lenguaje deliberadamente limitado de DTL: [model.title] se refiere a la clave [title] de un diccionario, o al atributo [title] de un objeto, o al elemento [title] de una lista ([Django] los prueba en ese orden) y, si es un método, [Django] lo llama sin ningún parámetro; los filtros transforman un valor ([name|upper] pone un nombre en mayúsculas); las etiquetas realizan acciones. Eso es todo: DTL no tiene operadores aritméticos, ni llamadas a funciones con parámetros, ni asignaciones. Esto es deliberado: los creadores de [Django] querían que las plantillas las escribieran diseñadores gráficos, sin el riesgo de que la lógica de la aplicación se infiltrara en las páginas. Por lo tanto, un cálculo se realiza en [Python], ya sea en la vista o en un método de un objeto del contexto, y la plantilla simplemente muestra el resultado. Los lenguajes de [Twig] ([Symfony]) y [Jinja2] ([Flask]), que se inspiraron en él, son más permisivos: realizan cálculos ([total / count]) y llaman a funciones con parámetros. Por último, una plantilla no se vuelve a analizar en cada solicitud: en su primer uso, [Django] la analiza y la transforma en una lista de nodos (un objeto [Python]) que conserva en memoria y reutiliza a partir de entonces (en modo de depuración, la vuelve a analizar si se ha modificado). Veremos cómo es esa lista.

4.1. Ejemplo 13: una primera plantilla

13-first-view/
├── config/
│   ├── settings.py
│   ├── urls.py
│   └── ...
├── pages/
│   ├── __init__.py
│   ├── urls.py
│   ├── viewmodels.py
│   └── views.py
├── templates/
│   └── pages/
│       ├── index.html
│       └── unknown.html
└── manage.py

4.1.1. La configuración: config/settings.py

El motor de plantillas se configura mediante el ajuste [TEMPLATES]:

# config/settings.py: la configuración del ejemplo 13

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-_ph!-_ox*o_&n8o2i=ykjwic(j9!mwf!cc2(()%nzdrs9ssai_"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

INSTALLED_APPS = [
    "pages",
]

# los MOTORES DE PLANTILLAS: aquí uno solo, el de Django (el DTL, Django Template
# Language), que busca las plantillas en la carpeta templates del proyecto
TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
    },
]
  • Líneas 19–24: [TEMPLATES] es una lista de motores de plantillas, cada uno descrito por un diccionario. Aquí solo hay uno: [BACKEND] se refiere al motor [Django] (DTL); [DIRS] es la lista de carpetas donde busca plantillas: la carpeta [templates] del proyecto. La configuración también puede indicar al motor que busque plantillas en la carpeta [templates] de cada aplicación incluida en [INSTALLED_APPS] ([APP_DIRS: True], ejemplo 18): así es como una aplicación reutilizable proporciona sus propias plantillas.

Las plantillas se almacenan en una subcarpeta llamada [pages], que lleva el nombre de la aplicación: es una práctica habitual, que evita que dos aplicaciones tengan cada una una plantilla [index.html] y que una sobrescriba a la otra.

4.1.2. El contexto de la plantilla: pages/viewmodels.py

# pages/viewmodels.py: el modelo de la vista, los datos que la vista de Python pasa a la plantilla

from dataclasses import dataclass


@dataclass(frozen=True)
class PageModel:
    title: str
    message: str
    time: str

El contexto de una plantilla es un diccionario de [Python]. Aquí tendrá una sola entrada, [model], un objeto inmutable de la clase [PageModel] (véase el ejemplo 03), que contiene las tres piezas de información que mostrará la plantilla. No es obligatorio definir el contexto de una plantilla mediante una clase: se podrían pasar tres variables separadas a la plantilla. Sin embargo, una clase documenta lo que espera la plantilla y permite que el editor verifique el código de la vista. Este es el enfoque que seguirá el caso de estudio, donde cada página importante tiene su propia clase de plantilla.

4.1.3. Vistas: pages/views.py

# pages/views.py: vistas que devuelven una página construida por una PLANTILLA

from django.shortcuts import render
from django.utils import timezone
from django.views.decorators.http import require_GET

from .viewmodels import PageModel


# render: el motor de plantillas construye la página a partir de la plantilla
# templates/pages/index.html y del CONTEXTO, un diccionario de las variables puestas
# a disposición de la plantilla (aquí una sola, model); la página producida es el cuerpo
# de la respuesta
@require_GET
def index(request):
    model = PageModel(
        "My first template",
        "This page was built by Django, on the server.",
        # la hora, en la zona horaria de la aplicación (ajuste TIME_ZONE)
        timezone.localtime().strftime("%H:%M:%S"))
    return render(request, "pages/index.html", {"model": model})


# la misma plantilla con otro modelo; u otra plantilla, con el código 404
@require_GET
def hello(request, name):
    if name == "unknown":
        # status: el código de la respuesta
        return render(request, "pages/unknown.html", {"name": name}, status=404)
    model = PageModel(
        f"Hello {name}",
        "This time, the title of the page comes from the URL.",
        timezone.localtime().strftime("%H:%M:%S"))
    return render(request, "pages/index.html", {"model": model})
  • Líneas 16–20: la vista construye el modelo. [timezone.localtime()], del módulo [django.utils.timezone], devuelve la hora actual en la zona horaria de la aplicación (ajuste [TIME_ZONE], [Europe/Paris]); [strftime] le da formato: [%H] para las horas, [%M] para los minutos, [%S] para los segundos;
  • Línea 21: el atajo [render] (del módulo [django.shortcuts], ejemplo 04) hace que el motor de plantillas genere la página. Recibe la solicitud, el nombre de la plantilla (la ruta del archivo, relativa a una de las carpetas de plantillas) y el contexto: un diccionario en el que cada clave se convierte en una variable de la plantilla; en este caso, una sola: [model]. [render] devuelve un objeto [HttpResponse] cuyo cuerpo es la página generada (de tipo [text/html]);
  • líneas 27–29: otra plantilla, con una variable distinta ([name]). El parámetro [status] de [render] especifica el código de respuesta: en este caso, 404, para una página de error personalizada;
  • líneas 30–34: la misma plantilla que la de la vista [index], con un modelo distinto. Esta es la ventaja de separar las vistas de las plantillas: una misma plantilla puede usarse para varias vistas.

Las rutas ([pages/urls.py]) asocian [/] con la vista [index], y [/hello/<str:name>] con la vista [hello].

4.1.4. La plantilla: templates/pages/index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  {# {{ ... }}: el valor de una variable, insertado en la página #}
  <title>{{ model.title }}</title>
</head>
<body>
  <h1>{{ model.title }}</h1>
  <p>{{ model.message }}</p>
  <p>Page built at {{ model.time }}.</p>
</body>
</html>
  • línea 5: un comentario de DTL;
  • línea 6: [{{ model.title }}] inserta el valor del atributo [title] de la variable [model]. El punto es el operador de acceso de DTL, mientras que [Python] escribiría [model.title] o [model["title"]], según corresponda.

Todo lo que se inserta mediante [{{ }}] se escapa: los caracteres [<], [>], [&], ["] y ['] se reemplazan por sus entidades HTML. Este es el papel que desempeñaba la función [format_html] en el ejemplo 09, pero esta vez es automático: por lo tanto, una plantilla no puede insertar inadvertidamente en la página el HTML proporcionado por un usuario.

4.1.5. La plantilla: templates/pages/unknown.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [{{ name }}] here.</h1>
</body>
</html>

Una plantilla no tiene por qué aceptar un objeto: la variable [name] es una cadena.

4.1.6. Ejecución

Image

Image

La hora mostrada es la de la zona horaria de la aplicación. La respuesta sin procesar muestra cómo funciona el motor: las etiquetas [{{ }}] se han reemplazado por sus valores y el comentario ha desaparecido (dejando una línea vacía con su sangría).

curl -i http://localhost:8000/
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">

  <title>My first template</title>
</head>
<body>
  <h1>My first template</h1>
  <p>This page was built by Django, on the server.</p>
  <p>Page built at 19:28:44.</p>
</body>
</html>

La página de error «personalizada», seguida de un nombre que contiene HTML y un apóstrofo ([<b>martin'], codificado como URL):

curl -i http://localhost:8000/hello/unknown
curl "http://localhost:8000/hello/%3Cb%3Emartin'"
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [unknown] here.</h1>
</body>
</html>
<!doctype html>
...
  <title>Hello &lt;b&gt;martin&#x27;</title>
</head>
<body>
  <h1>Hello &lt;b&gt;martin&#x27;</h1>
  <p>This time, the title of the page comes from the URL.</p>
...

La etiqueta [<b>] se escapó, sin que la vista ni la plantilla tuvieran que hacer nada (el apóstrofo también se escapó: [&#x27;]). Por último, así es la plantilla tal como [Django] la almacena en memoria. El comando [python manage.py shell] abre una consola [Python] en la que [Django] está listo; la opción [-c] hace que ejecute unas cuantas instrucciones:

python manage.py shell -c "from django.template.loader import get_template; print(*get_template('pages/index.html').template.nodelist, sep='\n')"
<TextNode: '<!doctype html>\n<html lan'>
<TextNode: '\n  <title>'>
<Variable Node: model.title>
<TextNode: '</title>\n</head>\n<body>\n '>
<Variable Node: model.title>
<TextNode: '</h1>\n  <p>'>
<Variable Node: model.message>
<TextNode: '</p>\n  <p>Page built at '>
<Variable Node: model.time>
<TextNode: '.</p>\n</body>\n</html>\n'>

La plantilla se ha convertido en una lista de nodos: fragmentos de texto ([TextNode], cuya visualización se trunca), copiados tal cual, y variables ([VariableNode]), cuyos valores se buscan en el contexto y luego se escapan. El comentario no dejó ningún nodo. Generar la página consiste en recorrer esta lista y reensamblar los fragmentos de texto. Por lo tanto, una plantilla es simplemente una forma más segura y legible de escribir una función [Python] que genera HTML.

4.2. Ejemplo 14: el lenguaje de plantillas

Este ejemplo combina las principales construcciones de DTL en una sola plantilla.

4.2.1. El modelo y la vista

El modelo de la plantilla se describe mediante tres clases de datos inmutables:

# basics/viewmodels.py: el modelo de la plantilla del ejemplo 14

from dataclasses import dataclass


@dataclass(frozen=True)
class Address:
    street: str
    city: str


@dataclass(frozen=True)
class Product:
    name: str
    price: float
    in_stock: bool


@dataclass(frozen=True)
class BasicsModel:
    title: str
    name: str
    # str | None: una cadena, o None
    nickname: str | None
    html: str
    logged_in: bool
    currency: str
    products: list[Product]
    cart: list[Product]
    address: Address

    # @property: un método que se lee como un atributo (model.total). El
    # lenguaje de plantillas no puede calcular: los cálculos se hacen en Python
    @property
    def total(self) -> float:
        return sum(p.price for p in self.products)

    @property
    def average_price(self) -> float:
        return self.total / len(self.products)
  • línea 24: [str | None]: una cadena, o [None] (ejemplo 06);
  • líneas 28–29: listas de objetos [Product];
  • líneas 34–40: como DTL no puede realizar cálculos, los cálculos que necesita la plantilla (precio total, precio promedio) son métodos del modelo. El decorador [@property] convierte un método en una propiedad: se lee como un atributo, sin paréntesis ([model.total]), y así es como DTL la verá. Por simplicidad, aquí los precios son de tipo [float] (el ejemplo 06 mostró por qué preferimos los centavos enteros).

El modelo contiene valores de diversos tipos: cadenas, [None], booleanos, listas de objetos, listas vacías y objetos que contienen otros objetos.

# basics/views.py: una plantilla que usa las principales construcciones del lenguaje de Django

from django.shortcuts import render
from django.views.decorators.http import require_GET

from .viewmodels import Address, BasicsModel, Product


@require_GET
def index(request):
    # argumentos NOMBRADOS: cada valor se asocia con un atributo por su nombre
    model = BasicsModel(
        title="Template basics",
        name="Martin",
        nickname=None,
        html="<b>this is HTML</b>",
        logged_in=True,
        currency="€",
        products=[
            Product("Keyboard", 25, True),
            Product("Mouse", 12.5, False),
            Product("Screen", 149, True),
        ],
        cart=[],
        address=Address("12 rue des Lilas", "Angers"))
    return render(request, "basics/index.html", {"model": model})

La vista construye el modelo usando parámetros con nombre (véase el ejemplo 02): cada valor está precedido por el nombre del atributo al que está destinado, lo que hace legible la llamada a pesar del número de parámetros.

4.2.2. La plantilla: templates/basics/index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{ model.title }}</title>
</head>
<body>
  <h1>{{ model.title }}</h1>
  {% comment %}
    1. muestra un valor del modelo; None se muestra... None; el filtro default
    reemplaza un valor vacío (None, "", 0, lista vacía...). Un comentario {# #} cabe
    en una sola línea; este, en varias, se escribe entre comment y endcomment
  {% endcomment %}
  <p>1. Name: {{ model.name }} - nickname: [{{ model.nickname }}] [{{ model.nickname|default:"none" }}]</p>
  {# 2. {{ }} escapa el HTML; el filtro safe lo inserta tal cual #}
  <p>2a. {{ model.html }}</p>
  <p>2b. {{ model.html|safe }}</p>
  {# 3. una condición #}
  {% if model.logged_in %}
    <p>3. You are logged in.</p>
  {% else %}
    <p>3. You are not logged in.</p>
  {% endif %}
  {# 4. un bucle: la variable forloop describe el estado del bucle #}
  <p>4. Our products:</p>
  <ul>
    {% for product in model.products %}
      <li>no. {{ forloop.counter0 }}: {{ product.name }}, {{ product.price }} {{ model.currency }}
        {{ product.in_stock|yesno:"(in stock),(sold out)" }}
        {% if forloop.first %} - the first{% endif %}
        {% if forloop.last %} - the last, seen by {{ model.name }}{% endif %}
      </li>
    {% endfor %}
  </ul>
  {# 5. la lista vacía: el bloque empty de un bucle for #}
  <p>5. Your cart:
    {% for p in model.cart %}<span>{{ p.name }}</span>{% empty %} it is empty.{% endfor %}
  </p>
  {% comment %}
    6. with: una variable de plantilla; el filtro length cuenta los productos;
    floatformat redondea y escribe el número según el idioma (configuración LANGUAGE_CODE)
  {% endcomment %}
  {% with count=model.products|length %}
    <p>6. {{ count }} products, for a total of {{ model.total }} {{ model.currency }};
      average price: {{ model.average_price|floatformat:2 }} {{ model.currency }}</p>
  {% endwith %}
  {# 7. un objeto dentro de un objeto, y un filtro que convierte a mayúsculas #}
  <p>7. Address: {{ model.address.street }}, {{ model.address.city|upper }}</p>
  {# 8. verbatim: un texto que Django copia sin interpretarlo #}
  <p>8. Braces displayed as they are: {% verbatim %}{{ model.name }}{% endverbatim %}</p>
</body>
</html>
  • Líneas 9–13: un comentario de varias líneas;
  • línea 14: se muestra un valor [None] ... [None]: esta es la representación en texto de [None]. El filtro [default] reemplaza un valor «vacío» ([None], cadena vacía, 0, lista vacía...) por un valor predeterminado. Un filtro se aplica mediante una barra vertical y puede recibir un parámetro opcional después de dos puntos: [value|filter:"parameter"]. Una variable que no existe en absoluto en el contexto ([model.unknown]) se mostraría como una cadena vacía, sin error;
  • líneas 16–17: [{{ }}] escapa el HTML (2a); el filtro [safe], en cambio, inserta el valor tal cual, sin escapar (2b). [safe] está reservado para el HTML generado por la propia aplicación, nunca para datos ingresados por el usuario. La etiqueta [{% autoescape off %}] desactiva el escape en toda una sección de la plantilla;
  • líneas 19–23: una condición: [{% if %}], [{% elif %}], [{% else %}], [{% endif %}]. Cada bloque se cierra con una etiqueta [{% end... %}]. Una condición puede usar los operadores [==], [!=], [<], [>], [<=], [>=], [in], [not], [and], [or];
  • líneas 27–33: un bucle [{% for ... in ... %}] ... [{% endfor %}]. Dentro del bucle, la variable especial [forloop] describe el estado del bucle: [forloop.counter0] (el número de iteración, comenzando en 0), [forloop.counter] (comenzando en 1), [forloop.first], [forloop.last] (verdadero en la primera y la última iteración, respectivamente), [forloop.revcounter] (el número de iteraciones restantes). Las variables externas al bucle ([model.name], [model.currency]) siguen siendo accesibles;
  • Línea 29: el filtro [yesno] selecciona un texto según si un valor es verdadero o falso: sus dos textos (un tercer texto opcional se usaría para [None]) se separan con una coma. Es el equivalente, en DTL, de una expresión condicional;
  • línea 37: un bucle [for] puede tener un bloque [{% empty %}], que se ejecuta si la lista está vacía. Esto es más sencillo que un [{% if %}] que verificara la longitud de la lista;
  • Líneas 43–46: la etiqueta [{% with %}] crea una variable que es válida hasta [{% endwith %}]: en este caso, el número de productos, calculado por el filtro [length] (el número de elementos de una lista o de caracteres de una cadena);
  • Líneas 44–45: las propiedades calculadas del modelo. El filtro [floatformat] redondea un número ([floatformat:2]) a dos decimales. Da formato al número según las convenciones del idioma de la aplicación ([LANGUAGE_CODE]): el separador decimal se formatea para inglés. Todos los números insertados en una página se formatean de esta manera: [Django] da formato a números y fechas según el idioma activo (en francés, [12.5] pasaría a ser [12,5]);
  • línea 48: el punto atraviesa objetos ([model.address.city]), y el filtro [upper] pone una cadena en mayúsculas (manejando correctamente los caracteres acentuados);
  • línea 50: la etiqueta [{% verbatim %}] copia su contenido sin interpretarlo: es útil cuando una página contiene llaves destinadas a un framework de [JavaScript].

DTL tiene unos sesenta filtros ([lower], [capfirst], [title], [truncatechars], [join], [slice], [first], [last], [date], [time], [linebreaks], [urlize], [pluralize], [add], [divisibleby], [escape], [json_script]...) y unas treinta etiquetas ([if], [for], [with], [url], [now], [cycle], [firstof], [include], [extends], [block], [load], [csrf_token], [spaceless]...); las aplicaciones de [Django] agregan más ([static], [translate]...), y la aplicación puede escribir las suyas (ejemplo 16).

4.2.3. Ejecución

Image

La página generada:

curl http://localhost:8000/
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Template basics</title>
</head>
<body>
  <h1>Template basics</h1>

  <p>1. Name: Martin - nickname: [None] [none]</p>

  <p>2a. &lt;b&gt;this is HTML&lt;/b&gt;</p>
  <p>2b. <b>this is HTML</b></p>


    <p>3. You are logged in.</p>


  <p>4. Our products:</p>
  <ul>

      <li>no. 0: Keyboard, 25 €
        (in stock)
         - the first

      </li>

      <li>no. 1: Mouse, 12.5 €
        (sold out)
...
  <p>5. Your cart:
     it is empty.
  </p>


    <p>6. 3 products, for a total of 186.5 €;
      average price: 62.17 €</p>


  <p>7. Address: 12 rue des Lilas, ANGERS</p>

  <p>8. Braces displayed as they are: {{ model.name }}</p>
</body>
</html>

Los comentarios y las etiquetas han desaparecido, pero dejan tras de sí sus espacios y saltos de línea: [Django] no elimina ningún espacio en blanco. Esto no tiene ningún efecto: el navegador ignora estos espacios en blanco. (La etiqueta [{% spaceless %}] eliminaría el espacio en blanco entre las etiquetas HTML en una sección de la plantilla). Los números se han escrito al estilo inglés ([12.5], [186.5]), aunque la plantilla no lo exigía.

4.3. Ejemplo 15: plantilla padre, fragmentos, archivos estáticos

Las páginas de un sitio web suelen compartir la misma estructura: un encabezado, una barra de navegación, un pie de página y las mismas hojas de estilo. En lugar de repetir esta estructura en cada plantilla, se escribe una sola vez en una plantilla padre (también llamada layout), que las páginas extienden. Este ejemplo también usa [Bootstrap], el framework CSS más utilizado, para el diseño de la página.

15-layout/
├── config/
│   ├── contexts.py
│   ├── settings.py
│   └── ...
├── pages/
│   ├── __init__.py
│   ├── viewmodels.py
│   └── views.py
├── static/
│   └── css/
│       └── styles.css
├── templates/
│   ├── fragments/
│   │   └── navbar.html
│   ├── pages/
│   │   ├── home.html
│   │   ├── raw.html
│   │   └── team.html
│   ├── layout.html
│   └── macros.html
└── manage.py

4.3.1. Archivos estáticos

Una página HTML hace referencia a otros archivos: hojas de estilo, scripts de [JavaScript] e imágenes. Estos archivos, que el servidor envía tal cual, se denominan archivos estáticos. Con [Django], se almacenan en carpetas [static] (la carpeta del proyecto y las carpetas de las aplicaciones), y la aplicación [django.contrib.staticfiles] los gestiona. La configuración:

# config/settings.py: la configuración del ejemplo 15

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-u0g1t-=6%v^*y#i*czmc@ge#-yk6m!jj13lte=0yw_pa6y+2m4"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

INSTALLED_APPS = [
    # la aplicación de Django que administra los archivos ESTÁTICOS (hojas de estilo,
    # imágenes, scripts): la etiqueta {% static %} y su servicio por runserver
    "django.contrib.staticfiles",
    "pages",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "OPTIONS": {
            # los PROCESADORES DE CONTEXTO: funciones que añaden variables al
            # contexto de TODAS las plantillas; request: la solicitud actual
            "context_processors": [
                "django.template.context_processors.request",
                "config.contexts.site",
            ],
        },
    },
]

# la URL de los archivos estáticos: {% static 'css/styles.css' %} -> /static/css/styles.css
STATIC_URL = "static/"
# las carpetas donde Django busca los archivos estáticos: la del ejemplo y
# la de Bootstrap, compartida por los ejemplos 15 a 28
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]
  • líneas 14–19: la aplicación [django.contrib.staticfiles], una de las aplicaciones incluidas con [Django];
  • líneas 21–34: el motor de plantillas, con dos procesadores de contexto, que se describen más adelante;
  • línea 37: [STATIC_URL], el prefijo de la URL de los archivos estáticos: el archivo [css/styles.css] estará disponible en la URL [/static/css/styles.css];
  • Líneas 40–43: [STATICFILES_DIRS], la lista de carpetas de archivos estáticos del proyecto (además de las carpetas [static] de las aplicaciones). La primera es la del ejemplo. La segunda es la carpeta [examples/common/static], que contiene [Bootstrap]: en lugar de incluir una copia en cada ejemplo, los ejemplos 15 a 28 la comparten (véase la introducción). [Django] busca un archivo en todas estas carpetas, en orden, y devuelve el primero que encuentra.

En modo de depuración, el servidor de desarrollo sirve él mismo los archivos estáticos, mediante la aplicación [staticfiles]: una URL que comienza con [/static/] no la gestionan las rutas de la aplicación, sino el controlador de archivos estáticos. En producción ([DEBUG = False]), ya no lo hace: esa no es la función de una aplicación [Python]. El comando [python manage.py collectstatic] copia entonces todos los archivos estáticos del proyecto y de las aplicaciones en una única carpeta (el ajuste [STATIC_ROOT]), que el servidor web ([nginx], [Apache]...) sirve directamente, o que sirve una biblioteca como [WhiteNoise] (véase el caso de estudio).

/* algunos ajustes además de Bootstrap */
body {
  background-color: #f5f7fa;
}

/* el pie de página del diseño base */
.footer {
  margin-top: 2rem;
  font-size: 0.85rem;
  color: #6c757d;
}

/* los mensajes de error, al final de la página, sobre un fondo rosa claro */
.error-area {
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef;
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

Unas pocas reglas CSS adicionales además de [Bootstrap]: un fondo gris claro, el estilo del pie de página y el estilo de un área de error que se usará en los ejemplos siguientes.

4.3.2. La plantilla padre: templates/layout.html

<!doctype html>
{# la plantilla PADRE de las páginas: las páginas la EXTIENDEN y rellenan sus bloques #}
{% load static %}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# block: un espacio que la página puede rellenar; aquí con un contenido predeterminado #}
  <title>{% block title %}Home{% endblock %} - {{ site_name }}</title>
  {# static: la URL de un archivo estático #}
  <link rel="stylesheet" href="{% static 'bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-3">
    {# inserción de la plantilla fragments/navbar.html #}
    {% include "fragments/navbar.html" %}
    <main>
      {# aquí se inserta el contenido de la página solicitada por la vista #}
      {% block content %}{% endblock %}
    </main>
    {# request: la solicitud actual; site_name: una variable global (ver config/contexts.py) #}
    <footer class="footer">Page [{{ request.path }}] - © {% now "Y" %} {{ site_name }}</footer>
  </div>
</body>
</html>
  • Línea 3: [{% load static %}] carga una biblioteca de etiquetas: la de la aplicación [staticfiles], que proporciona la etiqueta [{% static %}]. Las etiquetas y los filtros que no forman parte del núcleo de DTL se almacenan en bibliotecas, que una plantilla debe cargar antes de usarlos;
  • línea 7: la etiqueta [viewport] indica a los navegadores móviles que muestren la página con el ancho de la pantalla, que es lo que [Bootstrap] espera;
  • línea 9: la etiqueta [{% block %}] marca un espacio con nombre, que las páginas que extienden la plantilla pueden llenar definiendo un bloque con el mismo nombre. El contenido escrito entre [{% block title %}] y [{% endblock %}] es el contenido predeterminado del marcador de posición, que usa una página que no define este bloque. [site_name] es una variable global presente en todas las plantillas (véase [config/contexts.py], más abajo);
  • Líneas 11–12: [{% static 'path' %}] genera la URL de un archivo estático: [STATIC_URL] seguida de la ruta. Escribir a mano la URL de los archivos ([/static/css/styles.css]) también funcionaría, pero [{% static %}] se adapta si se cambia [STATIC_URL] (para servir los archivos desde otro sitio, por ejemplo), o si se agrega un hash de su contenido a los nombres de archivo para fines de caché (caso de estudio);
  • línea 17: [{% include %}] inserta el contenido de otra plantilla, en este caso la barra de navegación. La plantilla incluida ve las variables de la plantilla que la incluye;
  • línea 20: el marcador de posición que cada página llena con su propio contenido;
  • línea 23: la variable [request] es la solicitud actual ([request.path]: la ruta de la URL solicitada). Está presente en todas las plantillas gracias al procesador de contexto [request] (véase más abajo). La etiqueta [{% now "Y" %}] escribe la fecha actual en el siguiente formato: [Y], con el año en cuatro dígitos.

La clase [container] de [Bootstrap] centra el contenido y limita su ancho; [py-3] agrega relleno vertical: [Bootstrap] proporciona cientos de clases de este tipo, que se combinan en el atributo [class].

4.3.3. Variables globales: config/contexts.py

1
2
3
4
5
6
7
# config/contexts.py: un procesador de contexto

# Django lo llama por cada plantilla renderizada con la solicitud (render(request, ...));
# el diccionario que devuelve se añade al contexto: site_name es una variable GLOBAL,
# presente en todas las plantillas
def site(request):
    return {"site_name": "My site"}

Un procesador de contexto es una función que recibe la solicitud y devuelve un diccionario de variables que se agregan al contexto de todas las plantillas. [Django] llama a los procesadores del ajuste [context_processors] (líneas 28–31 del archivo [config/settings.py]) cada vez que se genera una plantilla con la solicitud (como ocurre con [render(request, ...)]). El procesador [django.template.context_processors.request], incluido con [Django], agrega la variable [request]; el nuestro agrega [site_name]. Otras aplicaciones de [Django] proporcionan los suyos: mensajes (ejemplo 20), idioma (ejemplo 22)... Un procesador se llama por cada plantilla generada: debe ser rápido.

4.3.4. La barra de navegación: templates/fragments/navbar.html

{# un fragmento: una pieza de página, insertada con include #}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">{{ site_name }}</span>
  <div class="navbar-nav">
    {# url: la URL de una ruta, designada por su nombre #}
    <a class="nav-link" href="{% url 'home' %}">Home</a>
    <a class="nav-link" href="{% url 'team' %}">Team</a>
    <a class="nav-link" href="{% url 'raw' %}">Page without parent template</a>
  </div>
</nav>

Un fragmento: una pieza de una página que no tiene sentido por sí sola. Las clases [navbar], [navbar-brand] y [nav-link] son las de la barra de navegación de [Bootstrap]. Los enlaces los genera la etiqueta [{% url %}] (línea 6), a partir de los nombres de las rutas (ejemplo 04): [{% url 'team' %}] produce [/team]. Los parámetros de la ruta siguen al nombre: [{% url 'contacts_details' contact.id %}] (ejemplo 21).

4.3.5. Fragmentos con nombre: templates/macros.html

{# FRAGMENTOS CON NOMBRE (partialdef): piezas de página reutilizables, almacenadas en un mismo archivo #}

{# una tarjeta (card) de Bootstrap, con un nombre y un rol #}
{% partialdef card %}
  <div class="card">
    <div class="card-body">
      <h5 class="card-title">{{ name }}</h5>
      <p class="card-text">{{ role }}</p>
    </div>
  </div>
{% endpartialdef %}
  • líneas 4–11: la etiqueta [{% partialdef %}], introducida con [Django] 6.0, define un fragmento con nombre (partial): una porción de una plantilla, en este caso una tarjeta ([card]) de [Bootstrap]. Un archivo puede contener varios. Definido de esta manera, el fragmento no se muestra donde está escrito: se muestra en otro lugar, mediante [{% include "macros.html#card" %}] (el nombre del archivo, un símbolo de numeral, el nombre del fragmento) o, dentro del mismo archivo, mediante [{% partial card %}]. El fragmento muestra dos variables, [name] y [role], que se le proporcionarán al incluirlo.

Los estudiantes del curso de [Symfony] reconocerán cómo ese curso usaba las macros de [Twig]. Hay una diferencia: una macro de [Twig] solo podía ver sus propios parámetros; un fragmento incluido puede ver todas las variables de la plantilla que lo incluye, además de las que se le pasan. La palabra clave [only] ([{% include "..." with name="..." only %}]) lo restringe a estas últimas. Para un componente más complejo que requiera código [Python], se escribe una etiqueta de inclusión (ejemplo 16).

4.3.6. Las páginas

{# esta página EXTIENDE la plantilla padre: solo aporta el contenido de sus bloques #}
{% extends "layout.html" %}

{% block content %}
  <h1>Welcome</h1>
  <p>This page only contains its own content: the header, the navigation
    bar and the footer come from the parent template <code>layout.html</code>.</p>
  {# el fragmento [card] del archivo macros.html, con dos variables escritas en el lugar #}
  {% include "macros.html#card" with name="A fragment" role="included with variables written in place" %}
{% endblock %}
  • Línea 2: la página extiende la plantilla padre: [Django] genera la página padre, reemplazando sus bloques por los que define la página. [{% extends %}] debe ser la primera etiqueta de la plantilla (solo un comentario [{# #}] puede precederla). En una plantilla que extiende otra, todo el contenido debe estar dentro de bloques: el texto escrito fuera de los bloques no aparece en la página generada;
  • líneas 4–10: el bloque [content], que llena el espacio del mismo nombre. La página no define el bloque [title]: el espacio conserva su contenido predeterminado, «Home»;
  • línea 9: la inclusión del fragmento [card], con dos variables especificadas después de la palabra clave [with]. El HTML del fragmento no se escapa por segunda vez: [Django] sabe que ya es HTML seguro (las variables, sin embargo, se escaparon dentro del fragmento).
{% extends "layout.html" %}

{% block title %}Our team{% endblock %}

{% block content %}
  <h1>Our team</h1>
  <div class="row g-3">
    {% for member in members %}
      <div class="col-md-4">
        {# las variables del fragmento son expresiones cualesquiera #}
        {% include "macros.html#card" with name=member.name role=member.role %}
      </div>
    {% endfor %}
  </div>
{% endblock %}
  • línea 3: el bloque [title], en una sola línea;
  • líneas 7–14: una tarjeta por cada miembro del equipo, en una cuadrícula de [Bootstrap] ([row], [col-md-4]: tres columnas en una pantalla mediana o grande, una columna en una pantalla estrecha);
  • línea 11: las variables que se pasan al fragmento pueden ser expresiones cualesquiera.

Un bloque del padre también puede complementarse en lugar de reemplazarse: [{{ block.super }}], escrito en el bloque de la página, inserta el contenido que tenía el bloque en el padre. Una plantilla puede extender una plantilla que a su vez extiende otra: la herencia tiene tantos niveles como sea necesario. La vista no contiene nada nuevo:

# pages/views.py: tres páginas

from django.shortcuts import render
from django.views.decorators.http import require_GET

from .viewmodels import Member


@require_GET
def home(request):
    return render(request, "pages/home.html")


@require_GET
def team(request):
    members = [
        Member("Marie Pélissier", "Director"),
        Member("Jacques Bromard", "Developer"),
        Member("Philippe Jandot", "Graphic designer"),
    ]
    return render(request, "pages/team.html", {"members": members})


@require_GET
def raw(request):
    return render(request, "pages/raw.html")

Por último, la tercera página no usa la plantilla padre:

<!doctype html>
{# esta plantilla no extiende la plantilla padre: es una página completa #}
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Raw page</title>
</head>
<body>
  <p>This page does not use the parent template: neither Bootstrap, nor navigation bar.</p>
  <p><a href="{% url 'home' %}">Back to the home page</a></p>
</body>
</html>

4.3.7. Ejecución

Image

Image

Image

Como la captura de pantalla es angosta, las tarjetas del equipo se apilan una debajo de otra. La página del equipo, tal como aparece en el navegador:

curl http://localhost:8000/team
<!doctype html>


<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <title>Our team - My site</title>

  <link rel="stylesheet" href="/static/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/static/css/styles.css">
</head>
<body>
  <div class="container py-3">


<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">My site</span>
  <div class="navbar-nav">

    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/team">Team</a>
    <a class="nav-link" href="/raw">Page without parent template</a>
  </div>
</nav>

    <main>


  <h1>Our team</h1>
  <div class="row g-3">

      <div class="col-md-4">


  <div class="card">
    <div class="card-body">
      <h5 class="card-title">Marie Pélissier</h5>
      <p class="card-text">Director</p>
    </div>
  </div>

      </div>
...
  </div>

    </main>

    <footer class="footer">Page [/team] - © 2026 My site</footer>
  </div>
</body>
</html>

El navegador recibió una página completa: la plantilla padre, el fragmento de la barra de navegación, la página y las tarjetas se ensamblaron en el servidor. Las URL de las hojas de estilo las calculó [{% static %}]: son URL específicas del sitio. Se puede verificar que las hojas de estilo se sirven correctamente (la opción [-I] de [curl] muestra solo los encabezados de la respuesta al enviar una solicitud HEAD):

curl -I http://localhost:8000/static/bootstrap/css/bootstrap.min.css
curl -I http://localhost:8000/static/css/styles.css
HTTP/1.1 200 OK
Content-Type: text/css
Content-Length: 232111
Content-Disposition: inline; filename="bootstrap.min.css"
Last-Modified: Sun, 27 Sep 2026 16:41:12 GMT

HTTP/1.1 200 OK
Content-Type: text/css
Content-Length: 435
Content-Disposition: inline; filename="styles.css"
Last-Modified: Sun, 27 Sep 2026 16:42:11 GMT

El primer archivo proviene de la carpeta [common/static], el segundo de la carpeta [static] del ejemplo: para el navegador, no hay diferencia entre ellos. El tipo de contenido se dedujo de la extensión del archivo ([text/css]): un navegador rechazará una hoja de estilo que se declare como otra cosa. Por último, un intento de acceder a las carpetas de archivos estáticos:

curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:8000/static/..%2F..%2Fconfig%2Fsettings.py"
500

(las opciones [-s -o /dev/null -w "%{http_code}\n"] muestran solo el código de respuesta; en [Windows], se muestra [-o NUL]). La opción de URL solicita el archivo [config/settings.py] del ejemplo, subiendo dos carpetas (los archivos [/] se codifican como [%2F], para que ni [curl] ni el navegador simplifiquen la ruta por su cuenta). [Django] falló: la consola muestra la excepción [SuspiciousFileOperation], con el mensaje «The joined path (...) is located outside of the base path component.» El código 500 indica una excepción no controlada; lo fundamental es que el archivo no se envió.

4.4. Ejemplo 16: ampliación del lenguaje de plantillas

Una plantilla suele necesitar dar formato a valores: un monto con su moneda, una fecha escrita completa o texto en mayúsculas. Este código no pertenece a la vista (que no se ocupa de la presentación), y DTL no permite escribirlo en la plantilla (véase la introducción de este capítulo). En cambio, se escribe en [Python], en una biblioteca de etiquetas y filtros: un módulo que agrega sus propios filtros y etiquetas al lenguaje de plantillas. Los componentes que generan fragmentos de HTML a partir de datos (las etiquetas de inclusión) también se escriben en [Python].

16-extensions/
├── config/
│   ├── middleware.py
│   ├── settings.py
│   └── ...
├── pages/
│   ├── templatetags/
│   │   ├── __init__.py
│   │   └── formats.py
│   ├── __init__.py
│   ├── viewmodels.py
│   └── views.py
├── static/
│   └── css/
│       └── styles.css
├── templates/
│   ├── fragments/
│   │   └── navbar.html
│   ├── pages/
│   │   ├── home.html
│   │   └── products.html
│   ├── tags/
│   │   ├── badge.html
│   │   └── link.html
│   └── layout.html
└── manage.py

4.4.1. La biblioteca: pages/templatetags/formats.py

Una biblioteca de etiquetas es un módulo contenido en el paquete [templatetags] de una aplicación (que debe declararse en [INSTALLED_APPS]); el nombre del módulo ([formats]) es el nombre que una plantilla asignará a [{% load formats %}]:

# pages/templatetags/formats.py: una BIBLIOTECA de extensiones del lenguaje de
# plantillas, cargada por {% load formats %}: dos filtros y dos etiquetas

from babel.dates import format_date
from babel.numbers import format_currency
from django import template
from django.utils.translation import get_language

# el objeto que registra los filtros y las etiquetas de la biblioteca
register = template.Library()


# un FILTRO: {{ product.price_cents|money }} o {{ ...|money:"USD" }}. Un
# monto en centavos, en una moneda, con el formato del idioma activo:
# 114990 -> "€1,149.90" en inglés, "1 149,90 €" en francés. La
# biblioteca Babel conoce las convenciones de cada país
@register.filter
def money(cents, currency="EUR"):
    return format_currency(cents / 100, currency, locale=get_language())


# una fecha en palabras completas, en el idioma activo: "Sunday, September 27, 2026"
@register.filter
def long_date(day):
    return format_date(day, format="full", locale=get_language())


# una ETIQUETA DE INCLUSIÓN: {% link 'products' '/products' 'Products' %} muestra la
# plantilla tags/link.html, con el contexto que devuelve la función.
# takes_context: la función también recibe el contexto de la plantilla que llama
@register.inclusion_tag("tags/link.html", takes_context=True)
def link(context, route, path, text):
    # un enlace de la barra de navegación, que recibe la clase [active] si la
    # página actual está bajo la ruta [path]
    active = context["request"].path.startswith(path)
    return {"route": route, "text": text, "active": active}


# un badge de Bootstrap: verde si el producto está en existencia, rojo en caso contrario
@register.inclusion_tag("tags/badge.html")
def badge(stock):
    return {"stock": stock}
  • líneas 4–5: dos funciones de la biblioteca [Babel] (véase la introducción), que conoce las convenciones de escritura de números, montos y fechas de todos los países (usa datos del proyecto Unicode CLDR);
  • línea 7: [get_language] obtiene el idioma activo para la consulta actual ([fr], [en]); veremos quién lo establece;
  • línea 10: el objeto [register], una [template.Library], almacena los filtros y las etiquetas del módulo. El nombre de la variable está fijo en el código: ahí es donde [Django] los busca;
  • Líneas 17–19: un filtro es una función, registrada por el decorador [@register.filter] con su propio nombre, [money]. Su primer parámetro es el valor filtrado; el segundo, opcional, es el parámetro del filtro en la plantilla ([price|money:"USD"]): aquí, la moneda, designada por su código internacional ([EUR], [USD]). El filtro da formato a un monto recibido en centavos (véase el ejemplo 06). El formato depende del idioma: en francés, [1 149,90 €] (espacio para separar los miles, coma decimal, símbolo de la moneda después del monto); en inglés, [€1,149.90];
  • líneas 23–25: formato de fechas: el formato [full] escribe la fecha completa, incluido el día de la semana ([Sunday, September 27, 2026]);
  • líneas 31–36: una etiqueta de inclusión, definida por [@register.inclusion_tag]: una función que calcula un contexto, y una plantilla (aquí, [tags/link.html]) que lo muestra. En una plantilla, [{% link 'products' '/products' 'Products' %}] llama a la función con estos tres parámetros y luego inserta la plantilla, construida con el diccionario que esta devolvió. Con [takes_context=True], la función recibe como primer parámetro el contexto de la plantilla que la llama: allí encuentra la consulta y determina si el enlace apunta a la página actual ([startswith] verifica el inicio de una cadena);
  • líneas 40–42: una segunda etiqueta de inclusión, sin el contexto: una insignia.

Una biblioteca también puede proporcionar etiquetas «simples» ([@register.simple_tag]), que devuelven un valor, y etiquetas completas, que analizan su propio contenido (como [{% if %}]): esto es menos común. Las plantillas de las dos etiquetas de inclusión:

<a class="nav-link{% if active %} active{% endif %}" href="{% url route %}">{{ text }}</a>
{% if stock > 0 %}<span class="badge text-bg-success">{{ stock }} in stock</span>{% else %}<span class="badge text-bg-danger">sold out</span>{% endif %}

Al enlace de la página actual se le asigna la clase [active] de [Bootstrap], que lo resalta. [{% url route %}] genera la URL de una ruta cuyo nombre está almacenado en una variable. La insignia es verde ([text-bg-success]) o roja ([text-bg-danger]) según el inventario. El paquete [templatetags] también tiene su archivo [__init__.py]; sin él, no sería un paquete.

4.4.2. El idioma de cada solicitud: config/middleware.py

# config/middleware.py: el idioma de cada solicitud

from django.utils import translation


class SetLanguage:
    def __init__(self, get_response):
        self.get_response = get_response

    # el parámetro ?lang=fr de la URL, inglés en caso contrario
    def __call__(self, request):
        language = "fr" if request.GET.get("lang") == "fr" else "en"
        # activate: el idioma ACTIVO, que Django usa para dar formato a los
        # los números y las fechas, y para traducir sus mensajes
        translation.activate(language)
        return self.get_response(request)

Cada solicitud tiene un idioma activo, que, por defecto, es el especificado en el ajuste [LANGUAGE_CODE]. Aquí, el parámetro [?lang=fr] de la URL selecciona el francés; el inglés es el idioma predeterminado. Un componente de middleware (ejemplo 03) lo establece antes de cada vista mediante la función [translation.activate]: es el idioma que [get_language] devolverá, el idioma en el que [Django] da formato a números y fechas y traduce sus propios mensajes (como los mensajes de error de los formularios). El idioma activo es específico del hilo de ejecución que atiende la solicitud: dos solicitudes simultáneas pueden tener idiomas distintos. No se restablece de una solicitud a la siguiente; por eso el middleware lo establece en cada solicitud, incluso para el inglés. El capítulo sobre internacionalización reemplazará este middleware por el de [Django] y [LocaleMiddleware], y usará este mismo idioma para traducir el texto.

4.4.3. Configuración: config/settings.py

# config/settings.py: la configuración del ejemplo 16

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-yw&p(@e00b!)6xtfnoy-goyep6e*8jhvk_o0aj8a&pizr94xrq"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

# los idiomas de la aplicación
LANGUAGES = [
    ("fr", "Français"),
    ("en", "English"),
]

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    # la aplicación pages contiene una carpeta templatetags: sus extensiones del
    # lenguaje de plantillas están disponibles mediante {% load formats %}
    "pages",
]

MIDDLEWARE = [
    "config.middleware.SetLanguage",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.request",
            ],
        },
    },
]

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]
  • líneas 15–18: los idiomas de la aplicación;
  • líneas 20–25: la aplicación [pages] debe declararse; [Django] busca los paquetes [templatetags] dentro de las aplicaciones de [INSTALLED_APPS];
  • Líneas 27–29: el middleware de idioma.

4.4.4. La vista: pages/views.py

# pages/views.py: dos páginas

from datetime import date

from django.shortcuts import render
from django.views.decorators.http import require_GET

from .viewmodels import Product


@require_GET
def home(request):
    return render(request, "pages/home.html", {"today": date.today()})


@require_GET
def products(request):
    items = [
        Product("keyboard", 2500, 12),
        Product("mouse", 1250, 0),
        Product("screen", 114990, 3),
    ]
    # el cálculo se hace aquí, en Python: la plantilla solo tiene que mostrarlo
    total = sum(p.price_cents * p.stock for p in items)
    return render(request, "pages/products.html", {"products": items, "stock_total": total})

Las vistas pasan valores sin procesar a las plantillas: una fecha ([date.today()], la fecha de hoy) y montos en centavos. Las plantillas se encargan del formato. En cambio, el inventario total es un cálculo: se calcula en [Python] (línea 24), ya que DTL no puede realizar cálculos. La clase [Product] combina un nombre, un precio (en centavos; véase el ejemplo 06) y una cantidad en existencia.

4.4.5. Las plantillas

{% load formats %}
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">Extensions</span>
  <div class="navbar-nav">
    {# 1. una condición escrita en la plantilla; resolver_match: la ruta de la solicitud actual #}
    <a class="nav-link{% if request.resolver_match.url_name == 'home' %} active{% endif %}" href="{% url 'home' %}">Home</a>
    {# 2. nuestra etiqueta [link] #}
    {% link 'products' '/products' 'Products' %}
    {# 3. url construye la ruta de una ruta; los parámetros de la URL se agregan a mano #}
    <a class="nav-link" href="{% url 'products' %}?lang=fr">Produits (fr)</a>
  </div>
</nav>
  • línea 1: el fragmento carga por sí mismo la biblioteca que necesita: las bibliotecas de [{% load %}] no se transmiten a las plantillas incluidas ni a las plantillas que extienden un padre. Cada plantilla carga sus propias bibliotecas;
  • línea 6: lo mismo que con la etiqueta [link], escrito directamente en la plantilla, con una condición. [request.resolver_match] describe el resultado del enrutamiento de la solicitud actual: [url_name] es el nombre de la ruta. La etiqueta evita tener que repetir la condición en cada enlace;
  • línea 8: la llamada a la etiqueta, con sus tres parámetros, separados por espacios;
  • línea 10: [{% url %}] solo genera la ruta: los parámetros de la URL se agregan manualmente ([?lang=fr]).
{% extends "layout.html" %}
{% load i18n formats %}
{% block title %}Home{% endblock %}

{% block content %}
  <h1>Home</h1>
  {# nuestro filtro long_date #}
  <p>Today is {{ today|long_date }}.</p>
  {# el idioma activo, establecido por el middleware SetLanguage #}
  {% get_current_language as language %}
  <p>Formatting language: {{ language }}
    (<a href="{% url 'home' %}?lang=fr">in French</a>, <a href="{% url 'home' %}">in English</a>)</p>
{% endblock %}
  • Línea 2: la página carga dos bibliotecas: [i18n], la biblioteca de internacionalización de [Django], y la nuestra;
  • línea 8: nuestro filtro [long_date];
  • Líneas 10–11: la etiqueta [{% get_current_language as language %}], de la biblioteca [i18n], guarda el idioma activo en una variable de la plantilla.
{% extends "layout.html" %}
{% load formats %}
{% block title %}Products{% endblock %}

{% block content %}
  <h1>Products</h1>
  <table class="table table-sm w-auto">
    <thead><tr><th>Product</th><th>Price</th><th>Price in dollars</th><th>Stock</th></tr></thead>
    <tbody>
      {% for product in products %}
        <tr>
          {# un filtro de Django (upper), luego nuestro filtro money, sin y luego con parámetro #}
          <td>{{ product.name|upper }}</td>
          <td>{{ product.price_cents|money }}</td>
          <td>{{ product.price_cents|money:"USD" }}</td>
          {# nuestra etiqueta [badge] construye el HTML de la insignia #}
          <td>{% badge product.stock %}</td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
  <p>Stock total: {{ stock_total|money }}</p>
{% endblock %}
  • línea 13: un filtro de [Django];
  • líneas 14–15: nuestro filtro [money], primero con su moneda predeterminada y luego con un parámetro;
  • línea 17: la llamada a la etiqueta [badge];
  • línea 22: el inventario total, calculado por la vista.

La plantilla padre [layout.html] es una versión simplificada de la del ejemplo 15; su atributo [lang] recibe el idioma activo ([<html lang="{{ language }}">], después de [{% get_current_language as language %}]).

4.4.6. Ejecución

Image

Image

La misma página, con el parámetro [?lang=fr]. Solo cambia el formato de los números: el texto en sí está fijo en las plantillas. El capítulo sobre internacionalización también traducirá el texto.

Image

Un extracto del HTML generado:

curl "http://localhost:8000/products?lang=fr"
...
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link active" href="/products">Products</a>
    <a class="nav-link" href="/products?lang=fr">Produits (fr)</a>
...
        <tr>
          <td>SCREEN</td>
          <td>1 149,90 €</td>
          <td>1 149,90 $US</td>
          <td><span class="badge text-bg-success">3 in stock</span>
</td>
        </tr>
...

4.5. Ejemplo 17: un formulario GET

Un formulario HTML envía sus campos al servidor de una de dos maneras, según su atributo [method]:

  • [method="get"]: los campos se agregan a la URL como parámetros ([/search?keyword=le&genre=novel]). Es el método que usa un formulario que realiza una consulta: una búsqueda o un filtro. La URL que contiene los resultados se puede guardar como marcador, compartir o recargar sin riesgo;
  • [method="post"]: los campos se incluyen en el cuerpo de la solicitud (véase el ejemplo 11). Es el método que usa un formulario que modifica datos: un registro, una adición o una eliminación.

Este primer formulario es una búsqueda de libros. Está escrito a mano en HTML dentro de la plantilla: los ejemplos siguientes usarán las plantillas de formularios de [Django].

4.5.1. La plantilla: books/viewmodels.py

# books/viewmodels.py: un libro y el modelo de la plantilla de búsqueda

from dataclasses import dataclass


@dataclass(frozen=True)
class Book:
    title: str
    author: str
    genre: str


# el modelo de la plantilla: la entrada (para mostrarla de nuevo), los géneros, los resultados
@dataclass(frozen=True)
class SearchModel:
    keyword: str
    genre: str
    genres: list[str]
    results: list[Book]
  • Líneas 14–19: el modelo contiene lo que ingresó el usuario, que el formulario mostrará, la lista de géneros sugeridos y los resultados.

4.5.2. La vista: books/views.py

# books/views.py: un formulario de búsqueda, enviado por GET

from django.shortcuts import render
from django.views.decorators.http import require_GET

from .viewmodels import Book, SearchModel

# CONSTANTES del módulo: los datos, escritos en el código para el ejemplo
GENRES = ["novel", "poetry", "drama"]
BOOKS = [
    Book("Le Rouge et le Noir", "Stendhal", "novel"),
    Book("Les Fleurs du mal", "Baudelaire", "poetry"),
    Book("Madame Bovary", "Flaubert", "novel"),
    Book("Alcools", "Apollinaire", "poetry"),
    Book("Le Cid", "Corneille", "drama"),
]


# GET / y GET /search?keyword=...&genre=...: el formulario Y sus resultados
@require_GET
def search(request):
    keyword = request.GET.get("keyword", "")
    genre = request.GET.get("genre", "")
    word = keyword.lower()
    # una COMPRENSIÓN de lista: los libros que cumplen la condición
    results = [book for book in BOOKS
               if (word == "" or word in book.title.lower() or word in book.author.lower())
               and (genre == "" or book.genre == genre)]
    return render(request, "books/search.html", {
        "model": SearchModel(keyword, genre, GENRES, results),
    })
  • líneas 9–16: dos constantes del módulo: la lista de géneros y la lista de libros. En una aplicación real, provendrían de una base de datos;
  • líneas 20–21: una sola vista referenciada por dos rutas ([config/urls.py]: [""] y ["search"], llamadas [books_home] y [books_search]). En la primera visita ([/]), no hay parámetros y se muestran todos los libros;
  • líneas 22–23: los campos del formulario se leen como parámetros de la URL (ejemplo 07), con una cadena vacía como valor predeterminado;
  • líneas 24–28: el filtrado, mediante una comprensión de lista con una condición ([if]): se selecciona un libro si la palabra clave está vacía o aparece en su título o autor (en minúsculas en ambos lados: [lower()] maneja correctamente los caracteres acentuados), y si el género está vacío o coincide con el género del libro. Una condición puede abarcar varias líneas, entre paréntesis;
  • líneas 29–31: la plantilla.

4.5.3. La plantilla: templates/books/search.html

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Book search</h1>
  {# method="get": los campos se envían en la URL (?keyword=...&genre=...) #}
  <form method="get" action="{% url 'books_search' %}" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="keyword">Title or author</label>
      {# value: el campo vuelve a mostrar lo que se escribió (escapado por {{ }}) #}
      <input class="form-control" id="keyword" name="keyword" value="{{ model.keyword }}">
    </div>
    <div class="col-auto">
      <label class="form-label" for="genre">Genre</label>
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>
        {% for genre in model.genres %}
          {# el atributo booleano selected, escrito si la condición es verdadera, omitido en caso contrario #}
          <option value="{{ genre }}"{% if genre == model.genre %} selected{% endif %}>{{ genre }}</option>
        {% endfor %}
      </select>
    </div>
    <div class="col-auto">
      <button class="btn btn-primary" type="submit">Search</button>
    </div>
  </form>
  <p>{{ model.results|length }} book(s) found.</p>
  <ul>
    {% for book in model.results %}
      <li><i>{{ book.title }}</i>, {{ book.author }} ({{ book.genre }})</li>
    {% endfor %}
  </ul>
{% endblock %}
  • línea 6: la etiqueta [<form>]. El atributo [action] es la URL a la que se envía el formulario; [method="get"] coloca los campos en la URL. Las clases de [Bootstrap] disponen los campos en una sola línea;
  • línea 8: una etiqueta de campo (label). Su atributo [for] especifica el identificador ([id]) del campo que describe: al hacer clic en la etiqueta, el cursor se coloca en el campo, y los lectores de pantalla leen la etiqueta junto con el campo;
  • línea 10: un campo de entrada. Su atributo [name] es el nombre del parámetro enviado al servidor: este es el vínculo entre el formulario y la vista ([request.GET.get("keyword", "")]). El atributo [value] es el valor mostrado: la entrada anterior, mostrada de nuevo (y escapada por [{{ }}], lo cual es esencial en un atributo: una entrada que contenga una comilla ["] cerraría el atributo de otro modo);
  • líneas 14–20: una lista desplegable. Cada [<option>] tiene un valor ([value]), que se envía al servidor, y un texto, que se muestra. La primera opción, con un valor vacío, significa «todos los géneros»;
  • línea 18: a la opción seleccionada en la solicitud anterior se le asigna el atributo [selected]. Es un atributo booleano: basta con su presencia; no tiene valor. La condición lo establece si es verdadera y no establece nada en caso contrario;
  • línea 23: el botón de envío;
  • línea 26: el número de resultados.

4.5.4. Ejecución

Image

Ingresemos [le] y seleccionemos el tipo [novel]:

Image

La URL de la página de resultados contiene los campos del formulario: [/search?keyword=le&genre=novel]. La respuesta del formulario:

curl "http://localhost:8000/search?keyword=le&genre=novel"
...
      <input class="form-control" id="keyword" name="keyword" value="le">
...
      <select class="form-select" id="genre" name="genre">
        <option value="">(all)</option>


          <option value="novel" selected>novel</option>


          <option value="poetry">poetry</option>


          <option value="drama">drama</option>

      </select>
...
  <p>1 book(s) found.</p>
  <ul>

      <li><i>Le Rouge et le Noir</i>, Stendhal (novel)</li>

  </ul>
...

«Madame Bovary» no está seleccionado: «le» no aparece ni en el título ni en el nombre del autor.

4.6. Ejemplo 18: campos de formulario

Este ejemplo muestra todos los tipos de campos de un formulario HTML, enviado esta vez mediante POST. Demuestra cómo volver a mostrar cada tipo de campo con su valor actual, cómo envía el navegador los valores de cada campo y cómo verifica el servidor que un valor recibido es realmente una de las opciones disponibles. Escribir todo esto a mano, como en el ejemplo 17, sería tedioso y repetitivo. Los formularios de [Django], que usamos en el capítulo anterior para validar parámetros, también pueden mostrarse: cada campo tiene un widget (un objeto que crea su campo de entrada en HTML, junto con el valor actual) y el formulario vuelve a mostrar lo ingresado y los posibles errores. Esta es la versión completa de lo que el curso de [Symfony] delegaba en su componente Form, y de lo que el curso de [Flask] delegaba en [WTForms].

18-fields/
├── config/
│   ├── rendering.py
│   ├── settings.py
│   └── ...
├── form/
│   ├── __init__.py
│   ├── forms.py
│   ├── lists.py
│   └── views.py
├── static/
│   └── ...
├── templates/
│   ├── django/
│   │   └── forms/
│   │       └── widgets/
│   │           ├── input_option.html
│   │           └── multiple_input.html
│   ├── form/
│   │   └── form.html
│   ├── forms/
│   │   └── field.html
│   └── layout.html
└── manage.py

4.6.1. Listas: form/lists.py

1
2
3
4
5
6
7
8
9
# form/lists.py: las listas que ofrece el formulario. En una aplicación
# real, provendrían de una base de datos

# cada lista: pares (valor enviado, texto mostrado)
TITLES = [("Mr", "Mr"), ("Mme", "Mme"), ("Melle", "Melle")]
COUNTRIES = [("fr", "France"), ("be", "Belgium"), ("ch", "Switzerland"), ("ca", "Canada")]
HOBBIES = [("reading", "reading"), ("music", "music"), ("sport", "sport"), ("cinema", "cinema")]
LANGUAGES = [("French", "French"), ("English", "English"), ("Spanish", "Spanish"),
             ("German", "German")]

Las listas desplegables del formulario (títulos de cortesía, países, pasatiempos, idiomas) son constantes de un módulo: en una aplicación real, provendrían de una base de datos. Cada lista consta de pares (valor, texto): el valor es lo que se envía al servidor y el texto es lo que se muestra (ejemplo 08). Un par se escribe entre paréntesis: es una tupla, una secuencia de valores que no se puede modificar.

4.6.2. El formulario: form/forms.py

# form/forms.py: la DESCRIPCIÓN del formulario: sus campos, su tipo, su widget

from django import forms

from . import lists


# una clase padre para nuestros formularios: da a cada área de entrada la
# clase CSS de Bootstrap que le corresponde
class BootstrapForm(forms.Form):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        # fields: los campos del formulario, en un diccionario {nombre: campo}
        for field in self.fields.values():
            widget = field.widget
            if isinstance(widget, (forms.RadioSelect, forms.CheckboxSelectMultiple)):
                css_class = "form-check-input"
            elif isinstance(widget, forms.Select):
                css_class = "form-select"
            else:
                css_class = "form-control"
            # attrs: los atributos HTML del área de entrada
            widget.attrs["class"] = css_class


# los campos del formulario, en su orden de visualización. El CAMPO (forms.XxxField)
# convierte y valida el valor; el WIDGET (forms.XxxInput...) dibuja el área de entrada
class FieldsForm(BootstrapForm):
    # botones de opción (radio): una lista de opciones, dibujada por el widget RadioSelect;
    # error_messages: el mensaje del error de "campo obligatorio"
    title = forms.ChoiceField(choices=lists.TITLES, widget=forms.RadioSelect,
                              error_messages={"required": "The title is required."})
    # un área de entrada; required=False: el campo no es obligatorio
    name = forms.CharField(required=False)
    # una contraseña: nunca se vuelve a mostrar en la página
    password = forms.CharField(label="Password", required=False, widget=forms.PasswordInput)
    # una fecha: un campo <input type="date">; el valor es una fecha de Python
    birth_date = forms.DateField(label="Date of birth", required=False,
                                 widget=forms.DateInput(attrs={"type": "date"}))
    # casillas de verificación: una lista de opciones MÚLTIPLES
    hobbies = forms.MultipleChoiceField(choices=lists.HOBBIES, required=False,
                                        widget=forms.CheckboxSelectMultiple)
    # lista desplegable: el widget predeterminado de un ChoiceField
    country = forms.ChoiceField(choices=lists.COUNTRIES)
    # lista de selección múltiple, mostrada en cuatro líneas
    languages = forms.MultipleChoiceField(label="Spoken languages", choices=lists.LANGUAGES,
                                          required=False,
                                          widget=forms.SelectMultiple(attrs={"size": 4}))
    comment = forms.CharField(required=False, widget=forms.Textarea(attrs={"rows": 2}))
    # un campo oculto
    token = forms.CharField(widget=forms.HiddenInput)
  • Líneas 10–23: una clase padre para nuestros formularios, que asigna a cada campo de entrada la clase adecuada (CSS derivado de [Bootstrap]). Redefine el constructor ([__init__]), que recibe los mismos parámetros que el de [forms.Form] ([*args], [**kwargs], ejemplo 08), y comienza llamándolo ([super().__init__(...)]). El atributo [fields] del formulario es entonces un diccionario de sus campos; cada campo tiene su propio widget ([field.widget]), cuyo diccionario [attrs] contiene los atributos HTML del campo de entrada. [isinstance] acepta una tupla de clases: ¿el widget es de una de estas clases? Los botones de opción y las casillas de verificación reciben la clase [form-check-input], las listas reciben [form-select] y los demás reciben [form-control];
  • Líneas 28–51: los campos, en el orden en que se muestran. Hay que distinguir dos objetos: el campo ([forms.XxxField]) convierte y valida el valor, como en el capítulo anterior; su widget ([forms.XxxInput], [forms.Select]...) dibuja el campo de entrada. Cada campo tiene un widget predeterminado, que se reemplaza mediante el parámetro [widget]. Por defecto, la etiqueta de un campo es su nombre, con formato ([password] se convertiría en «Password», [name] en «Name»); el parámetro [label] la selecciona;
  • Líneas 31–32: un [ChoiceField] es una lista desplegable. Con el widget [RadioSelect], se convierte en un grupo de botones de opción (una sola selección). El parámetro [error_messages] (ejemplo 09) muestra el mensaje de error de «campo obligatorio»;
  • línea 34: un [CharField] (widget predeterminado: [TextInput], un [<input type="text">]), opcional. Un campo obligatorio ([required=True], el valor predeterminado) genera el atributo HTML [required], que verifica el navegador (ejemplo 19);
  • línea 36: una contraseña (widget [PasswordInput], un [<input type="password">]), que nunca se devuelve a la página: su campo siempre está vacío al mostrarse;
  • líneas 38–39: una fecha ([DateField]), cuyo valor será un objeto [date] de tipo [Python]. El widget [DateInput] recibe el atributo [type="date"]: un campo [<input type="date">], para el cual el navegador muestra un calendario. Un campo de este tipo intercambia su valor con el servidor en el formato [yyyy-mm-dd], independientemente del formato en que lo muestre el navegador ([DateField] acepta este formato);
  • líneas 41–42: un [MultipleChoiceField] (ejemplo 10), dibujado por el widget [CheckboxSelectMultiple]: casillas de verificación;
  • Línea 44: un [ChoiceField] con su widget predeterminado, [Select]: una lista desplegable;
  • Líneas 46–48: un [MultipleChoiceField] con su widget predeterminado, [SelectMultiple]: una lista de selección múltiple, mostrada en cuatro líneas (el atributo HTML [size], especificado mediante [attrs]);
  • línea 49: un cuadro de texto ([Textarea]), de dos líneas;
  • línea 51: un campo oculto ([HiddenInput]).

[Django] también proporciona [EmailField] (ejemplo 19), [IntegerField], [DecimalField], [URLField], [BooleanField] (una sola casilla de verificación), [FileField], [ImageField], [SlugField], [UUIDField], [JSONField]... y otros widgets: [EmailInput], [NumberInput], [CheckboxInput], [ClearableFileInput], [SelectDateWidget] (tres listas: día, mes, año)...

4.6.3. Diseño de los campos: config/rendering.py y plantillas de formularios

Un formulario de [Django] se genera automáticamente mediante plantillas: una para todo el formulario, una para cada campo completo (etiqueta, campo de entrada, ayuda emergente, mensajes de error) y una para cada tipo de widget. [Django] proporciona todas estas plantillas en la aplicación [django.forms], con un diseño neutro. Para lograr el diseño de [Bootstrap], reemplazamos algunas de ellas. Primero, [Django] debe buscar las plantillas de formularios, igual que las demás, en las carpetas definidas por la configuración [TEMPLATES]: esta es la función de un renderizador de formularios:

# config/rendering.py: el motor de renderizado de los formularios

from django.forms.renderers import TemplatesSetting


# TemplatesSetting: un motor de renderizado que busca sus plantillas como las demás
# plantillas del proyecto (ajuste TEMPLATES): una plantilla de la carpeta templates del proyecto
# puede, por lo tanto, reemplazar la de Django
class BootstrapRenderer(TemplatesSetting):
    # la plantilla de un campo completo: etiqueta, área de entrada, ayuda, errores
    field_template_name = "forms/field.html"
  • línea 9: [TemplatesSetting] es el renderizador de formularios que busca sus plantillas con el motor de plantillas del proyecto: una plantilla de la carpeta [templates] del proyecto puede, por lo tanto, reemplazar una plantilla de [Django] que tenga el mismo nombre. Nuestra clase hereda este comportamiento;
  • Línea 11: el atributo [field_template_name] especifica la plantilla de un campo completo: la nuestra, [forms/field.html].

La configuración:

# config/settings.py: la configuración del ejemplo 18

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-b13ls-fk@*cj%i9(=5e1aa_eg(j0&*2cs)oc=j+qo&(!v06l^y"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    # las plantillas de los formularios de Django (una plantilla por tipo de campo)
    "django.forms",
    "form",
]

MIDDLEWARE = [
    # la protección anti-CSRF de TODAS las solicitudes POST (véase más adelante)
    "django.middleware.csrf.CsrfViewMiddleware",
]

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        # APP_DIRS: Django también busca las plantillas en la carpeta templates de
        # cada aplicación, incluido django.forms
        "APP_DIRS": True,
    },
]

# el MOTOR DE RENDERIZADO de los formularios: el nuestro, que dibuja los campos con las
# clases de Bootstrap 5 (véase config/rendering.py)
FORM_RENDERER = "config.rendering.BootstrapRenderer"

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]
  • línea 17: la aplicación [django.forms], que proporciona las plantillas de formularios de [Django], en su carpeta [templates];
  • Líneas 21–24: el middleware de protección anti-CSRF (véase más abajo);
  • línea 32: [APP_DIRS: True]: [Django] también busca plantillas en la carpeta [templates] de cada aplicación declarada, incluida [django.forms]. Las carpetas de [DIRS] se revisan primero: nuestras plantillas tienen prioridad sobre las de [Django];
  • línea 38: el ajuste [FORM_RENDERER] especifica nuestro motor de renderizado.

La plantilla de un campo completo:

{# un campo completo, con las clases de Bootstrap; field: el campo que se dibuja #}
{% if field.use_fieldset %}
  {# un grupo de botones de opción o casillas de verificación: un fieldset y su legend #}
  <fieldset class="mb-3">
    <legend class="form-label fs-6 mb-1">{{ field.label }}</legend>
    {{ field }}
{% else %}
  <div class="mb-3">
    <label class="form-label" for="{{ field.id_for_label }}">{{ field.label }}</label>
    {{ field }}
{% endif %}
    {% if field.help_text %}<div class="form-text" id="{{ field.auto_id }}_helptext">{{ field.help_text }}</div>{% endif %}
    {% if field.errors %}<div class="invalid-feedback d-block" id="{{ field.auto_id }}_error">{% for error in field.errors %}{{ error }}{% if not forloop.last %}<br>{% endif %}{% endfor %}</div>{% endif %}
{% if field.use_fieldset %}</fieldset>{% else %}</div>{% endif %}

La plantilla recibe el campo que se va a renderizar, [field] (un objeto [BoundField]: el campo, vinculado al formulario y, por lo tanto, a su valor y sus errores):

  • Líneas 2–6: un grupo de botones de opción o de casillas de verificación ([field.use_fieldset] se aplica a estos widgets) está rodeado por un [<fieldset>], cuyo título ([<legend>]) es la etiqueta del grupo: esto es lo que esperan los lectores de pantalla;
  • líneas 8–10: otro campo tiene un [<label>], vinculado al campo de entrada mediante su identificador ([id_for_label]: [id_name], por defecto [id_] seguido del nombre del campo). [{{ field }}] define el campo de entrada mediante la plantilla de su widget;
  • línea 12: el texto de ayuda del campo (parámetro [help_text] de un campo), si lo tiene;
  • línea 13: los errores del campo ([field.errors]), con las clases de [Bootstrap] ([invalid-feedback]: texto rojo, [d-block]: siempre visible). Su identificador, [id_name_error], es el que [Django] especifica en el atributo [aria-describedby] del campo de entrada, para que los lectores de pantalla lean el mensaje junto con el campo;
  • Línea 14: la etiqueta de cierre de la etiqueta abierta en la primera parte.

Por último, se reemplazan dos plantillas de widgets de [Django] para que los botones de opción y las casillas de verificación se muestren de la misma forma que en [Bootstrap], uno al lado del otro:

1
2
3
4
{# reemplaza la plantilla de Django: un grupo de botones de opción o casillas de verificación, uno al lado del otro #}
<div id="{{ widget.attrs.id }}">{% for group, options, index in widget.optgroups %}{% for option in options %}
  <div class="form-check form-check-inline">{% include option.template_name with widget=option %}</div>{% endfor %}{% endfor %}
</div>
1
2
3
{# reemplaza la plantilla de Django: UN botón de opción o UNA casilla de verificación, seguido de su etiqueta #}
{% include "django/forms/widgets/input.html" %}
<label class="form-check-label" for="{{ widget.attrs.id }}">{{ widget.label }}</label>

Tienen exactamente los mismos nombres y rutas que las plantillas de [Django] que reemplazan ([django/forms/widgets/...], que se encuentran en la carpeta [django/forms/templates] de la biblioteca):

  • [multiple_input.html] dibuja el grupo: por cada opción ([widget.optgroups]: las opciones, agrupadas; no tenemos subgrupos), un [<div class="form-check form-check-inline">] que contiene la opción, dibujada con su propia plantilla ([option.template_name]);
  • [input_option.html] renderiza una opción: el campo de entrada ([<input type="radio">] o [<input type="checkbox">], mediante la plantilla de [Django] e [input.html]), seguido de su etiqueta.

Todo esto debe escribirse una sola vez: los ejemplos 19, 21 y 28, así como el caso de estudio, usan estos archivos. Hay bibliotecas ya hechas, como [django-crispy-forms] y su paquete [crispy-bootstrap5], o [django-bootstrap5], que hacen lo mismo; preferimos demostrar el mecanismo.

4.6.4. La vista: form/views.py

# form/views.py: un formulario que usa todos los tipos de campos

from django.shortcuts import render
from django.views.decorators.http import require_http_methods

from .forms import FieldsForm

# los valores iniciales (uno por campo, una lista para un campo múltiple)
INITIAL_VALUES = {"title": "Mme", "country": "fr", "languages": ["French"], "token": "A7X2"}


# GET: el formulario, con valores iniciales; POST: los campos enviados se
# leen, se validan y luego se muestran de nuevo con el mismo formulario
@require_http_methods(["GET", "POST"])
def form(request):
    if request.method == "GET":
        # initial: los valores mostrados mientras no se haya enviado nada
        return render(request, "form/form.html",
                      {"form": FieldsForm(initial=INITIAL_VALUES)})
    # un formulario ENLAZADO a los datos enviados: los convierte y los valida
    form = FieldsForm(request.POST)
    valid = form.is_valid()
    data = None
    if valid:
        # cleaned_data: los valores convertidos por cada campo; una lista (campo
        # múltiple) se escribe como texto, con sus valores separados por comas
        data = {key: ", ".join(value) if isinstance(value, list) else value
                for key, value in form.cleaned_data.items()}
    # lo que el navegador realmente envió, campo por campo; lists(): los
    # pares (nombre, lista de todos los valores del campo)
    received = "\n".join(f"{name} = [{', '.join(values)}]" for name, values in request.POST.lists())
    return render(request, "form/form.html", {
        "form": form,
        "received": received,
        "valid": valid,
        "data": data,
    })
  • línea 9: los valores iniciales del formulario: un diccionario, con un valor por campo (una lista para un campo de varios valores);
  • línea 14: una sola vista para ambos métodos: GET muestra el formulario, POST lo procesa;
  • líneas 16–19: en GET, un formulario no vinculado (sin datos), con sus valores iniciales (parámetro [initial]): no se valida y no muestra ningún error;
  • líneas 21–22: en POST, un formulario vinculado a los campos enviados ([request.POST]), que luego se valida ([is_valid], capítulo anterior): cada campo convierte su valor (la fecha, las listas, etc.), verifica que una selección esté entre las que se ofrecieron y aplica sus restricciones;
  • líneas 24–28: si el formulario es válido, sus datos se convierten ([cleaned_data]) en un diccionario legible (mediante la sintaxis [{key: value for ...}]): una lista se escribe como texto, con sus elementos separados por comas ([", ".join(...)]);
  • Línea 31: para este ejemplo, lo que el navegador envió realmente. El método [lists()] de un [QueryDict] (ejemplo 10) recorre los pares (nombre, lista de todos los valores). La cadena [\n] es un salto de línea;
  • líneas 32–37: el formulario vinculado se pasa a la plantilla, que lo mostrará junto con lo ingresado por el usuario y los posibles errores.

4.6.5. La plantilla: templates/form/form.html

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">A complete form</h1>
  <form method="post" action="{% url 'form' %}" style="max-width: 40rem">
    {# el token anti-CSRF: un campo oculto, que verifica el middleware CsrfViewMiddleware #}
    {% csrf_token %}
    {# as_field_group: un campo completo (etiqueta, zona de entrada, errores) #}
    {{ form.title.as_field_group }}
    <div class="row g-2">
      <div class="col">{{ form.name.as_field_group }}</div>
      <div class="col">{{ form.password.as_field_group }}</div>
      <div class="col">{{ form.birth_date.as_field_group }}</div>
    </div>
    {{ form.hobbies.as_field_group }}
    <div class="row g-2">
      <div class="col">{{ form.country.as_field_group }}</div>
      <div class="col">{{ form.languages.as_field_group }}</div>
    </div>
    {{ form.comment.as_field_group }}
    {# un campo oculto: solo la zona de entrada, sin etiqueta #}
    {{ form.token }}
    <button class="btn btn-primary" type="submit">Send</button>
  </form>
  {# received: presente en el contexto si el formulario fue enviado #}
  {% if received %}
    <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border">{{ received }}</pre>
    <p>Valid form: {{ valid|yesno:"yes,no" }}</p>
    <ul>
      {# errors: un diccionario {campo: lista de errores}; items: sus pares #}
      {% for field, errors in form.errors.items %}
        {% for error in errors %}<li>{{ field }}: {{ error }}</li>{% endfor %}
      {% endfor %}
    </ul>
    {% if valid %}
      <p>The data of the form:</p>
      <ul>
        {% for key, value in data.items %}
          <li>{{ key }}: {{ value }}</li>
        {% endfor %}
      </ul>
    {% endif %}
  {% endif %}
{% endblock %}
  • Línea 5: la etiqueta [<form>], escrita manualmente: el formulario de [Django] no la genera;
  • línea 7: la etiqueta [{% csrf_token %}] crea un campo oculto que contiene el token anti-CSRF (véase más abajo);
  • línea 9: [{{ form.title }}] se refiere al campo [title] del formulario (un [BoundField]); su método [as_field_group] lo renderiza completo mediante la plantilla [forms/field.html]: etiqueta, campo de entrada (con su valor actual) y mensajes de error;
  • líneas 10–20: los demás campos, dispuestos según las clases de cuadrícula de [Bootstrap];
  • línea 22: el campo oculto, del cual solo se renderiza el campo de entrada;
  • línea 26: la variable [received] existe solo después de un envío; una variable inexistente es «falsa»;
  • líneas 32–34: los errores. [form.errors] es un diccionario, que se recorre mediante [items] (sin paréntesis, como en DTL): para cada campo, la lista de sus errores;
  • líneas 39–41: un bucle sobre un diccionario que recorre tanto las claves como los valores.

Podríamos haber escrito todo el formulario en una sola línea: [{{ form }}], que renderiza todos los campos en orden mediante la plantilla del formulario (ajuste del motor de renderizado [form_template_name]). Al procesar los campos uno por uno, se pueden disponer como se desee.

4.6.6. Protección contra CSRF

Un ataque CSRF (Cross-Site Request Forgery, falsificación de solicitudes entre sitios) consiste en que un sitio malicioso engaña al navegador de la víctima para que envíe un formulario a nuestra aplicación. El navegador incluye las cookies de nuestra aplicación en la solicitud (y, por lo tanto, la sesión del usuario autenticado), por lo que la solicitud parece legítima. La solución: todo formulario de nuestra aplicación contiene un token aleatorio que el sitio malicioso no puede conocer.

[Django] aplica esto a toda la aplicación mediante un componente de middleware, [CsrfViewMiddleware] (línea 23 del archivo [config/settings.py]). Cuando se genera una página, la etiqueta [{% csrf_token %}] escribe en el campo oculto [csrfmiddlewaretoken], y el middleware envía, junto con la respuesta, una cookie llamada [csrftoken], que contiene un secreto. Para toda solicitud que modifica datos (POST, PUT, PATCH, DELETE), antes de ejecutar la vista, el middleware verifica que el token enviado (en el campo [csrfmiddlewaretoken], o en el encabezado [X-CSRFToken], en el caso de una solicitud enviada mediante [JavaScript]) coincida con el secreto de la cookie. Un sitio malicioso no puede leer la cookie de nuestro sitio ni ver nuestras páginas: no puede generar un token válido. Si la verificación falla, no se llama a la vista: [Django] responde por sí mismo con un error 403. Esta es una diferencia importante con [Symfony], cuyo componente Form verificaba el token de cada formulario y dejaba que la acción decidiera qué hacer a continuación: con [Django], todas las solicitudes POST están protegidas, y una vista no puede olvidarse de protegerse. El decorador [@csrf_exempt] exime a una vista de esta verificación (para una API a la que llaman otros servidores, por ejemplo).

4.6.7. Ejecución

Image

Los valores iniciales son visibles: el botón de opción «Mme», el país «France» y el idioma «French». El HTML generado (extractos):

<form method="post" action="/form" style="max-width: 40rem">
    <input type="hidden" name="csrfmiddlewaretoken" value="HuaIyQ2pbEWYQCG1mTPuWEDSd9zjBvCQhGfposguhAGFVRfIl5gRe39M2HPOHKnm">
    <fieldset class="mb-3">
    <legend class="form-label fs-6 mb-1">Title</legend>
    <div id="id_title">
  <div class="form-check form-check-inline">
<input type="radio" name="title" value="Mr" class="form-check-input" required id="id_title_0">
<label class="form-check-label" for="id_title_0">Mr</label>
</div>
  <div class="form-check form-check-inline">
<input type="radio" name="title" value="Mme" class="form-check-input" required id="id_title_1" checked>
<label class="form-check-label" for="id_title_1">Mme</label>
</div>
...
<input type="checkbox" name="hobbies" value="reading" class="form-check-input" id="id_hobbies_0">
...
    <select name="languages" size="4" class="form-select" id="id_languages" multiple>
  <option value="French" selected>French</option>
  <option value="English">English</option>
...
    <input type="hidden" name="token" value="A7X2" class="form-control" id="id_token">
    <button class="btn btn-primary" type="submit">Send</button>
  </form>

[Django] ha escrito todo: los identificadores ([id_title_1]), las etiquetas asociadas a sus campos, los nombres de los campos (todas las casillas de verificación tienen el nombre [hobbies]: el navegador enviará un parámetro repetido, ejemplo 10), los atributos [checked] y [selected] para los valores actuales, el atributo [required] para los campos obligatorios y las clases de [Bootstrap]. El primer campo oculto contiene el token anti-CSRF; es distinto en cada página (se «enmascara» con un número aleatorio, para que un espía de la red no pueda adivinar el secreto comparando varias páginas). Llenemos el formulario y enviémoslo:

Image

La página muestra lo que recibió el servidor: un parámetro por campo, con varios valores para las casillas de verificación y la lista desplegable; la contraseña se envió, pero no se vuelve a mostrar en su campo. El navegador mostró la fecha según su propia configuración, pero la envió en el formato [yyyy-mm-dd]; la plantilla le dio formato al estilo inglés, [May 14, 1990], igual que cualquier fecha que muestra. El campo oculto [token] se devolvió exactamente tal cual: así es como se envía de ida y vuelta información que el usuario no puede ver (el caso de estudio lo usa para el número de versión de un registro). Sin embargo, un campo oculto no es un campo protegido: el usuario puede modificarlo con las herramientas para desarrolladores de su navegador, y el servidor debe validarlo igual que cualquier otro campo. El token anti-CSRF también se incluye entre los campos recibidos; no forma parte de los datos del formulario.

Ahora enviemos un formulario con [curl], sin token y con un país que no figuraba en la lista:

curl -i -d "name=Martin&country=xx" http://localhost:8000/form
1
2
3
4
5
6
7
8
HTTP/1.1 403 Forbidden
Content-Type: text/html; charset=utf-8

<!DOCTYPE html>
<html lang="en">
...
  <title>403 Forbidden</title>
...

La solicitud no pasó del middleware: no se llamó a la vista, y la consola del servidor lo indica:

Forbidden (CSRF cookie not set.): /form
[27/Sep/2026 19:30:21] "POST /form HTTP/1.1" 403 2908

En un navegador, la página de error de [Django] explica el motivo del rechazo (en modo de depuración):

Image

Para que se acepte el token, [curl] debe comportarse como un navegador: primero solicitar el formulario, conservando la cookie [csrftoken] (opción [-c], que guarda en un archivo las cookies recibidas), luego reenviar la cookie (opción [-b]) y el token leído de la página:

curl -c cookies.txt http://localhost:8000/form
curl -b cookies.txt -d "csrfmiddlewaretoken=k4ZfzHvE...yBD&name=Martin&country=xx&token=A7X2" http://localhost:8000/form
...
    <pre class="bg-light p-2 border">csrfmiddlewaretoken = [k4ZfzHvER4iJYcaDFRMsYh0OizTJGRMw2AtHYeGuGelfF3DZahfrxLcwUbVn0yBD]
name = [Martin]
country = [xx]
token = [A7X2]</pre>
    <p>Valid form: no</p>
    <ul>


        <li>title: The title is required.</li>

        <li>country: Select a valid choice. xx is not one of the available choices.</li>

    </ul>
...

(el token es el de la página recibida en la primera solicitud). Esta vez se llamó a la vista, y el formulario no es válido por dos motivos: no se envió ningún título, y el país [xx] no está entre las opciones. Esta última verificación la realiza el propio campo [ChoiceField], sin que lo hayamos solicitado: un usuario malintencionado podría enviar cualquier cosa, no solo lo que la página sugería. Aquí, la vista devuelve el formulario no válido con un código de estado 200; el ejemplo siguiente elegirá un código de estado más apropiado.

4.7. Ejemplo 19: validación de formularios

Un formulario de registro en el que cada campo tiene sus propias restricciones. Si se produce un error, el formulario se vuelve a mostrar con los datos ingresados por el usuario y un mensaje debajo de cada campo no válido. Agregamos una regla que se aplica a dos campos: la contraseña y su confirmación deben coincidir.

19-form-validation/
├── config/
│   ├── rendering.py
│   ├── settings.py
│   └── ...
├── registration/
│   ├── __init__.py
│   ├── forms.py
│   └── views.py
├── static/
│   └── ...
├── templates/
│   ├── forms/
│   │   └── field.html
│   ├── registration/
│   │   ├── registration.html
│   │   └── welcome.html
│   └── layout.html
└── manage.py

Los archivos [config/settings.py], [config/rendering.py] y [templates/forms/field.html] son los mismos que los del ejemplo 18.

4.7.1. El formulario: registration/forms.py

# registration/forms.py: el formulario de registro, sus campos y sus restricciones

from django import forms


# la clase padre del ejemplo 18: las clases CSS de Bootstrap
class BootstrapForm(forms.Form):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        for field in self.fields.values():
            field.widget.attrs["class"] = "form-control"


class RegistrationForm(BootstrapForm):
    # max_length: una restricción verificada por el servidor, que Django también escribe en
    # la página (atributo maxlength), para el navegador
    name = forms.CharField(max_length=20, error_messages={
        "required": "The name is required.",
        "max_length": "The name must not exceed 20 characters."})
    # EmailField: una dirección válida, con un nombre de dominio completo (example.com, y no example)
    email = forms.EmailField(label="Email address", error_messages={
        "required": "The email address is required.",
        "invalid": "Invalid email address."})
    # IntegerField: un entero; una entrada que no lo sea produce el error invalid
    age = forms.IntegerField(label="Age", min_value=18, max_value=120, error_messages={
        "required": "The age is required.",
        "invalid": "An integer is expected.",
        "min_value": "The age must be between 18 and 120 years.",
        "max_value": "The age must be between 18 and 120 years."})
    password = forms.CharField(label="Password", min_length=6, widget=forms.PasswordInput,
                               error_messages={
                                   "required": "The password is required.",
                                   "min_length": "The password must have at least 6 characters."})
    confirmation = forms.CharField(label="Confirmation", widget=forms.PasswordInput,
                                   error_messages={"required": "The confirmation is required."})

    # clean: la validación del formulario COMPLETO, después de la de cada campo. Es
    # aquí donde se comparan dos campos
    def clean(self):
        data = super().clean()
        password = data.get("password")
        confirmation = data.get("confirmation")
        # los dos campos pasaron su propia validación, pero difieren
        if password and confirmation and password != confirmation:
            # add_error: un error, asociado al campo de confirmación
            self.add_error("confirmation", "The confirmation does not match the password.")
        return data
  • líneas 7–11: la clase padre del ejemplo 18, simplificada: todos los campos son campos de entrada;
  • líneas 17–19: el nombre es obligatorio y no debe exceder los 20 caracteres. A cada error se le asigna su propio mensaje según su código (ejemplo 09). El parámetro [max_length] tiene dos efectos: el campo verifica la longitud (en el servidor) y su widget establece el atributo HTML [maxlength], que limita la entrada en el navegador ([min_length] hace lo mismo, con el atributo [minlength]);
  • líneas 21–23: un [EmailField] verifica que una dirección sea válida y exige un nombre de dominio completo ([example.com], no [example]). Su widget, [EmailInput], genera un [<input type="email">], que el navegador puede validar;
  • líneas 25–29: un [IntegerField] produce un [<input type="number">], con los atributos [min] y [max] derivados de [min_value] y [max_value], y convierte la entrada en un entero. Un valor que no es un entero produce el error [invalid];
  • líneas 30–35: la contraseña (de al menos 6 caracteres) y su confirmación, dos campos [CharField] que utilizan el widget [PasswordInput]. Un parámetro puede ocupar varias líneas;
  • líneas 39–47: el método [clean] valida el formulario completo después de validar cada campo (y sus métodos [clean_<field>], ejemplo 12). [super().clean()] devuelve [cleaned_data], que contiene solo los campos válidos: [data.get("password")] es igual a [None] si la contraseña ya fue rechazada (demasiado corta). La comparación se realiza únicamente si ambos campos son válidos; si difieren, [add_error] asocia un error al campo [confirmation] ([add_error(None, "...")] lo asociaría al propio formulario: un error “general”, que devuelve [non_field_errors()]). Esta es la manera de validar una regla que se aplica a varios campos.

4.7.2. La vista: registration/views.py

# registration/views.py: un formulario validado por el servidor

from django.shortcuts import render
from django.views.decorators.http import require_http_methods

from .forms import RegistrationForm


# GET /register: el formulario; ?html5=true: dejamos que el navegador lo valide
# antes de enviarlo. POST /register: el formulario enviado
@require_http_methods(["GET", "POST"])
def register(request):
    html5 = request.GET.get("html5") == "true"
    if request.method == "POST":
        form = RegistrationForm(request.POST)
        # is_valid: cada campo pudo convertirse y respeta sus restricciones, y
        # el método clean no informó ningún error
        if form.is_valid():
            return render(request, "registration/welcome.html",
                          {"registration": form.cleaned_data})
        # un formulario inválido, mostrado de nuevo con la entrada y los errores, con el
        # código 422 (Unprocessable Content)
        return render(request, "registration/registration.html",
                      {"form": form, "html5": html5}, status=422)
    # la primera visualización: un formulario vacío
    return render(request, "registration/registration.html",
                  {"form": RegistrationForm(), "html5": html5})
  • Línea 13: el parámetro [?html5=true] activa la validación del navegador (véase más adelante);
  • líneas 15–20: un formulario vinculado a los campos enviados. Si es válido, la página de bienvenida recibe sus datos (el siguiente ejemplo mostrará que es mejor redirigir después de un POST exitoso);
  • líneas 23–24: en caso contrario, el formulario se vuelve a mostrar, con los datos ingresados y los errores eventuales, junto con el código 422 (Unprocessable Content: “la solicitud está bien formada, pero su contenido no es válido”);
  • líneas 26–27: en la primera visualización, un formulario vacío y no vinculado.

Por lo tanto, el formulario no válido es mostrado de nuevo por la propia vista del POST, que conserva los datos ingresados y los errores: este es el enfoque habitual de [Django], al igual que de [Symfony]. Otros frameworks, como [Laravel], responden en cambio con una redirección a la página del formulario, conservando los datos ingresados y los errores en la sesión para la siguiente solicitud.

4.7.3. Plantillas

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Registration</h1>
  {% if html5 %}
    <p>Browser validation <b>enabled</b> - <a href="{% url 'register' %}">disable it</a></p>
  {% else %}
    <p>Browser validation <b>disabled</b> - <a href="{% url 'register' %}?html5=true">enable it</a></p>
  {% endif %}
  {# novalidate: el navegador ignora los atributos required, min... y envía el formulario tal cual #}
  <form method="post" {% if not html5 %}novalidate{% endif %}>
    {% csrf_token %}
    {# un bucle sobre el formulario: sus campos, cada uno con su etiqueta y sus errores #}
    {% for field in form %}
      {{ field.as_field_group }}
    {% endfor %}
    <button class="btn btn-primary" type="submit">Register</button>
  </form>
{% endblock %}

{% block page_bottom %}
  {# errors: los errores del formulario; vacío antes del envío, o si todo es válido #}
  {% if form.errors %}
    <div class="error-area" role="alert">The form contains errors.</div>
  {% endif %}
{% endblock %}
  • líneas 5–9: un enlace para activar o desactivar la validación del navegador;
  • línea 11: el atributo [novalidate] desactiva la validación del navegador: el formulario se envía tal cual y solo el servidor lo valida. Esto es lo que queremos observar primero. El formulario no tiene el atributo [action]: se envía a la URL de la página actual;
  • líneas 14–16: un bucle sobre el propio formulario: recorre sus campos, en el orden en que fueron declarados, y cada campo se renderiza de forma completa;
  • líneas 21–26: el bloque [page_bottom], definido por la plantilla padre (véase más adelante). [form.errors] está vacío antes del envío o si todo es válido. Si el formulario contiene errores, aparece un mensaje general en un recuadro cuyo estilo está definido por [static/css/styles.css] (ejemplo 15). El atributo [role="alert"] lo señala a los lectores de pantalla.
<!doctype html>
{% load static %}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Registration</title>
  <link rel="stylesheet" href="{% static 'bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-3" style="max-width: 34rem">
    <main>
      {% block content %}{% endblock %}
    </main>
    {# un segundo bloque, al pie de la página #}
    {% block page_bottom %}{% endblock %}
  </div>
</body>
</html>
  • Línea 17: un segundo bloque, [page_bottom], vacío de manera predeterminada: una plantilla puede tener tantos bloques como sean necesarios.
1
2
3
4
5
6
7
8
{% extends "layout.html" %}

{% block content %}
  {# registration: los datos validados del formulario (cleaned_data) #}
  <h1 class="h3">Welcome {{ registration.name }}</h1>
  <p>Your registration is saved: address <b>{{ registration.email }}</b>,
    age <b>{{ registration.age }}</b> years.</p>
{% endblock %}

[registration] es el diccionario de los datos validados: se eliminaron los espacios del nombre (véase más adelante) y la edad es un entero.

4.7.4. Ejecución

Enviemos un formulario lleno de errores: un nombre formado por espacios, una dirección sin dominio completo, una edad de 12, una contraseña demasiado corta y una confirmación diferente:

Image

Los datos ingresados se conservaron (excepto las contraseñas) y cada error se señala debajo de su campo correspondiente. El nombre formado por espacios se señala como faltante: un ***[CharField] elimina los espacios que rodean cada entrada (parámetro ***[strip]***, ejemplo 08) y vuelve a mostrar el valor depurado. En cambio, la confirmación no contiene errores, aunque difiere de la contraseña: como la contraseña fue rechazada, el método [clean]* no las comparó. La URL es la del formulario, [/register]: la página fue mostrada por la vista en respuesta al POST. Con [curl], proporcionando el token anti-CSRF como en el ejemplo 18, también es posible enviar algo que un navegador no enviaría: una edad no numérica:

curl -i -b cookies.txt -d "csrfmiddlewaretoken=...&name=Martin&email=jean.martin@example.com&age=abc&password=secret123&confirmation=secret123" http://localhost:8000/register
1
2
3
4
5
6
HTTP/1.1 422 Unprocessable Content
...
    <label class="form-label" for="id_age">Age</label>
    <input type="number" name="age" value="abc" min="18" max="120" class="form-control" required aria-invalid="true" aria-describedby="id_age_error" id="id_age">
    <div class="invalid-feedback d-block" id="id_age_error">An integer is expected.</div>
...

Vemos los datos ingresados nuevamente mostrados, los atributos HTML5 ([required], [min], [max]), el mensaje de error [invalid] y los atributos [aria-invalid] y [aria-describedby], que [Django] agrega automáticamente a un campo con error y que vinculan el campo con su mensaje para los lectores de pantalla.

4.7.5. Validación del navegador

Eliminemos el atributo [novalidate] haciendo clic en el enlace "Enable" (parámetro [?html5=true]). El navegador verifica entonces los atributos [required], [type="email"], [min], [max], [maxlength]... antes de enviar el formulario y muestra sus propios mensajes en un globo de ayuda debajo del primer campo con error (“Please fill in this field”, “The value must be greater than or equal to 18”, etc.): el formulario no se envía mientras haya un error. [Django] generó estos atributos automáticamente a partir de los campos: [required] para todo campo obligatorio, [maxlength] y [minlength] a partir de [max_length] y [min_length], [min] y [max] a partir de [min_value] y [max_value], [type="email"] y [type="number"] a partir de los widgets. Por lo tanto, siempre son coherentes con las restricciones del servidor. Solo la regla del método [clean] (la confirmación) no es manejada por el navegador.

Esta validación es cómoda para el usuario: es inmediata, sin idas y vueltas con el servidor. Pero no reemplaza la validación del servidor: un usuario puede desactivarla y un programa como [curl] la ignora por completo. La regla es absoluta: el servidor siempre valida; la validación del navegador es solo una comodidad adicional.

Por fin, una entrada correcta. El nombre, ingresado con espacios a ambos lados, fue depurado por el formulario:

Image

4.8. Ejemplo 20: el patrón Post/Redirect/Get

Cuando una vista POST responde con una página, esa página es el resultado de un POST. Si el usuario la recarga (presiona [F5]), el navegador reenvía el POST, tras una advertencia que pocas personas leen: el pedido se envía dos veces y el mensaje se publica dos veces. El patrón Post/Redirect/Get (PRG) evita este problema: una vista POST exitosa no genera una página, sino que responde con una redirección (ejemplo 04) a una página GET, que el navegador solicita de inmediato. Recargar esta página simplemente vuelve a ejecutar el GET.

Queda un problema: la página GET querría mostrar un mensaje (“la tarea fue agregada”), pero es la vista POST la que conoce ese mensaje, y no puede pasar una variable a una solicitud que todavía no ha ocurrido. La solución: un mensaje flash, publicado por la vista POST, que se conserva hasta que se lee, se muestra y luego se descarta. [Django] los proporciona mediante su aplicación [django.contrib.messages].

4.8.1. Configuración: config/settings.py

# config/settings.py: la configuración del ejemplo 20

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-a%lgt@s)1dxed4be^y25kc))1tt@7_%yytqt!xgh_v4=485(+k"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    # los MENSAJES FLASH: mensajes que deja una solicitud y que muestra la siguiente
    "django.contrib.messages",
    "tasks",
]

MIDDLEWARE = [
    "django.middleware.csrf.CsrfViewMiddleware",
    # el middleware de los mensajes flash: los lee al inicio de la solicitud y
    # los almacena al final de la solicitud
    "django.contrib.messages.middleware.MessageMiddleware",
]

# dónde se almacenan los mensajes flash entre dos solicitudes: en una COOKIE (véase el
# curso, "¿Dónde se almacenan los mensajes flash?")
MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "OPTIONS": {
            "context_processors": [
                # la variable messages: los mensajes flash por mostrar
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]
  • línea 17: la aplicación de mensajes;
  • líneas 21–26: su middleware, [MessageMiddleware], que lee los mensajes pendientes al comienzo de cada solicitud y, al final, almacena los que no han sido leídos (y los nuevos);
  • línea 30: la configuración [MESSAGE_STORAGE] determina dónde se almacenan los mensajes entre solicitudes: en este caso, en una cookie (véase más adelante). De manera predeterminada, [Django] prueba primero la cookie y luego, si el mensaje es demasiado grande, la sesión (véase el capítulo sobre los ámbitos); nuestro ejemplo no tiene sesión;
  • Líneas 37–40: el procesador de contexto de mensajes: hace que la variable [messages] esté disponible para todas las plantillas.

4.8.2. El servicio: tasks/service.py

# tasks/service.py: la lista de tareas, compartida por todos los usuarios

import threading

# el proceso del servidor permanece en memoria de una solicitud a la siguiente: una variable del
# MÓDULO vive tanto como él. Por lo tanto, la lista es compartida por todas las
# solicitudes de todos los usuarios (y se pierde cuando el servidor se detiene)
_tasks = ["Read chapter 3"]

# el servidor atiende varias solicitudes AL MISMO TIEMPO, en varios hilos de ejecución
# (threads): un candado garantiza que solo una a la vez modifique la lista
_lock = threading.Lock()


def list_tasks() -> list[str]:
    # una copia: quien llama no puede modificar la lista del servicio
    with _lock:
        return list(_tasks)


def add(label: str) -> None:
    # with: el candado se toma aquí y se libera al salir del bloque, incluso después de una excepción
    with _lock:
        _tasks.append(label)

La lista de tareas es compartida por todos los usuarios y debe persistir de una solicitud a la siguiente. Lo vimos en los ejemplos 01 y 06: en [Python], el servidor permanece en memoria de una solicitud a la siguiente. Por lo tanto, basta con una simple variable de módulo. Quienes siguieron el curso de [Symfony] recordarán que, en [PHP], la lista debía almacenarse en una caché o en un archivo.

  • Línea 8: la lista, una variable de módulo. Existe mientras se ejecuta el proceso del servidor: se pierde cuando el servidor se detiene o se reinicia (tras un cambio de código, durante el desarrollo). Y si el servidor de producción ejecuta varios procesos (lo cual es una práctica habitual: uno por procesador, por ejemplo), cada uno tendrá su propia lista. Por lo tanto, una aplicación real almacenaría la lista en una base de datos (capítulo 7);
  • Línea 12: el servidor de desarrollo procesa varias solicitudes al mismo tiempo, cada una en su propio hilo. Dos actualizaciones simultáneas podrían entrar en conflicto. Un bloqueo ([threading.Lock]) garantiza que solo un hilo a la vez ejecute el código que protege;
  • líneas 15–18: la función devuelve una copia de la lista, creada bajo la protección del bloqueo;
  • líneas 21–24: la instrucción [with] adquiere el bloqueo, ejecuta el bloque y luego lo libera, en todos los casos, incluso si una excepción interrumpe el bloque. Un objeto que puede ser utilizado por [with] se denomina administrador de contexto; los archivos son otro ejemplo ([with open(...) as f:] cierra el archivo al final del bloque).

El servicio es un módulo, no una clase: sus funciones se invocan mediante [service.list_tasks()] y [service.add(...)]. Esta es la manera más simple, en [Python], de tener un único objeto compartido por toda la aplicación (ejemplo 06).

4.8.3. Vistas: tasks/views.py

# tasks/views.py: el patrón Post / Redirect / Get

from django.contrib import messages
from django.shortcuts import redirect, render
from django.views.decorators.http import require_http_methods, require_POST

from . import service


# GET /tasks: la lista y el formulario de adición; POST /tasks: la adición, según el
# patrón Post / Redirect / Get
@require_http_methods(["GET", "POST"])
def tasks(request):
    if request.method == "GET":
        return render(request, "tasks/tasks.html", {"tasks": service.list_tasks()})
    label = request.POST.get("label", "").strip()
    if label == "" or len(label) > 40:
        # entrada inválida: mostramos la página de nuevo, sin redirección
        return render(request, "tasks/tasks.html", {
            "tasks": service.list_tasks(),
            "label": label,
            "error": "The label must have 1 to 40 characters."})
    service.add(label)
    # un mensaje "flash": sobrevivirá a la redirección, para la SIGUIENTE solicitud
    messages.success(request, f"The task [{label}] has been added.")
    # sin página: una redirección a la página GET
    return redirect("tasks")


# POST /tasks/without-prg: el contraejemplo (una página como respuesta al POST)
@require_POST
def add_without_prg(request):
    service.add(request.POST.get("label", "").strip() or "(untitled)")
    return render(request, "tasks/tasks.html", {"tasks": service.list_tasks(), "without_prg": True})
  • líneas 16–22: la entrada se valida manualmente para mantener el ejemplo conciso ([strip] elimina los espacios circundantes). Una entrada no válida se vuelve a mostrar sin redirección: no hay nada que proteger contra un envío duplicado, ya que nada ha sido modificado;
  • línea 25: [messages.success] registra un mensaje flash de nivel “success” (también existen [debug], [info], [warning], y [error]: el nivel permite mostrar los mensajes de manera distinta);
  • línea 27: la redirección a la página GET, llamada [tasks] (ejemplo 04);
  • líneas 31–34: el contraejemplo: una página en respuesta a un POST. El operador [or] devuelve su operando izquierdo si es “verdadero” (aquí, una cadena no vacía) y el operando derecho en caso contrario.

4.8.4. Las plantillas

<!doctype html>
{% load static %}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Tasks</title>
  <link rel="stylesheet" href="{% static 'bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    {# los mensajes flash: se leen una sola vez, luego desaparecen #}
    {% for message in messages %}
      <div class="alert alert-success" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
  </div>
</body>
</html>
  • Líneas 14–16: [messages] contiene los mensajes flash pendientes. Recorrerlos los marca como leídos: el middleware los eliminará al final de la solicitud; un mensaje flash se muestra una sola vez. La clase [alert alert-success] de [Bootstrap] muestra el mensaje en un recuadro verde. Cada mensaje también tiene un nivel ([message.level]) y etiquetas ([message.tags]: [success]...), que determinan su presentación.
{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">My tasks</h1>
  <ol>
    {% for task in tasks %}
      <li>{{ task }}</li>
    {% endfor %}
  </ol>
  <form method="post" action="{% url 'tasks' %}" class="d-flex gap-2">
    {% csrf_token %}
    <input class="form-control" name="label" value="{{ label }}" placeholder="New task">
    <button class="btn btn-primary text-nowrap" type="submit">Add</button>
    {# formaction: este botón envía el MISMO formulario a otra dirección #}
    <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="{% url 'tasks_without_prg' %}">Add without PRG</button>
  </form>
  {% if error %}
    <div class="error-area" role="alert">{{ error }}</div>
  {% endif %}
  {% if without_prg %}
    <p class="text-danger mt-2">Page displayed in response to a POST: press F5 and the task will be added a second time.</p>
  {% endif %}
{% endblock %}
  • línea 11: el token anti-CSRF: el middleware [CsrfViewMiddleware] está activo (línea 22 del archivo [config/settings.py]);
  • línea 12: la variable [label] solo existe después de una entrada no válida: una variable ausente se muestra como una cadena vacía;
  • línea 15: el atributo [formaction] de un botón envía el formulario a una dirección distinta de la de su atributo [action]: un mismo formulario puede así activar dos vistas diferentes;
  • Líneas 17–22: el mensaje de error y la advertencia del contraejemplo.

4.8.5. ¿Dónde se almacenan los mensajes flash?

Entre la solicitud POST y la solicitud GET posterior, el mensaje debe almacenarse en algún lugar. Elegimos una cookie. Examinémosla con [curl], guardando las cookies en un archivo (opciones [-c] y [-b], ejemplo 18), después de solicitar la página para obtener el token anti-CSRF:

curl -i -b cookies.txt -c cookies.txt -d "csrfmiddlewaretoken=...&label=Do%20the%20exercises" http://localhost:8000/tasks
1
2
3
4
HTTP/1.1 302 Found
Content-Type: text/html; charset=utf-8
Location: /tasks
Set-Cookie: messages=W1siX19qc29uX21lc3NhZ2UiLDAsMjUsIlRoZSB0YXNrIFtEbyB0aGUgZXhlcmNpc2VzXSBoYXMgYmVlbiBhZGRlZC4iLCIiXV0:1xAsjI:xIWL3aUp2CbHdwZRyfv13cVIN1QG9baN2Ss020Pzyl0; HttpOnly; Path=/; SameSite=Lax

La respuesta al POST es una redirección (código de estado 302, encabezado [Location]), acompañada de la cookie [messages]. Esta cookie es [HttpOnly] (el [JavaScript] de la página no puede leerla) y [SameSite=Lax] (el navegador no la envía con una solicitud POST originada en otro sitio). Su valor consta de tres partes, separadas por dos puntos: los datos, una fecha (codificada en base 62) y una firma. Los datos son la lista de mensajes, en JSON, codificada en base 64 (aquí no está comprimida: [Django] comprime los datos solo cuando eso los hace más cortos, y un valor comprimido comienza con un punto). Una vez decodificados, se obtiene:

[["__json_message",0,25,"The task [Do the exercises] has been added.",""]]

Se ve el nivel del mensaje (25: success) y su texto. Por lo tanto, el contenido de la cookie no es secreto: cualquiera puede decodificarlo. Pero está firmado: la firma se calcula a partir de los datos y de la clave secreta de la aplicación ([SECRET_KEY], ejemplo 01). Si el navegador devuelve una cookie modificada, la firma ya no coincide y [Django] la ignora: un usuario no puede fabricar mensajes falsos. Sigamos la redirección devolviendo la cookie:

curl -i -b cookies.txt -c cookies.txt http://localhost:8000/tasks
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Vary: Cookie
Set-Cookie: messages=""; expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=0; Path=/; SameSite=Lax
...
      <div class="alert alert-success" role="status">The task [Do the exercises] has been added.</div>
...
      <li>Read chapter 3</li>

      <li>Do the exercises</li>
...

El mensaje se muestra; el middleware, al ver que fue leído, elimina la cookie (una cookie vacía que expiró en 1970). Una nueva solicitud GET ya no mostraría el mensaje. El encabezado [Vary: Cookie] advierte a las cachés que la respuesta depende de las cookies de la solicitud. La lista de tareas, por su parte, se almacena en la memoria del servidor.

4.8.6. Ejecución

Agregar una tarea: el navegador siguió la redirección; la URL de la barra de direcciones corresponde a la página GET, que puede recargarse sin riesgo.

Image

Una entrada no válida, vuelta a mostrar con su mensaje de error:

Image

El contraejemplo: la página es la respuesta a un POST y su URL es [/tasks/without-prg]. Si se presiona [F5], el navegador pregunta si se desea reenviar el formulario; si se acepta, la tarea se agrega por segunda vez.

Image

4.9. Ejemplo 21: enlaces, botones y confirmación

Un principio del protocolo HTTP: una solicitud GET no modifica nada. Los navegadores, los motores de búsqueda y las herramientas que precargan páginas siguen libremente los enlaces sin pedir permiso al usuario. Un enlace “eliminar” ([<a href="/contacts/2/delete">]) sería, por lo tanto, peligroso: un bot que rastree el sitio lo eliminaría todo. En una aplicación web:

  • la consulta se realiza mediante un enlace ([<a href>]), que envía una solicitud GET;
  • la modificación (guardar, duplicar, eliminar) se realiza mediante un botón colocado en un formulario, protegido por un token anti-CSRF.

Este ejemplo gestiona una lista de contactos y muestra una ventana de confirmación antes de cada eliminación.

21-links-buttons/
├── config/
│   ├── middleware.py
│   ├── rendering.py
│   ├── settings.py
│   └── ...
├── contacts/
│   ├── __init__.py
│   ├── forms.py
│   ├── service.py
│   ├── viewmodels.py
│   └── views.py
├── static/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── templates/
│   ├── contacts/
│   │   ├── details.html
│   │   └── list.html
│   ├── forms/
│   │   └── field.html
│   ├── fragments/
│   │   └── confirmation.html
│   └── layout.html
└── manage.py

4.9.1. Simulación de método: config/middleware.py

Un formulario HTML solo puede enviar solicitudes GET y POST. Sin embargo, el protocolo HTTP admite otros métodos: DELETE para eliminar, y PUT y PATCH para actualizar. Muchos frameworks eluden esta limitación: un formulario POST que contiene un campo oculto [_method], con el valor [DELETE] (o [PUT], [PATCH]), se trata como una solicitud de ese método. Esto se conoce como method spoofing. [Symfony] lo ofrecía como opción; [Django] no. Implementémoslo como un middleware:

# config/middleware.py: el método HTTP de un formulario, reemplazado por su campo _method

# un formulario HTML solo puede enviar GET y POST. Un formulario POST que contiene un
# campo oculto _method (DELETE, PUT, PATCH) se maneja como una solicitud de ese método
class MethodOverride:
    METHODS = {"DELETE", "PUT", "PATCH"}

    def __init__(self, get_response):
        self.get_response = get_response

    def __call__(self, request):
        return self.get_response(request)

    # process_view: Django lo llama DESPUÉS del enrutamiento, justo antes de la vista (y después del
    # process_view de los middlewares que preceden a este, incluido el que verifica el
    # token anti-CSRF de un POST). Devolver None: la solicitud sigue su camino
    def process_view(self, request, view_func, view_args, view_kwargs):
        if request.method == "POST":
            method = request.POST.get("_method", "").upper()
            if method in self.METHODS:
                request.method = method
        return None
  • línea 6: un atributo de clase: el conjunto ([set], delimitado por llaves) de los métodos aceptados;
  • líneas 11–12: [__call__] transmite la solicitud sin hacer nada;
  • líneas 17–22: el método [process_view]: [Django] lo invoca después del enrutamiento, justo antes de llamar a la vista, con la vista seleccionada y sus parámetros (el capítulo sobre el ciclo de vida lo tratará en detalle). Si la solicitud es un POST cuyo campo [_method] apunta a uno de los métodos aceptados, el middleware reemplaza el método en la solicitud. Devolver [None] permite que la solicitud continúe su camino.

¿Por qué [process_view] y no [__call__]? Por la protección anti-CSRF. El middleware [CsrfViewMiddleware] realiza su validación en su propio método [process_view], que se invoca antes que el nuestro, ya que lo precede en la configuración [MIDDLEWARE]. Por lo tanto, el token se valida en la solicitud POST, antes de que la transformemos en DELETE. Esto es lo que indica el comentario del archivo [config/settings.py]:

# config/settings.py: la configuración del ejemplo 21

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure-0c(8)1yo+s15vc6372!f@+0f@jpe2n+3)g34z*%s=h@ikzos9a"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "django.contrib.messages",
    "django.forms",
    "contacts",
]

# el ORDEN importa: el método HTTP se reemplaza (MethodOverride) solo DESPUÉS de la
# verificación del token anti-CSRF (véase config/middleware.py)
MIDDLEWARE = [
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "config.middleware.MethodOverride",
]

MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"

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

FORM_RENDERER = "config.rendering.BootstrapRenderer"

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]
  • líneas 23–27: tres componentes de middleware: protección anti-CSRF, mensajes (ejemplo 20) y simulación de método, en ese orden;
  • línea 44: el motor de renderizado de formularios del ejemplo 18.

4.9.2. El servicio: contacts/service.py

# contacts/service.py: los contactos, compartidos por todos, en memoria (véase el ejemplo 20)

import threading

from .viewmodels import Contact

_contacts = [
    Contact(1, "Marie Durand", "01 23 45 67 89"),
    Contact(2, "Paul Martin", "06 12 34 56 78"),
    Contact(3, "Philippe Jandot", "02 98 76 54 32"),
]
_last_id = 3
_lock = threading.Lock()


def list_contacts() -> list[Contact]:
    with _lock:
        return list(_contacts)


# el contacto, o None si no existe
def read(id: int) -> Contact | None:
    with _lock:
        return next((c for c in _contacts if c.id == id), None)


def update(id: int, name: str, phone: str) -> Contact | None:
    with _lock:
        # enumerate: los pares (posición, elemento) de la lista
        for i, contact in enumerate(_contacts):
            if contact.id == id:
                # un contacto es inmutable (frozen): construimos uno nuevo, que
                # reemplaza al anterior en la lista
                _contacts[i] = Contact(id, name, phone)
                return _contacts[i]
        return None


def add(name: str, phone: str) -> Contact:
    # global: la función modifica la variable _last_id del módulo (sin esta palabra,
    # la asignación crearía una variable local)
    global _last_id
    with _lock:
        _last_id += 1
        contact = Contact(_last_id, name, phone)
        _contacts.append(contact)
        return contact


def delete(id: int) -> Contact | None:
    with _lock:
        for i, contact in enumerate(_contacts):
            if contact.id == id:
                # pop elimina el elemento i de la lista y lo devuelve
                return _contacts.pop(i)
        return None

Los contactos se almacenan en memoria, igual que las tareas del ejemplo 20. Cada contacto es un objeto inmutable [Contact] (un identificador, un nombre, un número de teléfono; archivo [contacts/viewmodels.py]). Algunos puntos sobre [Python]:

  • línea 12: el último identificador asignado;
  • líneas 27–36: un contacto es inmutable; se crea uno nuevo, que reemplaza al anterior en la lista. [enumerate] recorre una lista en pares (posición, elemento);
  • líneas 39–47: una función que asigna un valor a una variable de módulo debe declararla mediante [global] (línea 42): sin esta palabra clave, la asignación [_last_id += 1] crearía una variable local de la función (y fallaría aquí, ya que lee su valor antes de asignarlo). Leer una variable de módulo, o modificar la lista a la que hace referencia ([_contacts.append(...)]), no requiere nada semejante;
  • línea 55: [pop(i)] elimina de la lista el elemento en la posición [i] y lo devuelve;
  • Las funciones devuelven [None] para un contacto inexistente: corresponde a la vista decidir la respuesta.

4.9.3. El formulario de la ficha: contacts/forms.py

1
2
3
4
5
6
7
8
# contacts/forms.py: el formulario de la página de detalles de un contacto

from django import forms


class ContactForm(forms.Form):
    name = forms.CharField(widget=forms.TextInput(attrs={"class": "form-control"}))
    phone = forms.CharField(label="Phone", widget=forms.TextInput(attrs={"class": "form-control"}))

Ambos campos son obligatorios y tienen la clase "[form-control]" de "[Bootstrap]", que se asigna directamente a su widget. Los botones no forman parte de un formulario de "[Django]": están escritos directamente en la plantilla.

4.9.4. Vistas: contacts/views.py

# contacts/views.py: enlaces (GET) y botones (POST, DELETE)

from django.contrib import messages
from django.http import Http404
from django.shortcuts import redirect, render
from django.views.decorators.http import require_GET, require_http_methods

from . import service
from .forms import ContactForm


# el contacto, o una respuesta 404 si no existe
def contact_or_404(contact):
    if contact is None:
        raise Http404("unknown contact")
    return contact


# un ENLACE (<a href>): una solicitud GET, que no modifica nada
@require_GET
def list_contacts(request):
    return render(request, "contacts/list.html", {"contacts": service.list_contacts()})


# GET /contacts/2: la página de detalles; POST /contacts/2: uno de sus dos botones;
# DELETE /contacts/2: la eliminación (un POST y su campo _method)
@require_http_methods(["GET", "POST", "DELETE"])
def contact(request, id):
    if request.method == "DELETE":
        return delete(request, id)
    contact = contact_or_404(service.read(id))
    if request.method == "GET":
        form = ContactForm(initial={"name": contact.name, "phone": contact.phone})
        return render(request, "contacts/details.html", {"contact": contact, "form": form})
    form = ContactForm(request.POST)
    if not form.is_valid():
        return render(request, "contacts/details.html", {"contact": contact, "form": form})
    name = form.cleaned_data["name"]
    phone = form.cleaned_data["phone"]
    # el botón pulsado es el único que envía su nombre: "duplicate" en request.POST
    # es verdadero si es el que envió el formulario
    if "duplicate" in request.POST:
        copy = service.add(f"{name} (copy)", phone)
        messages.success(request, f"The contact [{copy.name}] has been created.")
    else:
        service.update(id, name, phone)
        messages.success(request, f"The contact [{name}] has been edited.")
    return redirect("contacts")


# la eliminación; el token anti-CSRF ya fue verificado por CsrfViewMiddleware
def delete(request, id):
    contact = contact_or_404(service.delete(id))
    messages.success(request, f"The contact [{contact.name}] has been deleted.")
    return redirect("contacts")
  • líneas 13–16: una función utilitaria: un contacto inexistente devuelve una respuesta 404 que termina la vista;
  • líneas 20–22: la vista GET de la lista, que no modifica nada;
  • líneas 27–48: la ficha de un contacto. En GET, muestra el formulario, rellenado con los datos del contacto; en POST, procesa el formulario; en DELETE, elimina el contacto. Se usa así la misma URL, [/contacts/2], para consultar, guardar y eliminar. El decorador [require_http_methods] se verifica cuando se invoca la vista, es decir, después de [process_view]: efectivamente ve el método DELETE;
  • líneas 35–37: un formulario no válido se vuelve a mostrar;
  • líneas 42–47: un formulario puede tener varios botones de envío. Cuando se envía el formulario, el navegador envía, además de los campos, el nombre (atributo [name]) del botón presionado, y solo el de ese botón. [in] verifica la presencia de una clave en un diccionario: ["duplicate" in request.POST] es verdadero si el formulario se envió mediante el botón [duplicate]. Según el botón, la vista duplica o guarda el contacto;
  • línea 48: en ambos casos, el flujo PRG (ejemplo 20), con un mensaje flash;
  • líneas 52–55: la eliminación. No necesita verificar el token anti-CSRF: [CsrfViewMiddleware] ya lo hizo previamente. Un token ausente o no válido habría detenido la solicitud con un error 403.

4.9.5. Las plantillas

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Contacts</h1>
  <table class="table align-middle">
    <tbody>
      {% for contact in contacts %}
        <tr>
          <td>{{ contact.name }}</td>
          <td>{{ contact.phone }}</td>
          <td class="text-end">
            {# view: un enlace simple; url coloca el id en la ruta: /contacts/2 #}
            <a class="btn btn-sm btn-outline-primary" href="{% url 'contacts_details' contact.id %}">View</a>
            {# delete: un formulario, cuyo envío será confirmado #}
            <form method="post" class="d-inline" action="{% url 'contacts_details' contact.id %}"
                  data-confirmation="Delete the contact {{ contact.name }}?">
              {% csrf_token %}
              {# el método DELETE, que un formulario HTML no puede enviar #}
              <input type="hidden" name="_method" value="DELETE">
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      {% endfor %}
    </tbody>
  </table>
{% endblock %}
  • línea 13: un enlace, presentado como un botón mediante las clases de [Bootstrap] ([btn]...): la apariencia no tiene nada que ver con el método HTTP. [{% url 'contacts_details' contact.id %}] coloca el identificador en la ruta: [/contacts/2];
  • líneas 15–21: un formulario por cada botón “Eliminar”, sin más campos que el token y el método. La clase [d-inline] lo muestra en la misma línea que el enlace. El atributo [data-confirmation] contiene el mensaje de confirmación: los atributos [data-...] no tienen un significado asignado y están destinados al [JavaScript] de la página;
  • línea 17: el token anti-CSRF;
  • línea 19: el campo oculto [_method], que convertirá este POST en una solicitud DELETE.
{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Contact no. {{ contact.id }}</h1>
  <form method="post">
    {% csrf_token %}
    {{ form.name.as_field_group }}
    {{ form.phone.as_field_group }}
    {# dos botones de envío para un mismo formulario; name: el nombre del botón, enviado si se hace clic en él #}
    <div class="d-flex gap-2">
      <button class="btn btn-primary" type="submit" name="save">Save</button>
      <button class="btn btn-outline-primary" type="submit" name="duplicate">Duplicate</button>
      <a class="btn btn-link" href="{% url 'contacts' %}">Back to the list</a>
    </div>
  </form>
{% endblock %}
  • líneas 11–12: los dos botones de envío del formulario, cada uno con su propio nombre;
  • línea 13: el enlace para volver a la lista.

4.9.6. La ventana de confirmación

El navegador puede mostrar un cuadro de confirmación (función [JavaScript] [confirm]), pero no es muy atractivo y su apariencia depende del navegador. Aquí utilizamos una ventana modal de [Bootstrap], mostrada mediante unas pocas líneas de [JavaScript]. La ventana es un fragmento incluido en la plantilla padre y, por lo tanto, está presente, aunque oculta, en todas las páginas:

{# una única ventana para toda la página, oculta (d-none) al principio #}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title">Confirmation</h5>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-secondary" data-action="no">No, go back</button>
          <button type="button" class="btn btn-danger" data-action="yes">Yes, confirm</button>
        </div>
      </div>
    </div>
  </div>
</div>
  • línea 2: la clase [d-none] de [Bootstrap] oculta el elemento;
  • líneas 3–4: el fondo gris, seguido de la ventana, se dibujan mediante las clases de [Bootstrap];
  • línea 11: la posición del mensaje;
  • líneas 14–15: los dos botones, de tipo [button] (no [submit]: no envían ningún formulario), que se distinguen por su atributo [data-action].
<!doctype html>
{% load static %}
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Contacts</title>
  <link rel="stylesheet" href="{% static 'bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    {% for message in messages %}
      <div class="alert alert-success" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
  </div>
  {# la ventana de confirmación, presente en todas las páginas #}
  {% include "fragments/confirmation.html" %}
  {# el script, al final de la página: los elementos que busca ya existen #}
  <script src="{% static 'js/app.js' %}"></script>
</body>
</html>
  • Líneas 12–14: mensajes flash (ejemplo 20);
  • línea 20: la ventana, incluida en todas las páginas;
  • línea 22: el script, colocado al final de la página: cuando se ejecuta, los elementos que busca ya existen. Es un archivo estático, almacenado en la carpeta [static/js].

El script [static/js/app.js]:

// confirmación de los formularios que llevan el atributo data-confirmation="..."
// Sin JavaScript, estos formularios simplemente se envían sin confirmación.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // el formulario que se enviará si el usuario confirma

  // 1. interceptamos el envío de los formularios por confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // el envío queda suspendido
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // aparece la ventana
    });
  });

  // 2. los dos botones de la ventana
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // envío, SIN volver a disparar el evento 'submit'
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • línea 3: el código está encerrado en una función anónima que se ejecuta de inmediato; sus variables no interfieren con las de los otros scripts de la página;
  • líneas 4–6: la ventana, el lugar del mensaje y el formulario en espera de confirmación;
  • Líneas 9–16: para cada formulario que tiene el atributo [data-confirmation], se intercepta el evento [submit], que se dispara cuando se envía el formulario. [preventDefault()] suspende el envío; el formulario se pone en espera y su mensaje ([dataset.confirmation], el valor del atributo [data-confirmation]) se muestra en la ventana que aparece;
  • líneas 19–27: un único manejador para los clics en la ventana: [event.target] es el elemento en el que se hizo clic; su atributo [data-action] indica de qué botón se trata. “Sí” envía el formulario pendiente mediante el método [submit()], que, a diferencia de hacer clic en un botón, no dispara el evento [submit] (de lo contrario, la ventana volvería a aparecer); “No” oculta la ventana.

Sin [JavaScript], el formulario simplemente se envía sin confirmación: la página sigue siendo utilizable. Esto es la mejora progresiva: [JavaScript] agrega comodidad, pero la aplicación no depende de él.

4.9.7. Ejecución

La lista de contactos:

Image

Al hacer clic en “Eliminar” se muestra la ventana de confirmación:

Image

Después de la confirmación, la solicitud DELETE (simulada), la redirección y el mensaje emergente:

Image

La ficha de un contacto, con sus dos botones de envío:

Image

Una solicitud sin token anti-CSRF es rechazada, y un contacto inexistente devuelve un error 404:

curl -i -X POST -d "_method=DELETE" http://localhost:8000/contacts/3
curl -i http://localhost:8000/contacts/9
1
2
3
4
5
6
HTTP/1.1 403 Forbidden
Content-Type: text/html; charset=utf-8
...
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8
...

Las páginas de error siguen siendo las detalladas del modo de depuración de [Django]. El capítulo sobre el ciclo de vida de la solicitud mostrará cómo reemplazarlas por páginas personalizadas.