Skip to content

4. La vista y su modelo

Hasta ahora, las acciones generaban sus propias respuestas: texto, JSON y algunas etiquetas HTML escritas en una cadena. En una aplicación MVC, este es el papel de una vista: un archivo que describe la página HTML, con marcadores de posición para los datos que le pasa la acción, el modelo de vista.

[Flask] incluye un motor de vistas, [Jinja2], escrito por el mismo equipo (el proyecto *Pallets*). Se pueden usar otros motores ([Mako], [Chameleon]...), pero [Jinja2] es, por mucho, el más utilizado en [Python]: se encuentra en [Django] (como opción), en [Ansible], en generadores de sitios estáticos... Es el que se usa en este curso.

Una vista [Jinja2] (la documentación la llama *template*, una plantilla de página) es un archivo de texto, en este caso HTML, en el que se interpretan tres tipos de etiquetas en el servidor:

  • [{{ expression }}]: el valor de una expresión, insertado en la página;
  • [{% instruction %}]: una instrucción: condición ([if]), bucle ([for]), herencia de plantillas ([extends], [block]), inclusión ([include]), macro...;
  • [{# comment #}]: un comentario que no aparece en la página generada.

Todo lo demás se copia tal cual. La sintaxis de las expresiones es similar a la de [Python]. Esto difiere de [Thymeleaf], el motor de vistas del curso [Spring MVC], cuyas vistas son archivos HTML válidos enriquecidos con atributos [th:]; en cambio, acerca [Jinja2] a [Razor] ([ASP.NET Core MVC]), que mezcla HTML y código. De forma predeterminada, [Flask] busca las vistas en la carpeta [templates] de la aplicación.

4.1. Ejemplo 13: Una primera vista

13-first-view/
├── app.py
├── controllers/
│   └── views.py
├── models/
│   └── page.py
└── templates/
    └── views/
        ├── index.html
        └── unknown.html

4.1.1. El modelo de la vista: models/page.py

1
2
3
4
5
6
7
8
9
# models/page.py: el modelo de la vista, los datos que la acción le pasa a la vista
from dataclasses import dataclass


@dataclass
class PageModel:
    title: str
    message: str
    time: str

El modelo de la vista es una simple [dataclass] (véase el ejemplo 06): las tres informaciones que mostrará la vista. No es obligatorio definir el modelo de una vista como una clase: se podrían pasar tres variables separadas a la vista. Sin embargo, una clase documenta lo que la vista espera y permite que el editor verifique el código de la acción. Este es el enfoque que seguirá el caso de estudio, donde cada vista tiene su propia clase de modelo.

4.1.2. El controlador: controllers/views.py

# controllers/views.py: acciones que devuelven una VISTA
from datetime import datetime

from flask import Blueprint, render_template

from models.page import PageModel

views = Blueprint("views", __name__)


# render_template: el motor Jinja2 construye la página a partir de la vista
# templates/views/index.html y de las variables pasadas como parámetros con nombre
# (aquí una sola, [model]); la página producida es la respuesta de la acción
@views.get("/")
def index():
    model = PageModel(
        "My first view",
        "This page was built by Jinja2, on the server.",
        datetime.now().strftime("%H:%M:%S"))
    return render_template("views/index.html", model=model)


# la misma vista con otro modelo; u otra vista, con el código 404
@views.get("/hello/<name>")
def hello(name):
    if name == "unknown":
        # una tupla (página, código): la página, enviada con el código 404
        return render_template("views/unknown.html", name=name), 404
    model = PageModel(
        f"Hello {name}",
        "This time, the title of the page comes from the URL.",
        datetime.now().strftime("%H:%M:%S"))
    return render_template("views/index.html", model=model)
  • línea 4: importa la función [render_template];
  • líneas 16–19: la acción construye el modelo de la vista. [datetime.now().strftime("%H:%M:%S")]: la hora actual, formateada (véase el ejemplo 12);
  • línea 20: [render_template] indica a [Jinja2] que genere la página: el primer parámetro es la ruta de la vista, relativa a la carpeta [templates]; los parámetros con nombre que siguen son las variables de la vista; en este caso, solo hay una: [model]. [render_template] devuelve el texto de la página generada, que se convierte en la respuesta de la acción (de tipo [text/html]);
  • línea 28: otra vista, con una variable diferente ([name]). La tupla [(page, 404)] envía la página con un código de estado 404 (véase el ejemplo 03): una página de error personalizada;
  • Líneas 29–33: la misma vista que la acción [index], con una plantilla diferente. Esta es la ventaja de separar las acciones de las vistas: una sola vista puede ser utilizada por varias acciones.

4.1.3. La vista: templates/views/index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  {# {{ ... }}: el valor de una expresión, 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 [Jinja2];
  • Línea 6: [{{ model.title }}] inserta el valor del atributo [title] de la variable [model]. La notación de punto de [Jinja2] es más flexible que la de [Python]: [model.title] busca primero un atributo [title] y, si no lo encuentra, una clave ["title"] (si [model] es un diccionario). Por lo tanto, el código de la vista no necesita saber si su modelo es un objeto o un diccionario.

Todo lo que inserta [{{ }}] se escapa: los caracteres [<], [>], [&], ["] y ['] se reemplazan por sus códigos de entidad HTML. Este es el papel que desempeñaba la función [escape] en el ejemplo 09, pero esta vez es automático: [Flask] activa el escape automático (*autoescape*) para las vistas cuyos nombres terminan en [.html], [.htm], [.xml], [.xhtml], o [.svg]. Esto evita que una vista inserte por descuido en la página el HTML proporcionado por un usuario.

4.1.4. La vista: templates/views/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 vista no está obligada a recibir un objeto: la variable [name] es una cadena.

4.1.5. Ejecución

Image

Image

La respuesta sin procesar muestra el trabajo realizado por [Jinja2]: las etiquetas [{{ }}] han sido reemplazadas por sus valores, y el comentario ha desaparecido (en su lugar queda una línea vacía; veremos en el próximo ejemplo cómo evitarlo).

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

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

  <title>My first view</title>
</head>
<body>
  <h1>My first view</h1>
  <p>This page was built by Jinja2, on the server.</p>
  <p>Page built at 15:30:51.</p>
</body>
</html>

La página de error “personalizada”, seguida de un nombre que contiene HTML ([<b>martin], codificado en la URL):

curl -i http://localhost:5000/hello/unknown
curl http://localhost:5000/hello/%3Cb%3Emartin
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 164

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [unknown] here.</h1>
</body>
</html>
...
  <title>Hello &lt;b&gt;martin</title>
...
  <h1>Hello &lt;b&gt;martin</h1>
...

La etiqueta [<b>] fue escapada sin que interviniera ninguna acción ni vista.

4.2. Ejemplo 14: El lenguaje Jinja2

Este ejemplo combina las principales construcciones de [Jinja2] en una sola vista.

4.2.1. El modelo y la acción

# models/basics.py: el modelo de la vista del ejemplo 14
from dataclasses import dataclass
from decimal import Decimal


@dataclass
class Product:
    name: str
    price: Decimal
    in_stock: bool


@dataclass
class Address:
    street: str
    city: str


@dataclass
class BasicsModel:
    title: str
    name: str
    nickname: str | None
    html: str
    logged_in: bool
    currency: str
    products: list[Product]
    cart: list[Product]
    address: Address

El modelo contiene valores de diversos tipos: cadenas, [None], booleanos, listas de objetos, listas vacías y objetos que contienen otros objetos. El tipo [Decimal], del módulo estándar [decimal], representa con exactitud los números decimales (a diferencia del tipo [float], para el cual [0.1 + 0.2] es igual a [0.30000000000000004]); es el tipo que se debe usar para los importes.

# controllers/basics.py: una vista que usa las construcciones principales de Jinja2
from decimal import Decimal

from flask import Blueprint, render_template

from models.basics import Address, BasicsModel, Product

basics = Blueprint("basics", __name__)


@basics.get("/")
def index():
    model = BasicsModel(
        title="Jinja2 basics",
        name="Martin",
        nickname=None,
        html="<b>this is HTML</b>",
        logged_in=True,
        currency="€",
        products=[
            Product("Keyboard", Decimal("25"), True),
            Product("Mouse", Decimal("12.5"), False),
            Product("Screen", Decimal("149"), True),
        ],
        cart=[],
        address=Address("12 rue des Lilas", "Angers"))
    return render_template("basics/index.html", model=model)

La acción construye el modelo y se lo pasa a la vista. [Decimal("12.5")]: un decimal se construye a partir de una cadena para evitar el uso de un [float] inexacto.

4.2.2. Configuración: app.py

# app.py: la aplicación del ejemplo 14
from flask import Flask

from controllers.basics import basics


def create_app():
    app = Flask(__name__)
    # las etiquetas {% ... %} no dejan líneas en blanco en la página producida:
    # trim_blocks elimina el salto de línea que sigue a una etiqueta, lstrip_blocks los
    # espacios que la preceden en su línea
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    app.register_blueprint(basics)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Líneas 12–13: [app.jinja_env] es el entorno [Jinja2] de la aplicación, el objeto que carga y ejecuta las vistas. De forma predeterminada, una etiqueta [{% %}] que está sola en su línea deja en la página generada los espacios que la preceden y el salto de línea que la sigue: un bucle produciría numerosas líneas vacías. [trim_blocks] elimina el salto de línea que sigue a una etiqueta, mientras que [lstrip_blocks] elimina los espacios que la preceden. Estos dos ajustes no afectan la visualización de la página (el navegador ignora estos caracteres de espacio en blanco), pero hacen que el HTML generado sea más legible. Todos los ejemplos siguientes los activan.

4.2.3. La vista: templates/basics/index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{ model.title }}</title>
</head>
<body>
  {# {% set %}: una variable de la vista; los filtros (|) transforman un valor #}
  {% set total = model.products | sum(attribute="price") %}
  {% set count = model.products | length %}
  <h1>{{ model.title }}</h1>
  {# 1. mostrar un valor del modelo; se muestra None... "None": el filtro
        default(text, true) reemplaza un valor vacío o None. Este comentario
        de Jinja2 no aparece en la página producida #}
  <p>1. Name: {{ model.name }} - nickname: [{{ model.nickname }}] [{{ model.nickname | default("", true) }}]</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: [loop] describe el estado del bucle #}
  <p>4. Our products:</p>
  <ul>
    {% for product in model.products %}
    <li>no. {{ loop.index0 }}: {{ product.name }}, {{ product.price }} {{ model.currency }}
      {{ "(in stock)" if product.in_stock else "(sold out)" }}
      {% if loop.first %}- the first one{% endif %}
      {% if loop.last %}- the last one, seen by {{ model.name }}{% endif %}
    </li>
    {% endfor %}
  </ul>
  {# 5. la lista vacía: el bloque else de un bucle for #}
  <p>5. Your cart:
    {% for p in model.cart %}<span>{{ p.name }}</span>{% else %}it is empty.{% endfor %}
  </p>
  {# 6. expresiones calculadas, las variables definidas con set y el filtro format #}
  <p>6. {{ count }} products, for a total of {{ total }} {{ model.currency }};
    average price: {{ "%.2f" | format(total / count) }} {{ model.currency }}</p>
  {# 7. un objeto dentro de un objeto y un método de Python (upper) #}
  <p>7. Address: {{ model.address.street }}, {{ model.address.city.upper() }}</p>
  <p>8. An email address: contact@example.com</p>
</body>
</html>
  • Líneas 9–10: [{% set %}] crea una variable de vista. Los filtros transforman un valor: [value | filter] o [value | filter(parameters)]. El filtro [sum(attribute="price")] suma los atributos [price] de los elementos de una lista; el filtro [length] devuelve la longitud de una lista. [Jinja2] ofrece unos cincuenta filtros: [upper], [lower], [title], [trim], [join], [sort], [round], [default], [replace], [truncate]... ;
  • línea 15: el valor [None] se muestra... [None]. El filtro [default(value, true)] reemplaza un valor “vacío” ([None], cadena vacía, cero) por el valor especificado; sin el segundo parámetro [true], solo reemplazaría una variable no definida;
  • líneas 17–18: [{{ }}] escapa el HTML (2a); el filtro [safe], en cambio, declara que el valor es HTML seguro, que debe insertarse tal cual (2b). [safe] se reserva para el HTML generado por la propia aplicación, nunca para datos ingresados por el usuario;
  • líneas 20–24: una condición: [{% if %}], [{% elif %}], [{% else %}], [{% endif %}]. A diferencia de [Python], cuyos bloques se delimitan por la indentación, [Jinja2] cierra cada bloque con una etiqueta [end...];
  • líneas 28–34: un bucle [{% for %}] ... [{% endfor %}]. Dentro del bucle, la variable especial [loop] describe el estado del bucle: [loop.index] (el número de iteración, empezando en 1), [loop.index0] (empezando en 0), [loop.first], [loop.last] (verdadero en la primera y en la última iteración), [loop.length] (el número de elementos). Las variables externas al bucle ([model.name]) siguen siendo accesibles;
  • línea 30: la expresión condicional de [Python], [a if condition else b], es también la de [Jinja2];
  • Línea 38: un bucle [for] puede contener un bloque [{% else %}], que se ejecuta si la lista está vacía. Esto es más simple que un [if] que verifique la longitud de la lista;
  • Líneas 41–42: expresiones calculadas ([total / count]). El filtro [format] aplica un formato similar al del operador [%] de [Python]: ["%.2f"] muestra un número con dos decimales. En el ejemplo 16 veremos una manera mucho mejor de dar formato a números e importes;
  • línea 44: la notación de punto recorre objetos ([model.address.city]) y permite llamar a sus métodos: [upper()] es un método de las cadenas de [Python];
  • línea 45: una dirección de correo electrónico, escrita tal cual. El carácter [@], que tiene un significado específico en otros motores de vistas ([Razor]), no tiene ese significado en [Jinja2]: solo se interpretan las etiquetas [{{ }}], [{% %}], y [{# #}] .

4.2.4. Ejecución

Image

La página generada:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Jinja2 basics</title>
</head>
<body>
  <h1>Jinja2 basics</h1>
  <p>1. Name: Martin - nickname: [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 one    </li>
    <li>no. 1: Mouse, 12.5 €
      (sold out)
    </li>
    <li>no. 2: Screen, 149 €
      (in stock)
- the last one, seen by Martin    </li>
  </ul>
  <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. An email address: contact@example.com</p>
</body>
</html>

Los comentarios han desaparecido, y las etiquetas [{% %}] no dejaron líneas en blanco. El formato de ciertas líneas (“[- the first one </li>]”) muestra que [trim_blocks] y [lstrip_blocks] también afectan a las etiquetas ubicadas a mitad de una línea; esto no tiene efecto en el navegador.

4.3. Ejemplo 15: Plantilla, fragmentos y 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 vista, se escribe una sola vez en una plantilla (*layout*), que las páginas extienden. Este ejemplo usa además [Bootstrap], el framework CSS más utilizado, para los estilos.

15-layout/
├── app.py
├── controllers/
│   └── pages.py
├── static/
│   └── css/
│       └── styles.css
└── templates/
    ├── fragments/
    │   ├── card.html
    │   └── navbar.html
    ├── layout.html
    └── pages/
        ├── home.html
        ├── raw.html
        └── team.html

4.3.1. Archivos estáticos

Una página HTML hace referencia a otros archivos: hojas de estilo, scripts [JavaScript] e imágenes. Estos archivos, que el servidor envía tal cual, se llaman archivos estáticos. [Flask] sirve automáticamente el contenido de la carpeta [static] de la aplicación bajo la URL [/static/...]: el archivo [static/css/styles.css] está disponible en la URL [/static/css/styles.css].

/* 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 pie 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;
}

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

[Bootstrap], por su parte, es utilizado por los ejemplos 15 a 28. En lugar de colocar una copia en la carpeta [static] de cada ejemplo, estos lo comparten: se encuentra en la carpeta [examples/common/bootstrap]. Por lo tanto, hay que indicarle a [Flask] que use también esta carpeta. Este es el propósito de las siguientes líneas de [app.py]:

# app.py: la aplicación del ejemplo 15
from datetime import date
from pathlib import Path

from flask import Blueprint, Flask, request

from controllers.pages import pages

# Bootstrap, compartido por los ejemplos: la carpeta examples/common/bootstrap,
# designada a partir de la ubicación de ESTE archivo (y no de la carpeta actual)
BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    # un blueprint sin rutas, que solo sirve archivos estáticos: la
    # carpeta BOOTSTRAP, bajo la URL /bootstrap/...
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(pages)

    # un "procesador de contexto": se ejecuta antes de construir CADA vista,
    # agrega sus variables al modelo de todas las vistas
    @app.context_processor
    def common_model():
        return {"path": request.path, "year": date.today().year}

    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Línea 11: la ruta de la carpeta [common/bootstrap]. [Path], del módulo estándar [pathlib], representa la ruta de un archivo. [Path(__file__)] es la ruta del propio archivo [app.py] ([__file__] es una variable que [Python] define en cada módulo); [resolve()] la convierte en absoluta; [parent] designa la carpeta que la contiene ([15-layout]), [parent.parent] designa la carpeta superior ([examples]); el operador [/] agrega un elemento a la ruta. Especificar la carpeta a partir de la ubicación del archivo, y no de la carpeta actual, permite iniciar la aplicación desde cualquier carpeta;
  • líneas 20–21: un blueprint puede tener su propia carpeta de archivos estáticos ([static_folder]), servida bajo la URL especificada ([static_url_path]). Este blueprint solo contiene eso: no tiene rutas. El archivo [common/bootstrap/css/bootstrap.min.css] se sirve así en la URL [/bootstrap/css/bootstrap.min.css];
  • Líneas 26–28: un procesador de contexto es una función que [Flask] ejecuta antes de generar cada vista. Devuelve un diccionario, cuyos pares clave-valor se agregan a las variables de la vista. Aquí, [path] (la ruta de la URL solicitada) y [year] (el año actual) quedan así disponibles en todas las vistas, sin que las acciones tengan que proporcionarlas. La plantilla los usa para su pie de página.

4.3.2. La plantilla: templates/layout.html

<!doctype html>
{# el layout de las páginas: las páginas lo EXTIENDEN y llenan sus bloques #}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# un bloque: un espacio que la página puede llenar; aquí con un contenido por defecto #}
  <title>{% block title %}Home{% endblock %} - My site</title>
  {# url_for construye la URL de un archivo estático: /bootstrap/css/bootstrap.min.css #}
  <link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
  <div class="container py-3">
    {# inserción del archivo fragments/navbar.html #}
    {% include "fragments/navbar.html" %}
    <main>
      {# aquí se inserta el contenido de la página solicitada por la acción #}
      {% block content %}{% endblock %}
    </main>
    {# path, year: agregados al modelo de todas las vistas (véase app.py) #}
    <footer class="footer">Page [{{ path }}] - © {{ year }}</footer>
  </div>
</body>
</html>
  • línea 6: la etiqueta [viewport] indica a los navegadores móviles que muestren la página con el ancho de la pantalla, que es lo que espera [Bootstrap];
  • línea 8: un bloque es un contenedor con nombre que pueden llenar las páginas que extienden la plantilla. El contenido escrito entre [{% block title %}] y [{% endblock %}] es el contenido predeterminado del bloque, utilizado por una página que no lo redefine;
  • líneas 10–11: [url_for], que conocemos por las acciones (ejemplo 04), también genera la URL de un archivo estático: [static] designa la carpeta estática de la aplicación, [bootstrap.static] la del blueprint [bootstrap]; [filename] es la ruta del archivo dentro de esa carpeta. [url_for] está disponible en todas las vistas. Escribir la URL manualmente ([/static/css/styles.css]) también funcionaría, pero [url_for] se adapta si se mueve la carpeta o si la aplicación se instala bajo un prefijo de la URL;
  • línea 16: [{% include %}] inserta el contenido de otra vista, en este caso la barra de navegación. La vista incluida tiene acceso a las variables de la vista que la incluye;
  • línea 19: el bloque que cada página llena con su propio contenido. Está vacío de forma predeterminada;
  • línea 22: el pie de página usa las dos variables del procesador de contexto.

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

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

1
2
3
4
5
6
7
8
9
{# un fragmento: un trozo de página, insertado con {% include %} #}
<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 layout</a>
  </div>
</nav>

Un fragmento: una sección 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].

4.3.4. Una macro: templates/fragments/card.html

1
2
3
4
5
6
7
8
9
{# una MACRO: un trozo de página que tiene parámetros, como una función #}
{% macro card(name, role) %}
<div class="card">
  <div class="card-body">
    <h5 class="card-title">{{ name }}</h5>
    <p class="card-text">{{ role }}</p>
  </div>
</div>
{% endmacro %}
  • Líneas 2–9: una macro es un fragmento de página que tiene parámetros; esta es una función de [Jinja2]. Al llamarla, [{{ card("name", "role") }}], se inserta el fragmento de página generado con esos valores. Los parámetros pueden tener un valor predeterminado, como en [Python]: [{% macro card(name, role="") %}]. La tarjeta ([card]) es un componente de [Bootstrap].

4.3.5. Las páginas

{# esta página EXTIENDE el layout: solo proporciona el contenido de sus bloques #}
{% extends "layout.html" %}
{# la macro [card] del archivo fragments/card.html #}
{% from "fragments/card.html" import card %}

{% block content %}
  <h1>Welcome</h1>
  <p>This page only contains its own content: the header, the navigation
    bar and the footer come from the <code>layout.html</code> layout.</p>
  {# la llamada a la macro, con dos parámetros escritos en el momento #}
  {{ card("A macro", "called with parameters written on the spot") }}
{% endblock %}
  • Línea 2: la página extiende la plantilla: [Jinja2] genera la página de la plantilla, reemplazando sus bloques por los que la página redefine. [{% extends %}] debe ser la primera etiqueta de la vista. En una vista que extiende una plantilla, el texto escrito fuera de los bloques no aparece en la página generada (sin embargo, las instrucciones [{% set %}] conservan allí su efecto; lo veremos en el capítulo sobre internacionalización);
  • línea 4: la importación de la macro [card], definida en otro archivo;
  • línea 6: el bloque [content] de la plantilla, redefinido. La página no redefine el bloque [title]: conserva su contenido predeterminado, “Home”;
  • Línea 11: la llamada a la macro.
{% extends "layout.html" %}
{% from "fragments/card.html" import card %}

{% 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">
      {# la macro recibe el nombre y el rol del miembro actual #}
      {{ card(member.name, member.role) }}
    </div>
    {% endfor %}
  </div>
{% endblock %}
  • línea 4: esta página también redefine el título;
  • líneas 9–14: una tarjeta por cada miembro del equipo, en una cuadrícula que usa [Bootstrap] ([row], [col-md-4]: tres columnas en una pantalla mediana o grande, una columna en un teléfono).

El controlador no contiene nada nuevo:

# controllers/pages.py: tres páginas
from dataclasses import dataclass

from flask import Blueprint, render_template

pages = Blueprint("pages", __name__)


# un miembro del equipo
@dataclass
class Member:
    name: str
    role: str


@pages.get("/")
def home():
    return render_template("pages/home.html")


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


@pages.get("/raw")
def raw():
    return render_template("pages/raw.html")

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

<!doctype html>
{# esta vista no usa el layout: 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 layout: no Bootstrap, no navigation bar.</p>
  <p><a href="/">Back to home</a></p>
</body>
</html>

4.3.6. Ejecución

Image

Image

Image

La página del equipo, tal como la recibe el navegador:

curl http://localhost:5000/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="/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 layout</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</footer>
  </div>
</body>
</html>

El navegador recibió una página completa: la plantilla, el fragmento, la página y las macros se ensamblaron en el servidor. Las URL de las hojas de estilo fueron calculadas por [url_for]. Se puede verificar que el archivo de [Bootstrap] se sirve correctamente (la opción [-I] de [curl] muestra solo los encabezados de la respuesta):

curl -I http://localhost:5000/bootstrap/css/bootstrap.min.css
1
2
3
4
HTTP/1.1 200 OK
Content-Disposition: inline; filename=bootstrap.min.css
Content-Type: text/css; charset=utf-8
...

4.4. Ejemplo 16: Helpers

Una vista suele necesitar dar formato a valores: un importe con su moneda, una fecha escrita completa o un texto en mayúsculas. Este código no pertenece a la acción (que no se ocupa de la presentación) y sería engorroso de escribir en la vista. En cambio, se escribe en [Python], dentro de funciones que las vistas llaman: son los helpers de la vista. [Jinja2] reconoce tres tipos: los filtros ([{{ price | money }}]), las funciones globales ([{{ uppercase(name) }}]) y las macros, que ya hemos visto.

4.4.1. Funciones: helpers/formats.py

# helpers/formats.py: funciones invocadas por las vistas
from datetime import date
from decimal import Decimal

from babel.dates import format_date
from babel.numbers import format_currency
from flask import g


# "keyboard" -> "KEYBOARD"
def uppercase(text: str | None) -> str:
    return "" if text is None else text.upper()


# un monto en una moneda, en el formato del idioma de la solicitud (g.locale,
# vea app.py): 1149.9 -> "€1,149.90" en inglés, "1 149,90 €" en francés.
# La biblioteca Babel conoce las convenciones de cada país
def money(amount: Decimal, currency: str = "EUR") -> str:
    return format_currency(amount, currency, locale=g.locale)


# una fecha en palabras completas, en el idioma de la solicitud: "Saturday, September 26, 2026"
def long_date(day: date) -> str:
    return format_date(day, format="full", locale=g.locale)
  • líneas 11–12: una función normal que acepta [None];
  • Líneas 18–19: formato de un importe. Depende del idioma: en francés, [1 149,90 €] (espacio para separar los miles, coma decimal, símbolo después del importe); en inglés, [€1,149.90]. La biblioteca [Babel] admite las convenciones de todos los países (usa datos del proyecto Unicode *CLDR*): [format_currency(amount, currency, locale=...)] da formato a un importe, con la moneda designada por su código internacional ([EUR], [USD]). La configuración regional ([fr_FR], [en_US]) especifica un idioma y un país. Aquí, se lee de [g.locale], que examinaremos a continuación;
  • líneas 23–24: [format_date] da formato a una fecha; el formato [full] la escribe completa, incluido el día de la semana.

4.4.2. La configuración: app.py

# app.py: la aplicación del ejemplo 16
from pathlib import Path

from flask import Blueprint, Flask, g, request

from helpers import formats
from controllers.pages import pages

BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(pages)

    # el idioma de formato de cada solicitud: el parámetro ?lang=fr de la URL,
    # inglés en caso contrario. before_request: una función que se ejecuta antes de CADA
    # acción; [g]: un objeto que vive durante una solicitud
    @app.before_request
    def set_language():
        g.locale = "fr_FR" if request.args.get("lang") == "fr" else "en_US"

    # FILTROS "caseros": {{ price | money }}, {{ day | long_date }}
    app.add_template_filter(formats.money)
    app.add_template_filter(formats.long_date)
    # una FUNCIÓN global, invocable en todas las vistas: {{ uppercase(name) }}
    app.add_template_global(formats.uppercase)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Líneas 23–25: el idioma del formato depende de la solicitud: el parámetro [?lang=fr] de la URL selecciona el francés; el inglés es el idioma predeterminado. [@app.before_request] registra una función que [Flask] ejecuta antes de cada acción (el capítulo sobre el ciclo de vida de la solicitud detallará estos “hooks”). Almacena la configuración regional en [g], un objeto de [Flask] que, al igual que [request], es específico de la solicitud en curso: se puede almacenar en él lo que se desee ([g.locale = ...]); se descarta al final de la solicitud. Esta es la manera de compartir información entre las distintas funciones que procesan la misma solicitud, sin pasarla como parámetro de una a otra. El capítulo sobre los ámbitos de datos retomará este tema;
  • líneas 28–29: registro de dos funciones como filtros de [Jinja2] bajo sus nombres. Un filtro recibe como primer parámetro el valor colocado antes de [|]; los parámetros siguientes son los del filtro: [{{ price | money("USD") }}] llama a [money(price, "USD")];
  • Línea 31: registro de una función como función global de vista.

El decorador [@app.template_filter()] (aplicado a la propia función) es otra manera de registrar un filtro. Llamar a [add_template_filter] desde [app.py] tiene la ventaja de mantener el módulo [helpers/formats.py] independiente de [Flask] (con la excepción de [g]).

4.4.3. El controlador: controllers/pages.py

# controllers/pages.py: dos páginas
from dataclasses import dataclass
from datetime import date
from decimal import Decimal

from flask import Blueprint, render_template

pages = Blueprint("pages", __name__)


@dataclass
class Product:
    name: str
    price: Decimal
    stock: int


@pages.get("/")
def home():
    return render_template("pages/home.html", today=date.today())


@pages.get("/products")
def products():
    return render_template("pages/products.html", products=[
        Product("keyboard", Decimal("25"), 12),
        Product("mouse", Decimal("12.5"), 0),
        Product("screen", Decimal("1149.9"), 3),
    ])

Las acciones pasan valores sin procesar a las vistas: un [date], algunos [Decimal]. El formato lo manejan las vistas.

4.4.4. Las vistas

{# una macro: un enlace de la barra de navegación, que recibe la clase [active]
   si la página actual está bajo la ruta [href]. [request]: la solicitud
   actual, que Flask pone a disposición de todas las vistas #}
{% macro link(href, text) %}
  {% set active = request.path == "/" if href == "/" else request.path.startswith(href) %}
  <a class="nav-link{{ ' active' if active }}" href="{{ href }}">{{ text }}</a>
{% endmacro %}

<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">Helpers</span>
  <div class="navbar-nav">
    {# 1. una condición escrita en la vista #}
    <a class="nav-link{% if request.path == '/' %} active{% endif %}" href="/">Home</a>
    {# 2. la macro [link] #}
    {{ link("/products", "Products") }}
    {# 3. url_for construye la URL de una acción; un parámetro que no es una
          variable de ruta se agrega al final de la URL: /products?lang=fr #}
    <a class="nav-link" href="{{ url_for('pages.products', lang='fr') }}">Produits (fr)</a>
  </div>
</nav>
  • Líneas 4–7: una macro que crea un enlace para la barra de navegación. Al enlace de la página actual se le asigna la clase [active] de [Bootstrap], que lo resalta. La variable [request] (la solicitud actual) está disponible en todas las vistas, al igual que [g], [url_for], y [session] (véase el capítulo sobre los ámbitos). La expresión condicional de la línea 5 trata por separado la página de inicio, cuya ruta, [/], es el punto de partida de todas las demás;
  • línea 6: una expresión condicional sin [else] devuelve una cadena vacía si la condición es falsa;
  • línea 13: lo mismo, escrito directamente en la vista, sin una macro. La macro evita repetir la condición en cada enlace;
  • línea 18: un parámetro de [url_for] que no es una variable de la ruta se agrega a la URL como parámetro: [/products?lang=fr].
1
2
3
4
5
6
{# un badge de Bootstrap: verde si el producto está en stock, rojo en caso contrario #}
{% macro badge(stock) %}
<span class="badge {{ 'text-bg-success' if stock > 0 else 'text-bg-danger' }}">
  {{- stock ~ " in stock" if stock > 0 else "sold out" -}}
</span>
{% endmacro %}
  • Línea 3: una insignia de [Bootstrap], verde ([text-bg-success]) o roja ([text-bg-danger]), según el inventario;
  • Línea 4: el operador [~] de [Jinja2] concatena dos valores convirtiéndolos en cadenas ([+] se negaría a sumar un entero y una cadena). Los guiones de [{{-] y [-}}] eliminan los espacios en blanco (espacios y saltos de línea) que preceden o siguen a la etiqueta: el texto de la insignia queda así pegado a sus etiquetas.
{% extends "layout.html" %}
{% block title %}Home{% endblock %}

{% block content %}
  <h1>Home</h1>
  {# el filtro "home-made" long_date #}
  <p>Today is {{ today | long_date }}.</p>
  {# g: el objeto de la solicitud actual, también accesible en las vistas #}
  <p>Formatting language: {{ g.locale }}
    (<a href="/?lang=fr">in French</a>, <a href="/">in English</a>)</p>
{% endblock %}
  • línea 7: la llamada al filtro “personalizado”;
  • línea 9: el objeto [g] es accesible en las vistas.
{% extends "layout.html" %}
{% from "fragments/badge.html" import badge %}
{% 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>
        {# una función global, luego un filtro, sin y con parámetro #}
        <td>{{ uppercase(product.name) }}</td>
        <td>{{ product.price | money }}</td>
        <td>{{ product.price | money("USD") }}</td>
        {# la macro [badge] construye el HTML del badge #}
        <td>{{ badge(product.stock) }}</td>
      </tr>
      {% endfor %}
    </tbody>
  </table>
{% endblock %}
  • Línea 13: la llamada a la función global;
  • líneas 14–15: el filtro [money], primero con su moneda predeterminada y luego con un parámetro;
  • línea 17: la llamada a la macro importada.

La plantilla [layout.html] es una versión simplificada de la del ejemplo 15.

4.4.5. 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á escrito directamente en las vistas. El capítulo sobre internacionalización también traducirá el texto.

Image

Un extracto del HTML produce:

curl "http://localhost:5000/products?lang=en"
1
2
3
4
5
6
7
8
9
...
      <tr>
        <td>KEYBOARD</td>
        <td>€25.00</td>
        <td>$25.00</td>
        <td><span class="badge text-bg-success">12 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]). Este es el método que usa un formulario que realiza una consulta: una búsqueda o un filtro. La URL que contiene los resultados puede guardarse como marcador, compartirse o recargarse sin riesgo;
  • [method="post"]: los campos se incluyen en el cuerpo de la solicitud (véase el ejemplo 11). Este 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.

4.5.1. El modelo: models/books.py

# models/books.py: un libro, y el modelo de la vista
from dataclasses import dataclass


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


# el modelo de la vista: la entrada (para mostrarla de nuevo), los géneros, los resultados
@dataclass
class SearchModel:
    keyword: str
    genre: str
    genres: list[str]
    results: list[Book]
  • Línea 5: [frozen=True] hace que los objetos [Book] sean inmutables: una vez creados, sus atributos ya no pueden modificarse. Es una buena práctica para los datos compartidos por todas las solicitudes, como la lista de libros;
  • líneas 14–18: el modelo de vista contiene los datos ingresados por el usuario (para que el formulario pueda mostrarlos de nuevo), la lista de géneros sugeridos y los resultados.

4.5.2. El controlador: controllers/books.py

# controllers/books.py: un formulario de búsqueda, enviado por GET
from flask import Blueprint, render_template, request

from models.books import Book, SearchModel

books = Blueprint("books", __name__)

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"),
)

GENRES = ["novel", "poetry", "drama"]


# GET / y GET /search?keyword=...&genre=...: el formulario Y sus resultados.
# Dos decoradores: dos rutas para la misma acción
@books.get("/")
@books.get("/search")
def search():
    keyword = request.args.get("keyword", "")
    genre = request.args.get("genre", "")
    word = keyword.strip().lower()
    results = [book for book in BOOKS
               if (not word or word in book.title.lower() or word in book.author.lower())
               and (not genre or book.genre == genre)]
    return render_template("books/search.html",
                           model=SearchModel(keyword, genre, GENRES, results))
  • líneas 8–16: los datos, escritos directamente en el código para este ejemplo. [BOOKS] es una tupla (entre paréntesis), una secuencia inmutable. Por convención, los nombres en mayúsculas indican constantes;
  • líneas 21–22: dos decoradores de ruta en la misma acción: responde a ambas URL. En la primera visita ([/]), no hay parámetros: se muestran todos los libros;
  • líneas 24–25: los campos del formulario se leen como parámetros de la URL (ejemplo 07). El segundo parámetro de [get] es el valor predeterminado;
  • líneas 27–29: filtrado mediante una comprensión de listas con una condición ([if]): un libro se selecciona si la palabra clave está vacía o aparece en su título o en su autor (en minúsculas en ambos lados), y si el género está vacío o coincide con el género del libro;
  • línea 31: la plantilla de la vista.

4.5.3. La vista: 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="/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 %}
        {# selected: un atributo booleano, escrito si la condición es verdadera, omitido en caso contrario #}
        <option value="{{ genre }}"{{ " selected" if genre == model.genre }}>{{ 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 (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 acción ([request.args.get("keyword")]). El atributo [value] es el valor mostrado: el dato ingresado anteriormente, mostrado de nuevo (y escapado por [{{ }}], lo cual es esencial en un atributo: un dato que contenga una comilla ["] cerraría el atributo en caso contrario);
  • 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 expresión condicional sin [else] determina si se escribe o no;
  • línea 23: el botón de envío ([type="submit"]);
  • 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:5000/search?keyword=le&genre=novel"
...
  <form method="get" action="/search" class="row g-2 align-items-end mb-3">
    <div class="col-auto">
      <label class="form-label" for="keyword">Title or author</label>
      <input class="form-control" id="keyword" name="keyword" value="le">
    </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>
        <option value="novel" selected>novel</option>
        <option value="poetry">poetry</option>
        <option value="drama">drama</option>
      </select>
    </div>
    ...
  </form>
  <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

Escribir manualmente el HTML de cada campo, volver a mostrar su valor, marcar las casillas correctas y seleccionar las opciones correctas es un trabajo repetitivo y propenso a errores. La biblioteca [WTForms] lo hace por nosotros. Allí, un formulario se describe mediante una clase, donde cada atributo es un campo; cada campo sabe cómo:

  • cómo enlazarse (binding) con la solicitud: leer su valor de los datos enviados y convertirlo a su tipo;
  • validarse a sí mismo, según su lista de validadores (ejemplo 19);
  • mostrarse en HTML, junto con su valor actual.

La extensión [Flask-WTF] integra [WTForms] en [Flask]: sus formularios leen por sí mismos la solicitud actual, y están protegidos contra los ataques CSRF (hablaremos de ello más adelante). Este ejemplo muestra todos los tipos de campos de un formulario HTML.

4.6.1. El servicio de listas: services/lists.py

# services/lists.py: las listas que ofrece el formulario. En una aplicación
# real, vendrían de una base de datos: las leeríamos UNA SOLA VEZ,
# al iniciar, ya que son las mismas para todos los usuarios.
from flask import current_app


class ListsService:

    # cada lista: pares (valor enviado, texto mostrado)
    def titles(self) -> list[tuple[str, str]]:
        return [(t, t) for t in ("Mr", "Mme", "Melle")]

    def countries(self) -> list[tuple[str, str]]:
        return [("fr", "France"), ("be", "Belgium"), ("ch", "Switzerland"), ("ca", "Canada")]

    def hobbies(self) -> list[tuple[str, str]]:
        return [(h, h) for h in ("reading", "music", "sport", "cinema")]

    def languages(self) -> list[tuple[str, str]]:
        return [(l, l) for l in ("French", "English", "Spanish", "German")]


def lists_service() -> ListsService:
    return current_app.extensions["lists"]

Las listas desplegables del formulario (títulos, países, pasatiempos, idiomas) las proporciona un servicio, siguiendo el modelo del ejemplo 06: en una aplicación real, provendrían de una base de datos. Cada opción es un par [(value, text)]: el valor enviado al servidor y el texto mostrado. [[(t, t) for t in (...)]] crea pares en los que ambos elementos son idénticos. La función [lists_service] hace único el objeto, almacenado en [app.extensions] por [app.py]:

# app.py: la aplicación del ejemplo 18
from pathlib import Path

from flask import Blueprint, Flask

from controllers.form import form
from services.lists import ListsService

# Bootstrap, compartido por los ejemplos (vea el ejemplo 15)
BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    # la clave secreta de la aplicación: firma el token anti-CSRF de los formularios
    # (vea models/input.py). En producción, una cadena aleatoria larga, mantenida en secreto
    app.config["SECRET_KEY"] = "a-secret-key-for-example-18"
    # el servicio de listas: un único objeto compartido (vea el ejemplo 06)
    app.extensions["lists"] = ListsService()
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(form)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • línea 19: [app.config] es la configuración de la aplicación, un diccionario. La clave [SECRET_KEY] es la clave secreta de la aplicación: [Flask] y sus extensiones la usan para firmar los datos confiados al navegador, es decir, para agregarles una huella digital que solo el poseedor de la clave puede calcular. Así se detecta cualquier modificación de los datos por parte del navegador. [Flask-WTF] la necesita para sus tokens anti-CSRF; volveremos a verla en la cookie de sesión (ejemplo 20). En producción, es una cadena aleatoria larga que nunca debe aparecer en el código fuente (el capítulo sobre autenticación la leerá de una variable de entorno);
  • Línea 21: el servicio único compartido por todas las solicitudes.

4.6.2. El formulario: models/input.py

# models/input.py: el formulario, descrito por una clase WTForms. Cada campo
# sabe leerse a sí mismo de la solicitud (binding) y mostrarse en HTML (renderizado)
from flask_wtf import FlaskForm
from wtforms import (DateField, HiddenField, PasswordField, RadioField,
                     SelectField, SelectMultipleField, StringField, TextAreaField)
from wtforms.validators import Optional
from wtforms.widgets import CheckboxInput, ListWidget

from services.lists import lists_service


# casillas de verificación: una lista de selección múltiple (SelectMultipleField),
# dibujada como una lista de casillas (widgets) en lugar de una lista desplegable
class Checkboxes(SelectMultipleField):
    widget = ListWidget(prefix_label=False)
    option_widget = CheckboxInput()


# FlaskForm: un formulario WTForms adaptado a Flask; lee por sí mismo los campos de la
# solicitud POST actual, y contiene un campo oculto [csrf_token]
class InputForm(FlaskForm):
    token = HiddenField()
    title = RadioField("Title")
    name = StringField("Name")
    password = PasswordField("Password")
    # un campo <input type="date"> intercambia sus valores en el formato aaaa-mm-dd;
    # Optional: el campo puede quedar vacío
    birth_date = DateField("Date of birth", validators=[Optional()])
    hobbies = Checkboxes("Hobbies")
    country = SelectField("Country")
    languages = SelectMultipleField("Spoken languages")
    comment = TextAreaField("Comment")

    # las listas de opciones, proporcionadas por el servicio en cada creación del formulario
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        lists = lists_service()
        self.title.choices = lists.titles()
        self.country.choices = lists.countries()
        self.hobbies.choices = lists.hobbies()
        self.languages.choices = lists.languages()
  • Líneas 14–16: [WTForms] no tiene un campo de “casillas de verificación”. Sin embargo, un grupo de casillas con el mismo nombre es, para el servidor, una lista de selección múltiple: envía cero, uno o más valores. Por lo tanto, creamos una clase derivada de [SelectMultipleField] que cambia solo su presentación: el widget de un campo es el objeto que genera su HTML; [ListWidget] presenta una lista de opciones, y cada opción es presentada por [CheckboxInput], una casilla de verificación;
  • línea 21: el formulario hereda de [FlaskForm], la clase base de [Flask-WTF];
  • líneas 22–32: los campos. El primer parámetro es la etiqueta. Cada clase de campo corresponde a un elemento HTML:
Campo WTForms
Elemento HTML generado
[StringField]
[<input type="text">]
[PasswordField]
[<input type="password">], nunca rellenado previamente
[HiddenField]
[<input type="hidden">], un campo invisible
[DateField]
[<input type="date">], cuyo valor se convierte a [date]
[IntegerField], [EmailField]
[<input type="number">], [<input type="email">] (ejemplo 19)
[RadioField]
un grupo de botones de opción: un solo valor
[SelectField]
una lista desplegable [<select>]: un solo valor
[SelectMultipleField]
una lista [<select multiple>]: varios valores
[TextAreaField]
un cuadro de texto [<textarea>], de varias líneas
[BooleanField]
una única casilla de verificación, convertida a booleano
  • Línea 28: el validador [Optional()] permite que el campo quede vacío (de lo contrario, la conversión de una cadena vacía a fecha fallaría). Un campo [<input type="date">] intercambia sus valores con el servidor en el formato [yyyy-mm-dd], independientemente del formato en que el navegador lo muestre;
  • líneas 35–41: los campos desplegables requieren su lista de opciones ([choices]). Esta lista se proporciona cada vez que se crea el formulario, en el constructor, mediante el método [__init__]. Primero llama al constructor de la clase padre ([super().__init__(...)]), pasándole todos sus parámetros, y luego completa los campos. Un campo [title] declarado a nivel de clase se convierte, dentro del objeto, en un campo vinculado ([self.title]) propio de este formulario.

4.6.3. El controlador: controllers/form.py

# controllers/form.py: un formulario que usa todos los tipos de campos
from flask import Blueprint, render_template, request

from models.input import InputForm

form = Blueprint("form", __name__, url_prefix="/form")


# GET: el formulario, con valores iniciales (parámetros con nombre: uno por campo)
@form.get("")
def display():
    input_form = InputForm(title="Mme", country="fr", languages=["French"], token="A7X2")
    return render_template("form/form.html", form=input_form)


# POST: InputForm() lee los campos enviados; el formulario los muestra de nuevo
@form.post("")
def process():
    input_form = InputForm()
    # validate: verifica el token anti-CSRF y las restricciones de los campos
    valid = input_form.validate()
    # lo que el navegador envió realmente, parámetro por parámetro
    received = "\n".join(f"{name} = [{', '.join(values)}]"
                         for name, values in request.form.lists())
    return render_template("form/form.html", form=input_form, received=received,
                           valid=valid)
  • línea 12: un formulario creado durante una solicitud (GET) no lee nada: sus campos toman los valores pasados al constructor (parámetros con nombre, uno por campo) o quedan vacíos. Estos son los valores iniciales del formulario;
  • línea 13: el propio formulario se pasa a la vista, que lo presentará;
  • línea 19: durante una solicitud POST, [FlaskForm] lee por sí mismo los campos enviados ([request.form]): cada campo toma el valor recibido, convertido a su tipo;
  • línea 21: [validate()] ejecuta los validadores de cada campo y devuelve [True] si todos se cumplen. Los campos desplegables verifican automáticamente que el valor recibido esté entre sus opciones: un usuario malintencionado puede enviar cualquier cosa, no solo lo que ofrecía la página. [Flask-WTF] agrega a esto una verificación del token anti-CSRF;
  • líneas 23–24: para el ejemplo, la lista de lo que el navegador realmente envió: [request.form.lists()] devuelve, para cada parámetro, su nombre y la lista de sus valores. [", ".join(...)] los combina en una sola cadena.

4.6.4. La vista: templates/form/form.html

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">A complete form</h1>
  <form method="post" action="/form" style="max-width: 40rem">
    {# los campos ocultos: el token anti-CSRF de Flask-WTF y nuestro campo [token] #}
    {{ form.csrf_token }}
    {{ form.token }}

    <div class="mb-2">
      <span class="form-label me-3">{{ form.title.label.text }}</span>
      {# botones de opción (radio): recorremos las opciones del campo; mismo [name], se envía un solo valor #}
      {% for option in form.title %}
      <div class="form-check form-check-inline">
        {{ option(class="form-check-input") }}
        {{ option.label(class="form-check-label") }}
      </div>
      {% endfor %}
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        {# un campo se muestra LLAMÁNDOLO; sus parámetros se convierten en atributos HTML #}
        {{ form.name.label(class="form-label") }}
        {{ form.name(class="form-control") }}
      </div>
      <div class="col">
        {# una contraseña NUNCA se devuelve en la página: PasswordField la omite #}
        {{ form.password.label(class="form-label") }}
        {{ form.password(class="form-control") }}
      </div>
      <div class="col">
        {{ form.birth_date.label(class="form-label") }}
        {{ form.birth_date(class="form-control") }}
      </div>
    </div>

    <div class="mb-2">
      <span class="form-label me-3">{{ form.hobbies.label.text }}</span>
      {# casillas de verificación: mismo [name], varios valores posibles #}
      {% for option in form.hobbies %}
      <div class="form-check form-check-inline">
        {{ option(class="form-check-input") }}
        {{ option.label(class="form-check-label") }}
      </div>
      {% endfor %}
    </div>

    <div class="row g-2 mb-2">
      <div class="col">
        {{ form.country.label(class="form-label") }}
        {{ form.country(class="form-select") }}
      </div>
      <div class="col">
        {{ form.languages.label(class="form-label") }}
        {# lista de selección múltiple: varios valores posibles #}
        {{ form.languages(class="form-select", size=4) }}
      </div>
    </div>

    <div class="mb-2">
      {{ form.comment.label(class="form-label") }}
      {# un área de texto: el valor va ENTRE las etiquetas #}
      {{ form.comment(class="form-control", rows=2) }}
    </div>

    <button class="btn btn-primary" type="submit">Send</button>
  </form>

  {% if received is defined %}
    <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border">{{ received }}</pre>
    <p>Valid form: {{ "yes" if valid else "no" }}</p>
    {# form.errors: un diccionario campo -> lista de sus mensajes de error #}
    <ul>
      {% for field, messages in form.errors.items() %}
      <li>{{ field }}: {{ messages | join(", ") }}</li>
      {% endfor %}
    </ul>
  {% endif %}
{% endblock %}
  • Línea 5: un formulario POST;
  • línea 7: el campo oculto que contiene el token anti-CSRF. Un ataque CSRF (*Cross-Site Request Forgery*) consiste en que un sitio malicioso engañe 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 tanto la sesión del usuario autenticado, de modo que la solicitud parece legítima. La defensa: cada formulario de nuestra aplicación contiene un token aleatorio vinculado a la sesión del usuario y firmado con la clave secreta, que el sitio malicioso no puede conocer. [Flask-WTF] rechaza todo formulario POST cuyo token falte o no sea válido;
  • línea 8: un campo se presenta llamándolo, o simplemente insertándolo en la página mediante [{{ }}] (lo que equivale a llamarlo sin parámetros). El HTML que produce no se escapa: [WTForms] lo marca como seguro (sin embargo, los valores que coloca en él sí se escapan);
  • Líneas 13–18: un grupo de botones de opción. Al recorrerlo con un bucle, el campo presenta sus opciones, una por botón: cada una se dibuja ([option(...)]) y tiene su propia etiqueta ([option.label(...)]). Todos los botones de opción comparten el mismo atributo, [name]: solo uno está seleccionado a la vez, y solo se envía un valor;
  • líneas 24–25: la etiqueta y el campo de entrada. Los parámetros con nombre de la llamada se convierten en atributos HTML: [class="form-control"]. Dado que el término [class] está reservado en [Python], [WTForms] también acepta [class_];
  • línea 30: [PasswordField] nunca vuelve a mostrar el valor recibido: una contraseña no debe enviarse de ida y vuelta dentro de una página HTML;
  • Líneas 41–46: casillas de verificación, con el mismo estilo que los botones de opción. También tienen el mismo [name]; sin embargo, se pueden seleccionar varias casillas, y el navegador envía entonces varios valores (por ejemplo, 10);
  • línea 57: la lista de selección múltiple, mostrada en cuatro líneas ([size]);
  • línea 64: el campo de texto, de dos líneas;
  • líneas 70–80: la condición [is defined] es verdadera si la variable [received] ha sido pasada a la vista (mediante la acción POST). [form.errors] es un diccionario que asocia cada campo no válido con una lista de sus mensajes de error; [items()] devuelve estos pares. El filtro [join] combina los elementos de una lista.

4.6.5. Ejecución

Image

Se ven los valores iniciales pasados al constructor: el botón de opción “Mme”, el país “France” y el idioma “French”. El HTML generado por [WTForms] (extractos):

<input id="csrf_token" name="csrf_token" type="hidden" value="ImJmYmRjNWU0NGMyZDMwNDM1MGQ0ODQ5YTExZjAzYThhYTc0YWI0ZDYi.arfKQQ.9PqkMic5droodAE5iZdcz87dHJI">
<input id="token" name="token" type="hidden" value="A7X2">
...
<input checked class="form-check-input" id="title-1" name="title" type="radio" value="Mme">
<label class="form-check-label" for="title-1">Mme</label>
...
<input class="form-control" id="birth_date" name="birth_date" type="date" value="">
...
<input class="form-check-input" id="hobbies-0" name="hobbies" type="checkbox" value="reading">
<label class="form-check-label" for="hobbies-0">reading</label>
...
<select class="form-select" id="country" name="country"><option selected value="fr">France</option><option value="be">Belgium</option>...</select>
...
<select class="form-select" id="languages" multiple name="languages" size="4"><option selected value="French">French</option>...</select>
...
<textarea class="form-control" id="comment" name="comment" rows="2">
</textarea>

[WTForms] escribió los atributos [id] (el nombre del campo, seguido del número de opción en los grupos), [name], [type], [value], así como [checked] y [selected] para las selecciones habituales. El token anti-CSRF es una cadena firmada. Vamos a llenar el formulario y enviarlo:

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 campo oculto [token] se devolvió tal cual: así es como circula, de ida y vuelta, la información que el usuario no ve (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 de desarrollo de su navegador, y el servidor debe validarlo como cualquier otro campo.

Ahora vamos a enviar, con [curl], un formulario sin token y con un país que no está en la lista:

curl -d "name=Martin&country=xx" http://localhost:5000/form
...
    <h2 class="h5 mt-3">What the server received</h2>
    <pre class="bg-light p-2 border">name = [Martin]
country = [xx]</pre>
    <p>Valid form: no</p>
    <ul>
      <li>title: Not a valid choice.</li>
      <li>country: Not a valid choice.</li>
      <li>csrf_token: The CSRF token is missing.</li>
    </ul>
...

Tres errores: falta el token; el país [xx] no figura entre las opciones; no se envió ningún título (un [RadioField] exige una selección). Los mensajes están en inglés, el idioma predeterminado de [WTForms]: el ejemplo siguiente muestra cómo elegir su idioma.

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 lo que ingresó el usuario y, debajo de cada campo con error, un mensaje.

4.7.1. El formulario: models/registration.py

# models/registration.py: los campos del formulario y sus restricciones
from flask_wtf import FlaskForm
from wtforms import EmailField, IntegerField, PasswordField, StringField
from wtforms.validators import DataRequired, Email, EqualTo, InputRequired, Length, NumberRange


# un FILTRO: transforma el valor recibido ANTES de la validación;
# aquí se quitan los espacios que rodean la entrada
def clean(value):
    return value.strip() if isinstance(value, str) else value


class RegistrationForm(FlaskForm):

    # el idioma de los mensajes que WTForms escribe por sí mismo (conversión imposible,
    # por ejemplo: "abc" en un campo de enteros)
    class Meta:
        locales = ["en"]

    # cada campo: una etiqueta, filtros y una lista de validadores, cada uno
    # con su mensaje de error. DataRequired rechaza una entrada vacía (o formada
    # solo por espacios); también produce el atributo HTML5 [required]
    name = StringField("Name", filters=[clean], validators=[
        DataRequired("The name is required."),
        Length(max=20, message="The name must not exceed 20 characters.")])

    # EmailField: un campo <input type="email">
    email = EmailField("Email address", filters=[clean], validators=[
        DataRequired("The email address is required."),
        Email("Invalid email address.")])

    # todo lo que proviene de un formulario es una cadena: IntegerField la convierte
    # ("42" -> 42); InputRequired: la entrada no debe estar vacía
    age = IntegerField("Age", validators=[
        InputRequired("The age is required."),
        NumberRange(min=18, max=120, message="The age must be between 18 and 120 years.")])

    password = PasswordField("Password", validators=[
        DataRequired("The password is required."),
        Length(min=6, message="The password must have at least 6 characters.")])

    # una regla sobre DOS campos: EqualTo compara este campo con otro
    confirmation = PasswordField("Confirmation", validators=[
        DataRequired("The confirmation is required."),
        EqualTo("password", message="The confirmation does not match the password.")])
  • Líneas 9–10: un [WTForms] filtro es una función que transforma el valor recibido antes de la validación. Aquí elimina los espacios que rodean una cadena (una entrada como [" "] queda vacía y será rechazada por [DataRequired]). La prueba con [isinstance] protege contra un valor ausente ([None]);
  • líneas 17–18: la clase interna [Meta] controla el comportamiento del formulario. [locales = ["en"]]: los mensajes que [WTForms] genera por sí mismo (una conversión imposible, una selección no válida, etc.) estarán en inglés; [WTForms] incluye sus traducciones a muchos idiomas (["fr"] daría mensajes en francés). [app.py] desactiva con este fin el mecanismo de traducción de [Flask-WTF] ([WTF_I18N_ENABLED = False]); de lo contrario, esperaría la extensión [Flask-Babel];
  • líneas 23–25: el parámetro [validators] es la lista de validadores del campo, que se ejecutan en orden. Cada uno recibe su propio mensaje de error. [DataRequired] rechaza un valor vacío; [Length] limita la longitud de la cadena;
  • líneas 28–30: [EmailField] genera un [<input type="email">]; el validador [Email] comprueba la sintaxis de la dirección (con la biblioteca [email-validator], que ya usa [Pydantic] en el ejemplo 08);
  • líneas 34–36: [IntegerField] convierte toda la entrada. [InputRequired] exige que haya una entrada; a diferencia de [DataRequired], comprueba que se haya ingresado algo, y no si el valor convertido es “verdadero”: [DataRequired] rechazaría una edad de 0, porque [0] es falso en [Python]. [NumberRange] limita el valor;
  • líneas 43–45: una regla que se aplica a dos campos: [EqualTo("password")] compara el valor de un campo con el de otro.

Los validadores también sirven para la visualización: [WTForms] deduce atributos HTML5 ([required], [maxlength], [minlength], [min], [max]) que permiten al navegador verificar la entrada incluso antes de enviarla (lo veremos más adelante). Un validador “personalizado” es una función que recibe como argumentos el formulario y el campo, y lanza una [ValidationError] (del módulo [wtforms.validators]) si el valor no es válido; también puede escribirse como un método del formulario llamado [validate_<field>]. [WTForms] ofrece otros validadores listos para usar: [Regexp] (una expresión regular), [AnyOf] (una lista de valores permitidos), [Optional]... El caso de estudio los utiliza.

4.7.2. El controlador: controllers/registration.py

# controllers/registration.py: un formulario validado por el servidor
from flask import Blueprint, render_template, request

from models.registration import RegistrationForm

registration = Blueprint("registration", __name__, url_prefix="/register")


# ?html5=true: dejamos que el navegador valide el formulario antes de enviarlo
def html5_requested() -> bool:
    return request.args.get("html5") == "true"


@registration.get("")
def display():
    return render_template("registration/registration.html", form=RegistrationForm(),
                           html5=html5_requested())


@registration.post("")
def register():
    form = RegistrationForm()
    # validate_on_submit: la solicitud es un POST Y el formulario es válido
    if not form.validate_on_submit():
        # MOSTRAMOS el formulario DE NUEVO: valores ingresados (excepto las contraseñas),
        # y un mensaje bajo cada campo incorrecto (vea fragments/field.html)
        return render_template("registration/registration.html", form=form,
                               html5=html5_requested(),
                               error="The form contains errors.")
    return render_template("registration/welcome.html", form=form)
  • líneas 10–11: el parámetro [?html5=true] activa la validación en el navegador (véase más adelante);
  • línea 24: [validate_on_submit()] devuelve [True] si la solicitud es un POST y si el formulario es válido;
  • líneas 27–29: el formulario no válido se vuelve a mostrar: es el mismo objeto [form], que contiene lo ingresado por el usuario y los errores de cada campo. La variable [error] es un mensaje general que la plantilla muestra al pie de la página;
  • línea 30: el formulario válido: la página de bienvenida. (El ejemplo siguiente mostrará que es mejor redirigir después de un POST exitoso.)

4.7.3. Un campo reutilizable: templates/fragments/field.html

Todos los campos se muestran de la misma manera: una etiqueta, el campo de entrada y, en caso de error, la zona resaltada en rojo y el mensaje debajo. Una macro evita tener que escribir esto cinco veces:

{# un campo de entrada, con su etiqueta y su PRIMER mensaje de error.
   field.errors: la lista de los mensajes de error del campo; los atributos HTML5
   (required, maxlength, minlength, min, max) los escribe el propio WTForms,
   según los validadores del campo #}
{% macro field_row(field) %}
<div class="mb-2">
  {{ field.label(class="form-label") }}
  {{ field(class="form-control" ~ (" is-invalid" if field.errors else "")) }}
  {% if field.errors %}
  <div class="invalid-feedback">{{ field.errors[0] }}</div>
  {% endif %}
</div>
{% endmacro %}
  • línea 5: la macro recibe un campo del formulario;
  • línea 8: la clase [is-invalid], procedente de [Bootstrap], enmarca el campo en rojo. Se agrega si la lista de errores del campo, [field.errors], no está vacía;
  • líneas 9–11: el primer mensaje de error del campo, en un elemento [invalid-feedback] que [Bootstrap] muestra en rojo debajo de un campo [is-invalid].

4.7.4. Las vistas

{% extends "layout.html" %}
{% from "fragments/field.html" import field_row %}

{% block content %}
  <h1 class="h3">Registration</h1>
  {% if html5 %}
  <p>Browser validation <b>enabled</b> - <a href="/register">disable it</a></p>
  {% else %}
  <p>Browser validation <b>disabled</b> - <a href="/register?html5=true">enable it</a></p>
  {% endif %}
  {# novalidate: el navegador ignora los atributos required, min... y
     envía el formulario tal cual; solo el servidor valida #}
  <form method="post" action="{{ '/register?html5=true' if html5 else '/register' }}"
        {{- '' if html5 else ' novalidate' }}>
    {{ form.csrf_token }}
    {{ field_row(form.name) }}
    {{ field_row(form.email) }}
    {{ field_row(form.age) }}
    {{ field_row(form.password) }}
    {{ field_row(form.confirmation) }}
    <button class="btn btn-primary" type="submit">Register</button>
  </form>
{% endblock %}
  • líneas 13–14: 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. [{{-] elimina el espacio en blanco que precede a la etiqueta, de modo que el atributo quede pegado a la etiqueta [<form>];
  • líneas 16–20: una llamada a la macro por cada campo.
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Registration</title>
  <link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    <main>
      {% block content %}{% endblock %}
    </main>
    {# el error global, al final de la página, sobre un fondo rosa claro; [error] lo proporciona la acción #}
    {% if error %}
    <div class="error-area" role="alert">{{ error }}</div>
    {% endif %}
  </div>
</body>
</html>
  • líneas 15–17: el mensaje general, al pie de la página, en una zona cuyo estilo se define en [static/css/styles.css] (ejemplo 15). El atributo [role="alert"] lo señala a los lectores de pantalla.
1
2
3
4
5
6
7
8
{% extends "layout.html" %}

{% block content %}
  {# form.name.data: el valor del campo, después de filtros y conversión #}
  <h1 class="h3">Welcome {{ form.name.data }}</h1>
  <p>Your registration is saved: address <b>{{ form.email.data }}</b>,
    age <b>{{ form.age.data }}</b> years.</p>
{% endblock %}

[form.name.data] es el valor del campo después del filtrado y la conversión: el nombre sin espacios y la edad como entero.

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

Image

Lo ingresado se conservó (excepto las contraseñas) y cada error se indica debajo de su campo correspondiente. Con [curl], esta vez proporcionando el token anti-CSRF, también podemos enviar algo que un navegador no enviaría: una edad no numérica. El mensaje de conversión, generado por [WTForms], está en inglés, el idioma elegido por [locales]:

  <input class="form-control is-invalid" id="age" max="120" min="18" name="age" required type="number" value="abc">
  <div class="invalid-feedback">Not a valid integer value.</div>

También se ven los atributos HTML5 deducidos de los validadores: [required], [min], [max].

4.7.6. Validación en el navegador

Quitemos el atributo [novalidate] haciendo clic en el enlace “enable it” (parámetro [?html5=true]). Entonces el navegador comprueba por sí mismo los atributos [required], [type="email"], [min], [maxlength]... antes de enviar el formulario, y muestra sus propios mensajes:

Image

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 lado 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 en el navegador es solo una comodidad adicional.

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

Image

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

Cuando una acción POST responde con una página, esa página es el resultado de un POST. Si el usuario recarga la página (presiona [F5]), el navegador vuelve a enviar la solicitud POST, tras mostrar una advertencia que pocas personas leen: el comando se envía dos veces y el mensaje se publica dos veces. El patrón Post/Redirect/Get (PRG) evita este problema: una acción POST exitosa no devuelve una página; 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 la acción GET.

Aún queda un problema: la página GET quiere mostrar un mensaje (“la tarea se ha agregado”), pero quien conoce ese mensaje es la acción POST, y esta no puede pasar una variable a una solicitud que todavía no ha ocurrido. La solución: un mensaje flash, publicado por la acción POST, conservado hasta la siguiente solicitud, mostrado y luego descartado.

4.8.1. El servicio: services/tasks.py

# services/tasks.py: la lista de tareas, en memoria, compartida por todos
from threading import Lock

from flask import current_app


class TasksService:

    def __init__(self):
        self._tasks = ["Read chapter 3"]
        # varias solicitudes pueden ejecutarse AL MISMO TIEMPO (el servidor las atiende
        # en varios hilos): un candado (Lock) garantiza que un solo
        # hilo a la vez lea o modifique la lista
        self._lock = Lock()

    def list(self) -> list[str]:
        with self._lock:
            return list(self._tasks)  # una COPIA: el llamador no puede modificar la nuestra

    def add(self, label: str):
        with self._lock:
            self._tasks.append(label)


def tasks_service() -> TasksService:
    return current_app.extensions["tasks"]
  • Línea 14: la lista de tareas es compartida por todas las solicitudes. Sin embargo, el servidor de desarrollo procesa cada solicitud en un hilo distinto: dos solicitudes pueden ejecutarse al mismo tiempo y modificar la lista simultáneamente. Un cerrojo ([Lock], del módulo estándar [threading]) garantiza que un solo hilo a la vez ejecute el código que protege. El prefijo [_] indica, por convención, un atributo interno de la clase;
  • línea 17: la instrucción [with] adquiere el cerrojo, ejecuta el bloque y luego lo libera, incluso si el bloque lanza una excepción. Un hilo que encuentra el cerrojo adquirido espera hasta que se libere;
  • línea 18: el método devuelve una copia de la lista: quien lo llama puede recorrerla con seguridad mientras otro hilo agrega una tarea a la original.

4.8.2. El controlador: controllers/tasks.py

# controllers/tasks.py: el patrón Post / Redirect / Get
from flask import Blueprint, flash, redirect, render_template, request, url_for

from services.tasks import tasks_service

tasks = Blueprint("tasks", __name__, url_prefix="/tasks")


# GET /tasks: la lista y el formulario de alta
@tasks.get("")
def display():
    return render_template("tasks/tasks.html", tasks=tasks_service().list())


# POST /tasks: el patrón Post / Redirect / Get
@tasks.post("")
def add():
    label = request.form.get("label", "")
    text = label.strip()
    if not text or len(text) > 40:
        # entrada inválida: mostramos la página de nuevo, sin redirección
        return render_template("tasks/tasks.html", tasks=tasks_service().list(),
                               label=label,
                               error="The label must have 1 to 40 characters.")
    tasks_service().add(text)
    # un mensaje "flash": sobrevivirá a la redirección, para la SIGUIENTE solicitud
    flash(f"The task [{text}] has been added.")
    # ninguna página: una redirección a la página GET
    return redirect(url_for("tasks.display"))


# POST /tasks/without-prg: el contraejemplo (una página como respuesta al POST)
@tasks.post("/without-prg")
def add_without_prg():
    label = request.form.get("label", "").strip()
    tasks_service().add(label or "(untitled)")
    return render_template("tasks/tasks.html", tasks=tasks_service().list(),
                           without_prg=True)
  • líneas 18–24: la entrada se valida manualmente, sin [WTForms], para mantener el ejemplo simple. Una entrada no válida se vuelve a mostrar sin redirección: no hay nada que proteger contra un envío duplicado, ya que no se ha modificado nada;
  • línea 27: [flash] define un mensaje para la siguiente solicitud;
  • línea 29: la redirección a la página GET;
  • líneas 34–38: el contraejemplo: una página como respuesta a un POST.

4.8.3. Las vistas

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Tasks</title>
  <link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    {# los mensajes flash, en la parte superior de la página: dejados ANTES de la redirección;
       get_flashed_messages los devuelve y luego los olvida #}
    {% for message in get_flashed_messages() %}
    <div class="alert alert-success" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {% if error %}
    <div class="error-area" role="alert">{{ error }}</div>
    {% endif %}
  </div>
</body>
</html>
  • líneas 13–15: la función [get_flashed_messages()], disponible en todas las vistas, devuelve la lista de mensajes flash pendientes y luego los descarta: solo se mostrarán una vez. La clase [alert alert-success] de [Bootstrap] los muestra en un marco verde.
{% 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="/tasks" class="d-flex gap-2">
    <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="/tasks/without-prg">Add without PRG</button>
  </form>
  {% 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 14: el atributo [formaction] de un botón envía el formulario a una dirección distinta de la de su atributo [action]: así, un mismo formulario puede desencadenar dos acciones diferentes.

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

Entre la solicitud POST y la solicitud GET siguiente, el mensaje debe almacenarse en alguna parte. [Flask] lo guarda en la sesión del usuario (véase el capítulo sobre los ámbitos). De forma predeterminada, la sesión de [Flask] no se almacena en el servidor: se guarda en una cookie enviada al navegador, que la reenvía con cada solicitud. Para impedir que el usuario la altere, la cookie se firma con la clave secreta, y por eso [app.py] la define. Examinemos esto con [curl]. La opción [-c] guarda en un archivo las cookies recibidas, mientras que la opción [-b] devuelve las del archivo:

curl -i -c cookies.txt -d "label=Do%20the%20exercises" http://localhost:5000/tasks
1
2
3
4
5
6
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 199
Location: /tasks
Set-Cookie: session=eyJfZmxhc2hlcyI6W3siIHQiOlsibWVzc2FnZSIsIlRoZSB0YXNrIFtEbyB0aGUgZXhlcmNpc2VzXSBoYXMgYmVlbiBhZGRlZC4iXX1dfQ.arfKbA.72zBgSN6wiA_v1Ci_KS3Si8Brbc; HttpOnly; Path=/
...

La respuesta al POST es una redirección (código de estado 302, encabezado [Location]), acompañada de una cookie [session]. Su valor consta de tres partes separadas por puntos: los datos, codificados en Base64 (sin comprimir: [Flask] solo los comprime cuando así resultan más cortos); la fecha de la firma; y la firma. Una vez decodificados, los datos son legibles:

{"_flashes":[{" t":["message","The task [Do the exercises] has been added."]}]}

Por lo tanto, la sesión de una aplicación [Flask] es legible para el usuario (no está cifrada), pero a prueba de manipulaciones (está firmada): no se almacena nada secreto en ella. El atributo [HttpOnly] impide que el [JavaScript] de la página lea la cookie. Sigamos la redirección reenviando la cookie:

curl -i -b cookies.txt -c cookies.txt http://localhost:5000/tasks
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 885
Set-Cookie: session=; Expires=Thu, 01 Jan 1970 00:00:00 GMT; Max-Age=0; HttpOnly; Path=/
...
    <div class="alert alert-success" role="status">The task [Do the exercises] has been added.</div>
    <main>
  <h1 class="h3">My tasks</h1>
  <ol>
    <li>Read chapter 3</li>
    <li>Do the exercises</li>
  </ol>
...

El mensaje se muestra y la sesión, que ahora está vacía, se elimina: el servidor devuelve una cookie vacía cuya fecha de expiración ya pasó. Una nueva solicitud GET ya no mostraría el mensaje.

4.8.5. Ejecución

Agregar una tarea: el navegador siguió la redirección; la URL es la de 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 los enlaces libremente, 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 eliminaría todo. En una aplicación web:

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

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

4.9.1. El servicio: services/contacts.py

# services/contacts.py: los contactos, en memoria, compartidos por todos
from dataclasses import dataclass, replace
from threading import Lock

from flask import current_app


# un contacto: un identificador, un nombre, un número de teléfono
@dataclass(frozen=True)
class Contact:
    id: int
    name: str
    phone: str


class ContactsService:

    def __init__(self):
        self._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"),
        ]
        self._last_id = 3
        self._lock = Lock()

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

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

    def edit(self, id: int, name: str, phone: str) -> Contact | None:
        with self._lock:
            for i, contact in enumerate(self._contacts):
                if contact.id == id:
                    # un contacto es inmutable (frozen): replace construye uno
                    # nuevo, que reemplaza al anterior en la lista
                    self._contacts[i] = replace(contact, name=name, phone=phone)
                    return self._contacts[i]
            return None

    def add(self, name: str, phone: str) -> Contact:
        with self._lock:
            self._last_id += 1
            contact = Contact(self._last_id, name, phone)
            self._contacts.append(contact)
            return contact

    def delete(self, id: int) -> Contact | None:
        with self._lock:
            contact = next((c for c in self._contacts if c.id == id), None)
            if contact is not None:
                self._contacts.remove(contact)
            return contact


def contacts_service() -> ContactsService:
    return current_app.extensions["contacts"]

Un servicio en memoria, protegido por un cerrojo como el del ejemplo 20. Algunos puntos sobre [Python]:

  • línea 34: la expresión entre paréntesis es un generador (véase el ejemplo 05) de los contactos cuyo ID coincide con el que se busca; [next] devuelve el primer elemento, o el valor predeterminado [None] si no existe ninguno;
  • línea 38: [enumerate] recorre una lista y devuelve, para cada elemento, su índice y el elemento;
  • línea 42: un contacto es inmutable ([frozen=True]); la función [replace] del módulo [dataclasses] crea una copia de él con algunos atributos modificados;
  • Los métodos devuelven [None] para un contacto inexistente: le corresponde al controlador decidir la respuesta.

4.9.2. El controlador: controllers/contacts.py

# controllers/contacts.py: enlaces (GET) y botones (POST)
from flask import Blueprint, abort, flash, redirect, render_template, request, url_for

from services.contacts import contacts_service

contacts = Blueprint("contacts", __name__, url_prefix="/contacts")


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


# un ENLACE (<a href>): una solicitud GET, que no modifica nada
@contacts.get("")
def list_contacts():
    return render_template("contacts/list.html", contacts=contacts_service().list())


@contacts.get("/<int:id>")
def details(id):
    contact = contact_or_404(contacts_service().read(id))
    return render_template("contacts/details.html", contact=contact)


# un BOTÓN en un formulario POST: una solicitud que modifica datos
@contacts.post("/<int:id>")
def save(id):
    contact = contact_or_404(contacts_service().edit(
        id, request.form.get("name", ""), request.form.get("phone", "")))
    flash(f"The contact [{contact.name}] has been edited.")
    return redirect(url_for("contacts.list_contacts"))


# mismo formulario, otro botón (atributo formaction): otra acción
@contacts.post("/<int:id>/duplicate")
def duplicate(id):
    copy = contacts_service().add(request.form.get("name", "") + " (copy)",
                                  request.form.get("phone", ""))
    flash(f"The contact [{copy.name}] has been created.")
    return redirect(url_for("contacts.list_contacts"))


@contacts.post("/<int:id>/delete")
def delete(id):
    contact = contact_or_404(contacts_service().delete(id))
    flash(f"The contact [{contact.name}] has been deleted.")
    return redirect(url_for("contacts.list_contacts"))
  • líneas 10–13: una función utilitaria: un contacto inexistente detiene la acción con una respuesta 404;
  • líneas 17–23: las dos acciones GET, que no modifican nada: la lista y la ficha de un contacto;
  • líneas 29–34: guardado de la ficha: una acción POST que sigue el patrón PRG. La misma URL, [/contacts/2] , es atendida por dos acciones diferentes según el método: GET muestra, POST guarda;
  • Líneas 38–43: duplicación, otra acción POST, desencadenada por un segundo botón del mismo formulario;
  • líneas 46–50: eliminación.

4.9.3. Protección anti-CSRF: app.py

# app.py: la aplicación del ejemplo 21
from pathlib import Path

from flask import Blueprint, Flask

from flask_wtf.csrf import CSRFProtect

from controllers.contacts import contacts
from services.contacts import ContactsService

# Bootstrap, compartido por los ejemplos (vea el ejemplo 15)
BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    app.config["SECRET_KEY"] = "a-secret-key-for-example-21"
    app.extensions["contacts"] = ContactsService()
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(contacts)
    # protección anti-CSRF de Flask-WTF, para TODAS las solicitudes POST de
    # la aplicación: cada formulario debe devolver el token csrf_token()
    CSRFProtect(app)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • línea 26: en los ejemplos 18 y 19, era el formulario [WTForms] el que verificaba su token, en [validate()]. Aquí los formularios se escriben a mano, sin [WTForms]. [CSRFProtect] extiende la protección a toda la aplicación: antes de cada solicitud (POST, así como PUT, PATCH, DELETE), verifica el token y devuelve un código de estado 400 si falta o no es válido, incluso antes de llamar a la acción. Una acción no puede omitirlo. Esta es la configuración que usará el caso de estudio.

4.9.4. Las vistas

{% 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_for coloca el id en la ruta: /contacts/2 #}
          <a class="btn btn-sm btn-outline-primary" href="{{ url_for('contacts.details', id=contact.id) }}">View</a>
          {# delete: un formulario POST, cuyo envío será confirmado #}
          <form method="post" class="d-inline" action="{{ url_for('contacts.delete', id=contact.id) }}"
                data-confirmation="Delete the contact {{ contact.name }}?">
            {# el token anti-CSRF, requerido por CSRFProtect (véase app.py) #}
            <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
            <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 botón mediante las clases de [Bootstrap] ([btn]...): la apariencia no tiene nada que ver con el método HTTP. [url_for('contacts.details', id=contact.id)] coloca el ID en la ruta: [/contacts/2];
  • líneas 15–20: un formulario POST por cada botón “Eliminar”, sin más campos que el token. 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 predefinido y están destinados al [JavaScript] de la página;
  • línea 18: la función [csrf_token()], proporcionada a las vistas por [Flask-WTF], devuelve el token anti-CSRF de la sesión; se coloca en un campo oculto llamado [csrf_token].
{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Contact no. {{ contact.id }}</h1>
  <form method="post" action="{{ url_for('contacts.save', id=contact.id) }}">
    <input type="hidden" name="csrf_token" value="{{ csrf_token() }}">
    <div class="mb-2">
      <label class="form-label" for="name">Name</label>
      <input class="form-control" id="name" name="name" value="{{ contact.name }}">
    </div>
    <div class="mb-3">
      <label class="form-label" for="phone">Phone</label>
      <input class="form-control" id="phone" name="phone" value="{{ contact.phone }}">
    </div>
    {# dos botones de envío para el mismo formulario #}
    <button class="btn btn-primary" type="submit">Save</button>
    <button class="btn btn-outline-primary" type="submit"
            formaction="{{ url_for('contacts.duplicate', id=contact.id) }}">Duplicate</button>
    <a class="btn btn-link" href="{{ url_for('contacts.list_contacts') }}">Back to the list</a>
  </form>
{% endblock %}
  • líneas 16–18: dos botones de envío para el mismo formulario: “Guardar” envía el formulario a la dirección indicada por su atributo [action] y “Duplicar” lo envía a la dirección indicada por su atributo [formaction] (ejemplo 20);
  • línea 19: regreso a la lista: un enlace.

4.9.5. La ventana de confirmación

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

{# una sola ventana para toda la página, oculta (d-none) al inicio #}
<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 y, a continuación, la ventana, se generan con 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>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Contacts</title>
  <link rel="stylesheet" href="{{ url_for('bootstrap.static', filename='css/bootstrap.min.css') }}">
  <link rel="stylesheet" href="{{ url_for('static', filename='css/styles.css') }}">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    {% for message in get_flashed_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="{{ url_for('static', filename='js/app.js') }}"></script>
</body>
</html>
  • línea 19: la ventana, incluida en todas las páginas;
  • línea 21: el script, colocado al final de la página: cuando se ejecuta, los elementos que busca ya existen.

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 que requieren confirmación
  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 demás 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–14: para cada formulario que tiene un atributo [data-confirmation], se intercepta el evento [submit], que se dispara cuando se envía el formulario. [preventDefault()] suspende el envío; el formulario queda en espera y su mensaje ([dataset.confirmation], el valor del atributo [data-confirmation]) se muestra en la ventana, que aparece;
  • líneas 19–25: 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 con el método [submit()], que, a diferencia de hacer clic en un botón, no desencadena el evento [submit] (de lo contrario, la ventana reaparecería); “No” oculta la ventana.

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

4.9.6. 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, el POST, la redirección y el mensaje emergente:

Image

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

Image

Una solicitud POST sin token anti-CSRF es rechazada por [CSRFProtect], y un contacto inexistente devuelve un error 404:

curl -i -X POST http://localhost:5000/contacts/2/delete
curl -i http://localhost:5000/contacts/9
HTTP/1.1 400 BAD REQUEST
Content-Type: text/html; charset=utf-8
Content-Length: 117

<!doctype html>
<html lang=en>
<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>The CSRF token is missing.</p>
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 102

<!doctype html>
<html lang=en>
<title>404 Not Found</title>
<h1>Not Found</h1>
<p>unknown contact</p>

Las páginas de error siguen siendo las de [Werkzeug], en inglés. El capítulo sobre el ciclo de vida de una solicitud mostrará cómo reemplazarlas por páginas personalizadas.