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
4.1.1. La configuración: config/settings.py
El motor de plantillas se configura mediante el ajuste [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
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
- 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
- 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
Una plantilla no tiene por qué aceptar un objeto: la variable [name] es una cadena.
4.1.6. Ejecución


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).
La página de error «personalizada», seguida de un nombre que contiene HTML y un apóstrofo ([<b>martin'], codificado como URL):
La etiqueta [<b>] se escapó, sin que la vista ni la plantilla tuvieran que hacer nada (el apóstrofo también se escapó: [']). 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:
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:
- 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.
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
- 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

La página generada:
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.
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:
- 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).
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
- 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
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 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
- 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
- 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).
- 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:
Por último, la tercera página no usa la plantilla padre:
4.3.7. Ejecución



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:
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):
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:
(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].
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 %}]:
- 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:
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
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
- 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
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
- 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]).
- 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.
- 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


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.

Un extracto del HTML generado:
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
- 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
- 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
- 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

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

La URL de la página de resultados contiene los campos del formulario: [/search?keyword=le&genre=novel]. La respuesta del formulario:
«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].
4.6.1. Listas: form/lists.py
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
- 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:
- 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:
- 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:
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:
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
- 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
- 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

Los valores iniciales son visibles: el botón de opción «Mme», el país «France» y el idioma «French». El HTML generado (extractos):
[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:

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:
La solicitud no pasó del middleware: no se llamó a la vista, y la consola del servidor lo indica:
En un navegador, la página de error de [Django] explica el motivo del rechazo (en modo de depuración):

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:
(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.
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
- 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
- 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
- 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.
- Línea 17: un segundo bloque, [page_bottom], vacío de manera predeterminada: una plantilla puede tener tantos bloques como sean necesarios.
[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:

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:
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:

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
- 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
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
- 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
- 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.
- 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:
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:
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:
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.

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

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.

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.
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:
- 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]:
- 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
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
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
- 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
- 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.
- 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:
- 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].
- 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]:
- 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:

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

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

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

Una solicitud sin token anti-CSRF es rechazada, y un contacto inexistente devuelve un error 404:
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.