Skip to content

4. A view e seu modelo

Até agora, as actions geravam suas próprias respostas: texto, JSON e algumas tags HTML escritas em uma string. Em uma aplicação MVC, esse é o papel de uma view: um arquivo que descreve a página HTML, com marcadores para os dados que a action lhe passa — o modelo da view.

[Flask] vem com uma engine de views, o [Jinja2], escrito pela mesma equipe (o projeto *Pallets*). Outras engines podem ser usadas ([Mako], [Chameleon]...), mas [Jinja2] é de longe a mais usada em [Python]: ele é encontrado no [Django] (como opção), no [Ansible], em geradores de sites estáticos... É o que usamos neste curso.

Uma view [Jinja2] (a documentação a chama de *template*, um modelo de página) é um arquivo de texto — neste caso, HTML — no qual três tipos de tags são interpretados no servidor:

  • [{{ expression }}]: o valor de uma expressão, inserido na página;
  • [{% instruction %}]: uma instrução: condição ([if]), laço ([for]), herança de template ([extends], [block]), inclusão ([include]), macro...;
  • [{# comment #}]: um comentário que não aparece na página gerada.

Todo o resto é copiado como está. A sintaxe das expressões é semelhante à do [Python]. Isso difere do [Thymeleaf], a engine de views do curso de [Spring MVC], cujas views são arquivos HTML válidos enriquecidos com atributos [th:]; em vez disso, aproxima o [Jinja2] do [Razor] ([ASP.NET Core MVC]), que mistura HTML e código. Por padrão, o [Flask] procura as views na pasta [templates] da aplicação.

4.1. Exemplo 13: uma primeira view

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

4.1.1. O modelo da view: models/page.py

1
2
3
4
5
6
7
8
9
# models/page.py: o modelo da view, os dados que a ação passa para a view
from dataclasses import dataclass


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

O modelo da view é uma simples [dataclass] (veja o Exemplo 06): as três informações que a view exibirá. Não há obrigação de definir o modelo de uma view como uma classe: três variáveis separadas poderiam ser passadas à view. No entanto, uma classe documenta o que a view espera e permite que o editor verifique o código da action. Essa é a abordagem que o estudo de caso seguirá, em que cada view tem sua própria classe de modelo.

4.1.2. O controller: controllers/views.py

# controllers/views.py: ações que retornam uma VIEW
from datetime import datetime

from flask import Blueprint, render_template

from models.page import PageModel

views = Blueprint("views", __name__)


# render_template: a engine Jinja2 constrói a página a partir da view
# templates/views/index.html e das variáveis passadas como parâmetros nomeados
# (aqui uma só, [model]); a página produzida é a resposta da ação
@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)


# a mesma view com outro modelo; ou outra view, com o código 404
@views.get("/hello/<name>")
def hello(name):
    if name == "unknown":
        # uma tupla (página, código): a página, enviada com o 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)
  • linha 4: importa a função [render_template];
  • linhas 16–19: a action constrói o modelo da view. [datetime.now().strftime("%H:%M:%S")]: a hora atual, formatada (veja o Exemplo 12);
  • linha 20: [render_template] instrui o [Jinja2] a gerar a página: o primeiro parâmetro é o caminho da view, relativo à pasta [templates]; os parâmetros nomeados seguintes são as variáveis da view; neste caso, há apenas uma: [model]. [render_template] retorna o texto da página gerada, que se torna a resposta da action (do tipo [text/html]);
  • linha 28: outra view, com uma variável diferente ([name]). A tupla [(page, 404)] envia a página com o código de status 404 (veja o Exemplo 03): uma página de erro personalizada;
  • Linhas 29–33: a mesma view da action [index], com um modelo diferente. Esse é o benefício de separar as actions das views: uma única view pode ser usada por várias actions.

4.1.3. A view: templates/views/index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  {# {{ ... }}: o valor de uma expressão, inserido na 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>
  • linha 5: um comentário [Jinja2];
  • Linha 6: [{{ model.title }}] insere o valor do atributo [title] da variável [model]. A notação de ponto do [Jinja2] é mais flexível que a do [Python]: [model.title] procura primeiro um atributo [title] e, se não o encontrar, uma chave ["title"] (se [model] for um dicionário). O código da view, portanto, não precisa saber se seu modelo é um objeto ou um dicionário.

Tudo o que é inserido por [{{ }}] é escapado: os caracteres [<], [>], [&], ["] e ['] são substituídos por suas entidades HTML. Esse é o papel que a função [escape] desempenhava no Exemplo 09, mas desta vez é automático: o [Flask] ativa o escape automático (*autoescape*) para as views cujos nomes terminam em [.html], [.htm], [.xml], [.xhtml], ou [.svg]. Isso evita que uma view insira, sem querer, na página um HTML fornecido por um usuário.

4.1.4. A view: 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>

Uma view não é obrigada a receber um objeto: a variável [name] é uma string.

4.1.5. Execução

Image

Image

A resposta bruta mostra o trabalho feito pelo [Jinja2]: as tags [{{ }}] foram substituídas por seus valores, e o comentário desapareceu (resta uma linha vazia em seu lugar; veremos no próximo exemplo como evitá-la).

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>

A página de erro “personalizada”, seguida de um nome contendo HTML ([<b>martin], codificado na 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>
...

A tag [<b>] foi escapada sem que nenhuma action ou view precisasse intervir.

4.2. Exemplo 14: a linguagem Jinja2

Este exemplo combina as principais construções do [Jinja2] em uma única view.

4.2.1. O modelo e a action

# models/basics.py: o modelo da view do exemplo 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

O modelo contém valores de vários tipos: strings, [None], booleanos, listas de objetos, listas vazias e objetos que contêm outros objetos. O tipo [Decimal], do módulo padrão [decimal], representa números decimais com exatidão (ao contrário do tipo [float], para o qual [0.1 + 0.2] é igual a [0.30000000000000004]); é o tipo a usar para valores monetários.

# controllers/basics.py: uma view que usa as principais construções do 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)

A action constrói o modelo e o passa à view. [Decimal("12.5")]: um decimal é construído a partir de uma string para evitar o uso de um [float] impreciso.

4.2.2. Configuração: app.py

# app.py: a aplicação do exemplo 14
from flask import Flask

from controllers.basics import basics


def create_app():
    app = Flask(__name__)
    # as tags {% ... %} não deixam linhas em branco na página produzida:
    # trim_blocks remove a quebra de linha que segue uma tag, lstrip_blocks os
    # espaços que a precedem na sua linha
    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)
  • Linhas 12–13: [app.jinja_env] é o ambiente [Jinja2] da aplicação — o objeto que carrega e executa as views. Por padrão, uma tag [{% %}] sozinha em sua linha deixa na página gerada os espaços que a precedem e a quebra de linha que a segue: um laço produziria numerosas linhas vazias. [trim_blocks] remove a quebra de linha que segue uma tag, enquanto [lstrip_blocks] remove os espaços que a precedem. Essas duas configurações não afetam a exibição da página (o navegador ignora esses espaços em branco), mas tornam o HTML gerado mais legível. Todos os exemplos seguintes as ativam.

4.2.3. A view: templates/basics/index.html

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{ model.title }}</title>
</head>
<body>
  {# {% set %}: uma variável da view; os filtros (|) transformam um valor #}
  {% set total = model.products | sum(attribute="price") %}
  {% set count = model.products | length %}
  <h1>{{ model.title }}</h1>
  {# 1. exibe um valor do modelo; None é exibido... "None": o filtro
        default(text, true) substitui um valor vazio ou None. Este comentário
        Jinja2 não aparece na página produzida #}
  <p>1. Name: {{ model.name }} - nickname: [{{ model.nickname }}] [{{ model.nickname | default("", true) }}]</p>
  {# 2. {{ }} escapa o HTML; o filtro safe o insere como está #}
  <p>2a. {{ model.html }}</p>
  <p>2b. {{ model.html | safe }}</p>
  {# 3. uma condição #}
  {% if model.logged_in %}
  <p>3. You are logged in.</p>
  {% else %}
  <p>3. You are not logged in.</p>
  {% endif %}
  {# 4. um laço: [loop] descreve o estado do laço #}
  <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. a lista vazia: o bloco else de um laço for #}
  <p>5. Your cart:
    {% for p in model.cart %}<span>{{ p.name }}</span>{% else %}it is empty.{% endfor %}
  </p>
  {# 6. expressões calculadas, as variáveis definidas com set e o filtro format #}
  <p>6. {{ count }} products, for a total of {{ total }} {{ model.currency }};
    average price: {{ "%.2f" | format(total / count) }} {{ model.currency }}</p>
  {# 7. um objeto dentro de um objeto e um método Python (upper) #}
  <p>7. Address: {{ model.address.street }}, {{ model.address.city.upper() }}</p>
  <p>8. An email address: contact@example.com</p>
</body>
</html>
  • Linhas 9–10: [{% set %}] cria uma variável da view. Os filtros transformam um valor: [value | filter] ou [value | filter(parameters)]. O filtro [sum(attribute="price")] soma os atributos [price] dos elementos de uma lista; o filtro [length] retorna o comprimento de uma lista. [Jinja2] fornece cerca de cinquenta filtros: [upper], [lower], [title], [trim], [join], [sort], [round], [default], [replace], [truncate]... ;
  • linha 15: o valor [None] é exibido... [None]. O filtro [default(value, true)] substitui um valor “vazio” ([None], string vazia, zero) pelo valor especificado; sem o segundo parâmetro [true], ele substituiria apenas uma variável indefinida;
  • linhas 17–18: [{{ }}] escapa o HTML (2a); o filtro [safe], por sua vez, declara que o valor é um HTML seguro, a ser inserido como está (2b). [safe] é reservado ao HTML gerado pela própria aplicação, nunca a dados digitados por usuários;
  • linhas 20–24: uma condição: [{% if %}], [{% elif %}], [{% else %}], [{% endif %}]. Diferentemente do [Python], cujos blocos são delimitados pela indentação, o [Jinja2] fecha cada bloco com uma tag [end...];
  • linhas 28–34: um laço [{% for %}] ... [{% endfor %}]. Dentro do laço, a variável especial [loop] descreve o estado do laço: [loop.index] (o número da iteração, começando em 1), [loop.index0] (começando em 0), [loop.first], [loop.last] (verdadeiros na primeira e na última iteração), [loop.length] (o número de elementos). As variáveis externas ao laço ([model.name]) continuam acessíveis;
  • linha 30: a expressão condicional do [Python], [a if condition else b], também é a do [Jinja2];
  • Linha 38: um laço [for] pode conter um bloco [{% else %}], que é executado se a lista estiver vazia. Isso é mais simples do que um [if] que verificasse o comprimento da lista;
  • Linhas 41–42: expressões calculadas ([total / count]). O filtro [format] aplica um formato semelhante ao do operador [%] do [Python]: ["%.2f"] exibe um número com duas casas decimais. No Exemplo 16, veremos uma maneira muito melhor de formatar números e valores monetários;
  • linha 44: a notação de ponto percorre objetos ([model.address.city]) e permite chamar seus métodos: [upper()] é um método das strings [Python];
  • linha 45: um endereço de e-mail, escrito como está. O caractere [@], que tem um significado específico em outras engines de views ([Razor]), não tem esse significado no [Jinja2]: apenas as tags [{{ }}], [{% %}], e [{# #}] são interpretadas.

4.2.4. Execução

Image

A página gerada:

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

Os comentários desapareceram, e as tags [{% %}] não deixaram nenhuma linha em branco. A formatação de certas linhas (“[- the first one </li>]”) mostra que [trim_blocks] e [lstrip_blocks] também afetam tags colocadas no meio de uma linha; isso não tem efeito no navegador.

4.3. Exemplo 15: template, fragmentos, arquivos estáticos

As páginas de um site costumam compartilhar a mesma estrutura: um cabeçalho, uma barra de navegação, um rodapé e as mesmas folhas de estilo. Em vez de repetir essa estrutura em cada view, ela é escrita uma única vez em um template (*layout*), que as páginas estendem. Este exemplo também usa o [Bootstrap], o framework CSS mais usado, para a estilização.

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. Arquivos estáticos

Uma página HTML referencia outros arquivos: folhas de estilo, scripts [JavaScript] e imagens. Esses arquivos, que o servidor envia como estão, são chamados de arquivos estáticos. [Flask] serve automaticamente o conteúdo da pasta [static] da aplicação sob a URL [/static/...]: o arquivo [static/css/styles.css] está disponível na URL [/static/css/styles.css].

/* alguns ajustes além do Bootstrap */
body {
  background-color: #f5f7fa;
}

/* o rodapé do layout */
.footer {
  margin-top: 2rem;
  font-size: 0.85rem;
  color: #6c757d;
}

/* as mensagens de erro, no final da página, sobre um fundo 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;
}

Algumas regras CSS adicionais além do [Bootstrap]: um fundo cinza-claro, o estilo do rodapé e o estilo de uma área de erro que será usada nos exemplos seguintes.

[Bootstrap], por sua vez, é usado pelos exemplos 15 a 28. Em vez de colocar uma cópia na pasta [static] de cada um, os exemplos o compartilham: ele fica na pasta [examples/common/bootstrap]. É preciso, portanto, instruir o [Flask] a usar também essa pasta. É a finalidade das linhas seguintes em [app.py]:

# app.py: a aplicação do exemplo 15
from datetime import date
from pathlib import Path

from flask import Blueprint, Flask, request

from controllers.pages import pages

# Bootstrap, compartilhado pelos exemplos: a pasta examples/common/bootstrap,
# indicada a partir da localização DESTE arquivo (e não da pasta atual)
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
    # um blueprint sem rotas, que apenas serve arquivos estáticos: a pasta
    # BOOTSTRAP, sob a URL /bootstrap/...
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    app.register_blueprint(pages)

    # um "context processor": executado antes de construir CADA view,
    # ele adiciona suas variáveis ao modelo de todas as views
    @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)
  • Linha 11: o caminho da pasta [common/bootstrap]. [Path], do módulo padrão [pathlib], representa o caminho de um arquivo. [Path(__file__)] é o caminho do próprio arquivo [app.py] ([__file__] é uma variável que o [Python] define em cada módulo); [resolve()] o torna absoluto; [parent] refere-se à pasta que o contém ([15-layout]), [parent.parent] refere-se à pasta acima dela ([examples]); o operador [/] acrescenta um elemento ao caminho. Especificar a pasta com base na localização do arquivo — e não na pasta atual — permite iniciar a aplicação de qualquer pasta;
  • linhas 20–21: um blueprint pode ter sua própria pasta de arquivos estáticos ([static_folder]), servida sob a URL especificada ([static_url_path]). Essa pasta contém apenas isso: não tem rotas. O arquivo [common/bootstrap/css/bootstrap.min.css] é, assim, servido na URL [/bootstrap/css/bootstrap.min.css];
  • Linhas 26–28: um context processor é uma função que o [Flask] executa antes de cada view ser gerada. Ela retorna um dicionário, cujos pares chave-valor são adicionados às variáveis da view. Aqui, [path] (o caminho da URL requisitada) e [year] (o ano atual) ficam assim disponíveis em todas as views, sem que as actions precisem fornecê-los. O template os usa no rodapé.

4.3.2. O template: templates/layout.html

<!doctype html>
{# o layout das páginas: as páginas o ESTENDEM e preenchem seus blocos #}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {# um bloco: um espaço que a página pode preencher; aqui com um conteúdo padrão #}
  <title>{% block title %}Home{% endblock %} - My site</title>
  {# url_for constrói a URL de um arquivo 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">
    {# inserção do arquivo fragments/navbar.html #}
    {% include "fragments/navbar.html" %}
    <main>
      {# o conteúdo da página solicitada pela action é inserido aqui #}
      {% block content %}{% endblock %}
    </main>
    {# path, year: adicionados ao modelo de todas as views (veja app.py) #}
    <footer class="footer">Page [{{ path }}] - © {{ year }}</footer>
  </div>
</body>
</html>
  • linha 6: a tag [viewport] instrui os navegadores móveis a exibir a página na largura da tela, que é o que o [Bootstrap] espera;
  • linha 8: um bloco é um contêiner nomeado que as páginas que estendem o template podem preencher. O conteúdo escrito entre [{% block title %}] e [{% endblock %}] é o conteúdo padrão do bloco, usado por uma página que não o sobrescreve;
  • linhas 10–11: [url_for], que já conhecemos das actions (exemplo 04), também gera a URL de um arquivo estático: [static] refere-se à pasta estática da aplicação, [bootstrap.static] à do blueprint [bootstrap]; [filename] é o caminho do arquivo dentro dessa pasta. [url_for] está disponível em todas as views. Digitar a URL manualmente ([/static/css/styles.css]) também funcionaria, mas [url_for] se adapta se a pasta for movida ou se a aplicação for instalada sob um prefixo de URL;
  • linha 16: [{% include %}] insere o conteúdo de outra view, neste caso a barra de navegação. A view incluída tem acesso às variáveis da view que a inclui;
  • linha 19: o bloco que cada página preenche com seu próprio conteúdo. Por padrão, ele é vazio;
  • linha 22: o rodapé usa as duas variáveis do context processor.

A classe [container] do [Bootstrap] centraliza o conteúdo e limita sua largura; [py-3] adiciona um espaçamento interno vertical: o [Bootstrap] fornece centenas de classes desse tipo, que são combinadas no atributo [class].

4.3.3. A barra de navegação: templates/fragments/navbar.html

1
2
3
4
5
6
7
8
9
{# um fragmento: um pedaço de página, inserido por {% 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>

Um fragmento: uma parte de uma página que não tem sentido sozinha. As classes [navbar], [navbar-brand] e [nav-link] são as da barra de navegação do [Bootstrap].

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

1
2
3
4
5
6
7
8
9
{# uma MACRO: um pedaço de página que tem parâmetros, como uma função #}
{% 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 %}
  • Linhas 2–9: uma macro é um fragmento de página que tem parâmetros; esse é um recurso do [Jinja2]. Chamá-la — [{{ card("name", "role") }}] — insere o fragmento de página gerado com esses valores. Os parâmetros podem ter um valor padrão, como no [Python]: [{% macro card(name, role="") %}]. O cartão ([card]) é um componente do [Bootstrap].

4.3.5. As páginas

{# esta página ESTENDE o layout: ela só fornece o conteúdo de seus blocos #}
{% extends "layout.html" %}
{# a macro [card] do arquivo 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>
  {# a chamada da macro, com dois parâmetros escritos na hora #}
  {{ card("A macro", "called with parameters written on the spot") }}
{% endblock %}
  • Linha 2: a página estende o template: o [Jinja2] gera a página do template, substituindo seus blocos pelos redefinidos pela página. [{% extends %}] deve ser a primeira tag da view. Em uma view que estende um template, o texto escrito fora dos blocos não aparece na página gerada (no entanto, as instruções [{% set %}] mantêm ali o seu efeito; veremos isso no capítulo sobre internacionalização);
  • linha 4: a importação da macro [card], definida em outro arquivo;
  • linha 6: o bloco [content] do template, redefinido. A página não redefine o bloco [title]: ele mantém seu conteúdo padrão, “Home”;
  • Linha 11: a chamada da 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">
      {# a macro recebe o nome e o papel do membro atual #}
      {{ card(member.name, member.role) }}
    </div>
    {% endfor %}
  </div>
{% endblock %}
  • linha 4: esta página também redefine o título;
  • linhas 9–14: um cartão por membro da equipe, em uma grade que usa o [Bootstrap] ([row], [col-md-4]: três colunas em uma tela média ou grande, uma coluna em um celular).

O controller não traz nenhuma novidade:

# controllers/pages.py: três páginas
from dataclasses import dataclass

from flask import Blueprint, render_template

pages = Blueprint("pages", __name__)


# um membro da equipe
@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 fim, a terceira página não usa o template:

<!doctype html>
{# esta view não usa o layout: é uma 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. Execução

Image

Image

Image

A página da equipe, como recebida pelo 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>

O navegador recebeu uma página completa: o template, o fragmento, a página e as macros foram montados no servidor. As URLs das folhas de estilo foram calculadas por [url_for]. É possível verificar se o arquivo do [Bootstrap] está sendo servido corretamente (a opção [-I] do [curl] exibe apenas os cabeçalhos da resposta):

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. Exemplo 16: helpers

Uma view frequentemente precisa formatar valores: um valor monetário com sua moeda, uma data por extenso ou um texto em maiúsculas. Esse código não pertence à action (que não cuida da apresentação) e seria trabalhoso de escrever na view. Em vez disso, ele é escrito em [Python], em funções que as views chamam: são os helpers da view. [Jinja2] reconhece três tipos: filtros ([{{ price | money }}]), funções globais ([{{ uppercase(name) }}]) e macros, que já conhecemos.

4.4.1. Funções: helpers/formats.py

# helpers/formats.py: funções chamadas pelas views
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()


# um valor em uma moeda, no formato do idioma da requisição (g.locale,
# veja app.py): 1149.9 -> "€1,149.90" em inglês, "1 149,90 €" em francês.
# A biblioteca Babel conhece as convenções de cada país
def money(amount: Decimal, currency: str = "EUR") -> str:
    return format_currency(amount, currency, locale=g.locale)


# uma data por extenso, no idioma da requisição: "Saturday, September 26, 2026"
def long_date(day: date) -> str:
    return format_date(day, format="full", locale=g.locale)
  • linhas 11–12: uma função comum que aceita [None];
  • Linhas 18–19: formatação de um valor monetário. Isso depende do idioma: em francês, [1 149,90 €] (espaço para separar os milhares, vírgula decimal, símbolo após o valor); em inglês, [€1,149.90]. A biblioteca [Babel] oferece suporte às convenções de todos os países (ela usa os dados do projeto Unicode *CLDR*): [format_currency(amount, currency, locale=...)] formata um valor monetário, com a moeda designada por seu código internacional ([EUR], [USD]). O locale ([fr_FR], [en_US]) especifica um idioma e um país. Aqui, ele é lido de [g.locale], que examinaremos a seguir;
  • linhas 23–24: [format_date] formata uma data; o formato [full] a escreve por extenso, incluindo o dia da semana.

4.4.2. A configuração: app.py

# app.py: a aplicação do exemplo 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)

    # o idioma de formatação de cada requisição: o parâmetro ?lang=fr da URL,
    # inglês caso contrário. before_request: uma função executada antes de CADA
    # ação; [g]: um objeto que vive durante uma requisição
    @app.before_request
    def set_language():
        g.locale = "fr_FR" if request.args.get("lang") == "fr" else "en_US"

    # FILTROS "caseiros": {{ price | money }}, {{ day | long_date }}
    app.add_template_filter(formats.money)
    app.add_template_filter(formats.long_date)
    # uma FUNÇÃO global, que pode ser chamada em todas as views: {{ uppercase(name) }}
    app.add_template_global(formats.uppercase)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Linhas 23–25: o idioma de formatação depende da requisição: o parâmetro [?lang=fr] da URL seleciona o francês; o inglês é o idioma padrão. [@app.before_request] registra uma função que o [Flask] executa antes de cada action (o capítulo sobre o ciclo de vida da requisição detalhará esses “hooks”). Ela armazena o locale em [g], um objeto do [Flask] que, assim como [request], é específico da requisição atual: é possível guardar nele o que se quiser ([g.locale = ...]); ele é descartado no fim da requisição. Essa é a maneira de compartilhar informações entre as diferentes funções que processam a mesma requisição, sem passá-las como parâmetro de uma para a outra. O capítulo sobre escopos de dados voltará a esse tema;
  • linhas 28–29: registro de duas funções como filtros do [Jinja2] com seus nomes. Um filtro recebe como primeiro parâmetro o valor colocado antes de [|]; os parâmetros seguintes são os do filtro: [{{ price | money("USD") }}] chama [money(price, "USD")];
  • Linha 31: registro de uma função como função global das views.

O decorador [@app.template_filter()] (aplicado à própria função) é outra maneira de registrar um filtro. Chamar [add_template_filter] a partir de [app.py] tem a vantagem de manter o módulo [helpers/formats.py] independente do [Flask] (com exceção de [g]).

4.4.3. O controller: controllers/pages.py

# controllers/pages.py: duas 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),
    ])

As actions passam valores brutos às views: uma [date], alguns [Decimal]. A formatação fica a cargo das views.

4.4.4. As views

{# uma macro: um link da barra de navegação, que recebe a classe [active]
   se a página atual estiver sob o caminho [href]. [request]: a requisição
   atual, que o Flask disponibiliza a todas as views #}
{% 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. uma condição escrita na view #}
    <a class="nav-link{% if request.path == '/' %} active{% endif %}" href="/">Home</a>
    {# 2. a macro [link] #}
    {{ link("/products", "Products") }}
    {# 3. url_for constrói a URL de uma action; um parâmetro que não é uma
          variável de caminho é adicionado no final da URL: /products?lang=fr #}
    <a class="nav-link" href="{{ url_for('pages.products', lang='fr') }}">Produits (fr)</a>
  </div>
</nav>
  • Linhas 4–7: uma macro que cria um link para a barra de navegação. O link da página atual recebe a classe [active] do [Bootstrap], que o destaca. A variável [request] (a requisição atual) está disponível em todas as views, assim como [g], [url_for], e [session] (veja o capítulo sobre escopos). A expressão condicional da linha 5 trata separadamente a página inicial, cujo caminho, [/], é o ponto de partida de todos os outros;
  • linha 6: uma expressão condicional sem [else] retorna uma string vazia se a condição for falsa;
  • linha 13: a mesma coisa, escrita diretamente na view, sem macro. A macro evita repetir a condição para cada link;
  • linha 18: um parâmetro de [url_for] que não é uma variável do caminho da rota é adicionado à URL como parâmetro: [/products?lang=fr].
1
2
3
4
5
6
{# um badge do Bootstrap: verde se o produto está em estoque, vermelho caso contrário #}
{% 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 %}
  • Linha 3: um badge do [Bootstrap], verde ([text-bg-success]) ou vermelho ([text-bg-danger]), conforme o estoque;
  • Linha 4: o operador [~] do [Jinja2] concatena dois valores convertendo-os em strings ([+] se recusaria a somar um inteiro e uma string). Os hifens em [{{-] e [-}}] removem os espaços em branco (espaços e quebras de linha) que precedem ou seguem a tag: o texto do badge fica, assim, colado às suas tags.
{% extends "layout.html" %}
{% block title %}Home{% endblock %}

{% block content %}
  <h1>Home</h1>
  {# o filtro "artesanal" long_date #}
  <p>Today is {{ today | long_date }}.</p>
  {# g: o objeto da requisição atual, também acessível nas views #}
  <p>Formatting language: {{ g.locale }}
    (<a href="/?lang=fr">in French</a>, <a href="/">in English</a>)</p>
{% endblock %}
  • linha 7: a chamada ao filtro “personalizado”;
  • linha 9: o objeto [g] é acessível nas views.
{% 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>
        {# uma função global, depois um filtro, sem e depois com um parâmetro #}
        <td>{{ uppercase(product.name) }}</td>
        <td>{{ product.price | money }}</td>
        <td>{{ product.price | money("USD") }}</td>
        {# a macro [badge] constrói o HTML do badge #}
        <td>{{ badge(product.stock) }}</td>
      </tr>
      {% endfor %}
    </tbody>
  </table>
{% endblock %}
  • Linha 13: a chamada à função global;
  • linhas 14–15: o filtro [money], primeiro com sua moeda padrão e depois com um parâmetro;
  • linha 17: a chamada à macro importada.

O template [layout.html] é uma versão simplificada do template do Exemplo 15.

4.4.5. Execução

Image

Image

A mesma página, com o parâmetro [?lang=fr]. Apenas a formatação dos números muda: o texto em si está escrito diretamente nas views. O capítulo sobre internacionalização também traduzirá o texto.

Image

Um trecho do HTML produzido:

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. Exemplo 17: um formulário GET

Um formulário HTML envia seus campos ao servidor de duas maneiras, conforme seu atributo [method]:

  • [method="get"]: os campos são adicionados à URL como parâmetros ([/search?keyword=le&genre=novel]). É o método usado por um formulário que faz uma consulta: uma busca ou um filtro. A URL que contém os resultados pode ser salva nos favoritos, compartilhada ou recarregada com segurança;
  • [method="post"]: os campos são incluídos no corpo da requisição (veja o Exemplo 11). É o método usado por um formulário que modifica dados: um cadastro, uma inclusão ou uma exclusão.

Este primeiro formulário é uma busca de livros.

4.5.1. O modelo: models/books.py

# models/books.py: um livro, e o modelo da view
from dataclasses import dataclass


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


# o modelo da view: a entrada (para exibi-la de novo), os gêneros, os resultados
@dataclass
class SearchModel:
    keyword: str
    genre: str
    genres: list[str]
    results: list[Book]
  • Linha 5: [frozen=True] torna os objetos [Book] imutáveis: depois de criados, seus atributos não podem mais ser modificados. É uma boa prática para dados compartilhados por todas as requisições, como a lista de livros;
  • linhas 14–18: o modelo da view contém o que o usuário digitou — para que o formulário possa exibi-lo novamente —, a lista de gêneros sugeridos e os resultados.

4.5.2. O controller: controllers/books.py

# controllers/books.py: um formulário de busca, 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 / e GET /search?keyword=...&genre=...: o formulário E seus resultados.
# Dois decoradores: duas rotas para a mesma ação
@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))
  • linhas 8–16: os dados, escritos diretamente no código para este exemplo. [BOOKS] é uma tupla (entre parênteses), uma sequência imutável. Por convenção, nomes em maiúsculas indicam constantes;
  • linhas 21–22: dois decoradores de rota na mesma action: ela responde às duas URLs. Na primeira visita ([/]), não há parâmetros: todos os livros são exibidos;
  • linhas 24–25: os campos do formulário são lidos como parâmetros da URL (exemplo 07). O segundo parâmetro de [get] é o valor padrão;
  • linhas 27–29: filtragem por meio de uma compreensão de lista com uma condição ([if]): um livro é selecionado se a palavra-chave estiver vazia ou aparecer em seu título ou autor (em minúsculas dos dois lados), e se o gênero estiver vazio ou corresponder ao gênero do livro;
  • linha 31: o modelo da view.

4.5.3. A view: templates/books/search.html

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">Book search</h1>
  {# method="get": os campos são enviados na 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: o campo exibe novamente o que foi digitado (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: um atributo booleano, escrito se a condição for verdadeira, omitido caso contrário #}
        <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 %}
  • linha 6: a tag [<form>]. O atributo [action] é a URL para a qual o formulário é enviado; [method="get"] coloca os campos na URL. As classes do [Bootstrap] dispõem os campos em uma única linha;
  • Linha 8: um rótulo. Seu atributo [for] especifica o identificador ([id]) do campo que ele descreve: clicar no rótulo coloca o cursor no campo, e os leitores de tela leem o rótulo junto com o campo;
  • Linha 10: um campo de entrada. Seu atributo [name] é o nome do parâmetro enviado ao servidor: é o vínculo entre o formulário e a action ([request.args.get("keyword")]). O atributo [value] é o valor exibido: a entrada anterior, reexibida (e escapada por [{{ }}], o que é essencial em um atributo: uma entrada contendo aspas ["] fecharia o atributo);
  • linhas 14–20: uma lista suspensa. Cada [<option>] tem um valor ([value]), enviado ao servidor, e um texto, exibido. A primeira opção, com valor vazio, significa “todos os gêneros”;
  • linha 18: a opção selecionada na requisição anterior recebe o atributo [selected]. Esse é um atributo booleano: basta sua presença; ele não tem valor. A expressão condicional sem [else] determina se ele é escrito ou não;
  • linha 23: o botão de envio ([type="submit"]);
  • linha 26: o número de resultados.

4.5.4. Execução

Image

Vamos digitar [le] e selecionar o gênero [novel]:

Image

A URL da página de resultados contém os campos do formulário: [/search?keyword=le&genre=novel]. A resposta do formulário:

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” não foi selecionado: “le” não aparece nem no título nem no nome do autor.

4.6. Exemplo 18: campos de formulário

Digitar manualmente o HTML de cada campo, reexibir seu valor, marcar as caixas corretas e selecionar as opções corretas é um trabalho repetitivo e sujeito a erros. A biblioteca [WTForms] faz isso por nós. Nela, um formulário é descrito por uma classe, em que cada atributo é um campo; cada campo sabe:

  • como fazer o binding com a requisição: ler seu valor dos dados enviados e convertê-lo para o seu tipo;
  • validar-se a si mesmo, com base em sua lista de validadores (Exemplo 19);
  • exibir-se em HTML, junto com seu valor atual.

A extensão [Flask-WTF] integra o [WTForms] ao [Flask]: seus formulários leem eles mesmos a requisição atual e são protegidos contra ataques CSRF (voltaremos a isso). Este exemplo mostra todos os tipos de campo de um formulário HTML.

4.6.1. O serviço de listas: services/lists.py

# services/lists.py: as listas oferecidas pelo formulário. Em uma aplicação
# real, elas viriam de um banco de dados: nós as leríamos UMA ÚNICA VEZ,
# na inicialização, já que são as mesmas para todos os usuários.
from flask import current_app


class ListsService:

    # cada lista: pares (valor enviado, texto exibido)
    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"]

As listas suspensas do formulário (títulos, países, hobbies, idiomas) são fornecidas por um serviço, seguindo o modelo do Exemplo 06: em uma aplicação real, elas viriam de um banco de dados. Cada opção é um par [(value, text)]: o valor enviado ao servidor e o texto exibido. [[(t, t) for t in (...)]] cria pares em que os dois elementos são idênticos. A função [lists_service] torna o objeto único, armazenado em [app.extensions] por [app.py]:

# app.py: a aplicação do exemplo 18
from pathlib import Path

from flask import Blueprint, Flask

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

# Bootstrap, compartilhado pelos exemplos (veja o exemplo 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
    # a chave secreta da aplicação: ela assina o token anti-CSRF dos formulários
    # (veja models/input.py). Em produção, uma string aleatória longa, mantida em segredo
    app.config["SECRET_KEY"] = "a-secret-key-for-example-18"
    # o serviço de listas: um único objeto compartilhado (veja o exemplo 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)
  • linha 19: [app.config] é a configuração da aplicação, um dicionário. A chave [SECRET_KEY] é a chave secreta da aplicação: [Flask] e suas extensões a usam para assinar os dados confiados ao navegador — isto é, para acrescentar uma impressão digital que apenas o detentor da chave pode calcular. Qualquer modificação dos dados pelo navegador é, assim, detectada. [Flask-WTF] precisa dela para seus tokens anti-CSRF; voltaremos a vê-la no cookie de sessão (exemplo 20). Em produção, é uma longa string aleatória que nunca deve aparecer no código-fonte (o capítulo sobre autenticação a lerá de uma variável de ambiente);
  • Linha 21: o serviço único compartilhado por todas as requisições.

4.6.2. O formulário: models/input.py

# models/input.py: o formulário, descrito por uma classe WTForms. Cada campo
# sabe ler a si mesmo a partir da requisição (binding) e se exibir em HTML (renderização)
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


# checkboxes: uma lista de múltipla escolha (SelectMultipleField),
# desenhada como uma lista de caixas (widgets) em vez de uma lista suspensa
class Checkboxes(SelectMultipleField):
    widget = ListWidget(prefix_label=False)
    option_widget = CheckboxInput()


# FlaskForm: um formulário WTForms adaptado ao Flask; ele lê sozinho os campos da
# requisição POST atual, e contém um campo oculto [csrf_token]
class InputForm(FlaskForm):
    token = HiddenField()
    title = RadioField("Title")
    name = StringField("Name")
    password = PasswordField("Password")
    # um campo <input type="date"> troca seus valores no formato yyyy-mm-dd;
    # Optional: o campo pode ficar vazio
    birth_date = DateField("Date of birth", validators=[Optional()])
    hobbies = Checkboxes("Hobbies")
    country = SelectField("Country")
    languages = SelectMultipleField("Spoken languages")
    comment = TextAreaField("Comment")

    # as listas de escolha, fornecidas pelo serviço a cada criação do formulário
    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()
  • Linhas 14–16: o [WTForms] não tem um campo de “caixas de seleção”. No entanto, um grupo de caixas de seleção com o mesmo nome é, para o servidor, uma lista de múltipla escolha: ele envia zero, um ou mais valores. Criamos, portanto, uma classe derivada de [SelectMultipleField] que altera apenas sua apresentação: o widget de um campo é o objeto que gera seu HTML; [ListWidget] renderiza uma lista de opções, e cada opção é renderizada por [CheckboxInput], uma caixa de seleção;
  • linha 21: o formulário herda de [FlaskForm], a classe base do [Flask-WTF];
  • linhas 22–32: os campos. O primeiro parâmetro é o rótulo. Cada classe de campo corresponde a um elemento HTML:
Campo WTForms
Elemento HTML gerado
[StringField]
[<input type="text">]
[PasswordField]
[<input type="password">], nunca preenchido previamente
[HiddenField]
[<input type="hidden">], um campo invisível
[DateField]
[<input type="date">], cujo valor é convertido em [date]
[IntegerField], [EmailField]
[<input type="number">], [<input type="email">] (exemplo 19)
[RadioField]
um grupo de botões de opção: um único valor
[SelectField]
uma lista suspensa [<select>]: um único valor
[SelectMultipleField]
uma lista [<select multiple>]: vários valores
[TextAreaField]
uma caixa de texto [<textarea>], de várias linhas
[BooleanField]
uma única caixa de seleção, convertida em booleano
  • Linha 28: o validador [Optional()] permite que o campo permaneça vazio (caso contrário, a conversão de uma string vazia em data falharia). Um campo [<input type="date">] troca seus valores com o servidor no formato [yyyy-mm-dd], independentemente do formato em que o navegador o exibe;
  • linhas 35–41: os campos de lista suspensa exigem sua lista de opções ([choices]). Essa lista é fornecida a cada criação do formulário, no construtor, por meio do método [__init__]. Ele primeiro chama o construtor da classe pai ([super().__init__(...)]), passando-lhe todos os seus parâmetros, e depois preenche os campos. Um campo [title] declarado no nível da classe torna-se, dentro do objeto, um campo vinculado ([self.title]) específico deste formulário.

4.6.3. O controller: controllers/form.py

# controllers/form.py: um formulário que usa todos os tipos de campos
from flask import Blueprint, render_template, request

from models.input import InputForm

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


# GET: o formulário, com valores iniciais (parâmetros nomeados: um 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() lê os campos enviados; o formulário os exibe de novo
@form.post("")
def process():
    input_form = InputForm()
    # validate: verifica o token anti-CSRF e as restrições dos campos
    valid = input_form.validate()
    # o que o navegador realmente enviou, 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)
  • linha 12: um formulário criado durante uma requisição (GET) não lê nada: seus campos assumem os valores passados ao construtor (parâmetros nomeados, um por campo) ou permanecem vazios. Esses são os valores iniciais do formulário;
  • linha 13: o próprio formulário é passado à view, que o renderizará;
  • linha 19: durante uma requisição POST, o [FlaskForm] lê ele mesmo os campos enviados ([request.form]): cada campo assume o valor recebido, convertido para o seu tipo;
  • linha 21: [validate()] executa os validadores de cada campo e retorna [True] se todos forem satisfeitos. Os campos de lista suspensa verificam automaticamente se o valor recebido está entre suas opções: um usuário malicioso pode enviar qualquer coisa, não apenas o que a página ofereceu. O [Flask-WTF] acrescenta a isso uma verificação do token anti-CSRF;
  • Linhas 23–24: para o exemplo, a lista do que o navegador realmente enviou: [request.form.lists()] retorna, para cada parâmetro, seu nome e a lista de seus valores. [", ".join(...)] os reúne em uma única string.

4.6.4. A view: 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">
    {# os campos ocultos: o token anti-CSRF do Flask-WTF e o nosso campo [token] #}
    {{ form.csrf_token }}
    {{ form.token }}

    <div class="mb-2">
      <span class="form-label me-3">{{ form.title.label.text }}</span>
      {# botões de opção: percorremos as opções do campo; mesmo [name], um único valor enviado #}
      {% 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">
        {# um campo é exibido ao CHAMÁ-LO; seus parâmetros viram atributos HTML #}
        {{ form.name.label(class="form-label") }}
        {{ form.name(class="form-control") }}
      </div>
      <div class="col">
        {# uma senha NUNCA é reenviada na página: PasswordField a 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>
      {# caixas de seleção: mesmo [name], vários valores possíveis #}
      {% 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 seleção múltipla: vários valores possíveis #}
        {{ form.languages(class="form-select", size=4) }}
      </div>
    </div>

    <div class="mb-2">
      {{ form.comment.label(class="form-label") }}
      {# uma área de texto: o valor fica ENTRE as tags #}
      {{ 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: um dicionário campo -> lista de suas mensagens de erro #}
    <ul>
      {% for field, messages in form.errors.items() %}
      <li>{{ field }}: {{ messages | join(", ") }}</li>
      {% endfor %}
    </ul>
  {% endif %}
{% endblock %}
  • Linha 5: um formulário POST;
  • linha 7: o campo oculto que contém o token anti-CSRF. Um ataque CSRF (*Cross-Site Request Forgery*) consiste em um site malicioso induzir o navegador da vítima a enviar um formulário à nossa aplicação. O navegador inclui os cookies da nossa aplicação na requisição — e, portanto, a sessão do usuário autenticado —, de modo que a requisição parece legítima. A defesa: cada formulário da nossa aplicação contém um token aleatório vinculado à sessão do usuário e assinado com a chave secreta, que o site malicioso não tem como conhecer. O [Flask-WTF] rejeita qualquer formulário POST cujo token esteja ausente ou seja inválido;
  • linha 8: um campo é renderizado chamando-o, ou simplesmente inserindo-o na página por meio de [{{ }}] (o que equivale a chamá-lo sem parâmetros). O HTML que ele produz não é escapado: o [WTForms] o marca como seguro (os valores que ele coloca nele são, no entanto, escapados);
  • Linhas 13–18: um grupo de botões de opção. Percorrido por um laço, o campo renderiza suas opções, uma por botão: cada uma é desenhada ([option(...)]) e tem seu próprio rótulo ([option.label(...)]). Todos os botões de opção compartilham o mesmo atributo [name]: apenas um é selecionado por vez, e apenas um valor é enviado;
  • linhas 24–25: o rótulo e o campo de entrada. Os parâmetros nomeados da chamada tornam-se atributos HTML: [class="form-control"]. Como o termo [class] é reservado em [Python], o [WTForms] também aceita [class_];
  • linha 30: [PasswordField] nunca reexibe o valor recebido: uma senha não deve circular de um lado para outro em uma página HTML;
  • Linhas 41–46: caixas de seleção, estilizadas da mesma forma que os botões de opção. Elas também têm o mesmo [name]; no entanto, várias caixas de seleção podem ser marcadas, e o navegador então envia vários valores (por exemplo, 10);
  • linha 57: a lista de seleção múltipla, exibida em quatro linhas ([size]);
  • linha 64: o campo de texto, ocupando duas linhas;
  • linhas 70–80: a condição [is defined] é verdadeira se a variável [received] tiver sido passada à view (pela action POST). [form.errors] é um dicionário que associa cada campo inválido a uma lista de suas mensagens de erro; [items()] retorna esses pares. O filtro [join] reúne os elementos de uma lista.

4.6.5. Execução

Image

Os valores iniciais passados ao construtor estão visíveis: o botão de opção “Mme”, o país “France” e o idioma “French”. O HTML gerado pelo [WTForms] (trechos):

<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] escreveu os atributos [id] (o nome do campo, seguido do número da opção nos grupos), [name], [type], [value], bem como [checked] e [selected] para as seleções comuns. O token anti-CSRF é uma string assinada. Vamos preencher o formulário e enviá-lo:

Image

A página mostra o que o servidor recebeu: um parâmetro por campo, com vários valores para as caixas de seleção e a lista suspensa; a senha foi enviada, mas não é exibida novamente em seu campo. O campo oculto [token] foi devolvido sem alteração: é assim que as informações que o usuário não vê trafegam de um lado para o outro (o estudo de caso usa isso para o número de versão de um registro). No entanto, um campo oculto não é um campo protegido: o usuário pode modificá-lo usando as ferramentas de desenvolvedor do navegador, e o servidor deve validá-lo como qualquer outro campo.

Agora vamos enviar, usando [curl], um formulário sem token e com um país que não está na 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>
...

Três erros: o token está ausente; o país [xx] não está entre as opções; nenhum título foi enviado (um [RadioField] exige uma seleção). As mensagens estão em inglês, o idioma padrão do [WTForms]: o exemplo a seguir mostra como escolher o idioma delas.

4.7. Exemplo 19: Validação de formulário

Um formulário de cadastro, em que cada campo tem suas próprias restrições. Se ocorrer um erro, o formulário é exibido novamente com os dados digitados pelo usuário e uma mensagem abaixo de cada campo que contenha um erro.

4.7.1. O formulário: models/registration.py

# models/registration.py: os campos do formulário e suas restrições
from flask_wtf import FlaskForm
from wtforms import EmailField, IntegerField, PasswordField, StringField
from wtforms.validators import DataRequired, Email, EqualTo, InputRequired, Length, NumberRange


# um FILTRO: ele transforma o valor recebido ANTES da validação;
# aqui, os espaços ao redor da entrada são removidos
def clean(value):
    return value.strip() if isinstance(value, str) else value


class RegistrationForm(FlaskForm):

    # o idioma das mensagens que o próprio WTForms escreve (conversão impossível,
    # por exemplo: "abc" em um campo inteiro)
    class Meta:
        locales = ["en"]

    # cada campo: um rótulo, filtros e uma lista de validadores, cada um
    # com sua mensagem de erro. DataRequired rejeita uma entrada vazia (ou feita
    # só de espaços); ele também produz o 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: um campo <input type="email">
    email = EmailField("Email address", filters=[clean], validators=[
        DataRequired("The email address is required."),
        Email("Invalid email address.")])

    # tudo o que vem de um formulário é uma string: IntegerField a converte
    # ("42" -> 42); InputRequired: a entrada não deve estar vazia
    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.")])

    # uma regra sobre DOIS campos: EqualTo compara este campo com outro
    confirmation = PasswordField("Confirmation", validators=[
        DataRequired("The confirmation is required."),
        EqualTo("password", message="The confirmation does not match the password.")])
  • Linhas 9–10: um [WTForms] filtro é uma função que transforma o valor recebido antes da validação. Ele remove os espaços ao redor de uma string (uma entrada como [" "] torna-se vazia e será rejeitada por [DataRequired]). O teste [isinstance] protege contra a ausência de valor ([None]);
  • linhas 17–18: a classe interna [Meta] controla o comportamento do formulário. [locales = ["en"]]: as mensagens que o [WTForms] gera por conta própria (uma conversão impossível, uma seleção inválida etc.) estarão em inglês; o [WTForms] traz as traduções delas para muitos idiomas (["fr"] daria mensagens em francês). O arquivo [app.py] desativa o mecanismo de tradução do [Flask-WTF] ([WTF_I18N_ENABLED = False]) para essa finalidade; caso contrário, ele esperaria pela extensão [Flask-Babel];
  • linhas 23–25: o parâmetro [validators] é a lista de validadores do campo, executados em ordem. Cada um recebe sua própria mensagem de erro. [DataRequired] rejeita um valor vazio; [Length] limita o comprimento da string;
  • linhas 28–30: [EmailField] gera um [<input type="email">]; o validador [Email] verifica a sintaxe do endereço (usando a biblioteca [email-validator], já utilizada pelo [Pydantic] no Exemplo 08);
  • linhas 34–36: [IntegerField] converte toda a entrada. [InputRequired] exige uma entrada; diferentemente de [DataRequired], ele verifica se algo foi digitado, e não se o valor convertido é “verdadeiro”: [DataRequired] rejeitaria uma idade igual a 0, porque [0] é falso em [Python]. [NumberRange] limita o valor;
  • Linhas 43–45: uma regra que se aplica a dois campos: [EqualTo("password")] compara o valor de um campo com o de outro campo.

Os validadores também servem para a exibição: [WTForms] deriva atributos HTML5 ([required], [maxlength], [minlength], [min], [max]), que permitem ao navegador verificar a entrada antes mesmo de ela ser enviada (veremos isso adiante). Um validador “personalizado” é uma função que recebe o formulário e o campo como argumentos e lança uma [ValidationError] (do módulo [wtforms.validators]) se o valor for inválido; ele também pode ser escrito como um método do formulário chamado [validate_<field>]. [WTForms] fornece outros validadores prontos para uso: [Regexp] (uma expressão regular), [AnyOf] (uma lista de valores permitidos), [Optional]... O estudo de caso os utiliza.

4.7.2. O controller: controllers/registration.py

# controllers/registration.py: um formulário validado pelo servidor
from flask import Blueprint, render_template, request

from models.registration import RegistrationForm

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


# ?html5=true: deixamos o navegador validar o formulário antes de enviá-lo
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: a requisição é um POST E o formulário é válido
    if not form.validate_on_submit():
        # EXIBIMOS o formulário DE NOVO: valores digitados (exceto as senhas),
        # e uma mensagem sob cada campo errado (veja 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)
  • linhas 10–11: o parâmetro [?html5=true] ativa a validação no navegador (veja adiante);
  • linha 24: [validate_on_submit()] retorna [True] se a requisição for um POST e se o formulário for válido;
  • Linhas 27–29: o formulário inválido é exibido novamente: é o mesmo objeto [form], que contém os dados digitados pelo usuário e os erros de cada campo. A variável [error] é uma mensagem geral exibida na parte inferior da página pelo template;
  • linha 30: o formulário válido — a página de boas-vindas. (O exemplo seguinte mostrará que é melhor redirecionar após um POST bem-sucedido.)

4.7.3. Um campo reutilizável: templates/fragments/field.html

Cada campo é exibido da mesma maneira: um rótulo, o campo de entrada e, em caso de erro, a área contornada em vermelho e a mensagem abaixo dela. Uma macro evita ter de escrever isso cinco vezes:

{# um campo de entrada, com seu rótulo e sua PRIMEIRA mensagem de erro.
   field.errors: a lista das mensagens de erro do campo; os atributos HTML5
   (required, maxlength, minlength, min, max) são escritos pelo próprio WTForms,
   de acordo com os validadores do 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 %}
  • linha 5: a macro recebe um campo do formulário;
  • linha 8: a classe [is-invalid], proveniente do [Bootstrap], contorna o campo em vermelho. Ela é adicionada se a lista de erros do campo, [field.errors], não estiver vazia;
  • Linhas 9–11: a primeira mensagem de erro do campo, em um elemento [invalid-feedback], que o [Bootstrap] exibe em vermelho abaixo de um campo [is-invalid].

4.7.4. As views

{% 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: o navegador ignora os atributos required, min... e
     envia o formulário como está; só o 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 %}
  • linhas 13–14: o atributo [novalidate] desativa a validação do navegador: o formulário é enviado como está, e somente o servidor o valida. É isso que queremos observar primeiro. [{{-] remove o espaço em branco que precede a tag para deixar o atributo adjacente à tag [<form>];
  • linhas 16–20: uma chamada da macro para 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>
    {# o erro global, no pé da página, sobre um fundo rosa claro; [error] é fornecido pela action #}
    {% if error %}
    <div class="error-area" role="alert">{{ error }}</div>
    {% endif %}
  </div>
</body>
</html>
  • linhas 15–17: a mensagem geral, na parte inferior da página, em uma área cujo estilo é definido por [static/css/styles.css] (exemplo 15). O atributo [role="alert"] a sinaliza para os leitores de tela.
1
2
3
4
5
6
7
8
{% extends "layout.html" %}

{% block content %}
  {# form.name.data: o valor do campo, após filtros e conversão #}
  <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] é o valor do campo após a filtragem e a conversão: o nome sem os espaços e a idade como inteiro.

4.7.5. Execução

Vamos enviar um formulário cheio de erros: um nome formado por espaços, um endereço sem domínio completo, uma idade de 12 anos, uma senha curta demais e uma confirmação diferente:

Image

A entrada foi preservada (exceto as senhas), e cada erro é sinalizado abaixo do campo correspondente. Com [curl], desta vez fornecendo o token anti-CSRF, também podemos enviar algo que um navegador não enviaria — uma idade não numérica: a mensagem de conversão, gerada pelo [WTForms], está em inglês, o idioma escolhido 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>

Também podemos ver os atributos HTML5 inferidos dos validadores: [required], [min], [max].

4.7.6. Validação no navegador

Vamos remover o atributo [novalidate] clicando no link “ativá-la” (parâmetro [?html5=true]). O navegador passa então a verificar por conta própria os atributos [required], [type="email"], [min], [maxlength]... antes de enviar o formulário, e exibe suas próprias mensagens:

Image

Essa validação é conveniente para o usuário: é imediata, sem idas e vindas ao servidor. Mas ela não substitui a validação no servidor: o usuário pode desativá-la, e um programa como o [curl] a ignora por completo. A regra é absoluta: o servidor sempre valida; a validação no navegador é apenas uma comodidade adicional.

Uma entrada correta, enfim. O nome, digitado com espaços de ambos os lados, foi limpo pelo filtro:

Image

4.8. Exemplo 20: O padrão Post/Redirect/Get

Quando uma ação POST responde com uma página, essa página é o resultado de um POST. Se o usuário recarrega a página (pressiona [F5]), o navegador reenvia a requisição POST, depois de exibir um aviso que poucas pessoas leem: o comando é enviado duas vezes, e a mensagem é postada duas vezes. O padrão Post/Redirect/Get (PRG) evita esse problema: uma ação POST bem-sucedida não retorna uma página; ela responde com um redirecionamento (exemplo 04) para uma página GET, que o navegador solicita imediatamente. Recarregar essa página simplesmente executa de novo a ação GET.

Resta um problema: a página GET quer exibir uma mensagem (“a tarefa foi adicionada”), mas é a ação POST que conhece essa mensagem, e ela não pode passar uma variável para uma requisição que ainda não ocorreu. A solução: uma mensagem flash, postada pela ação POST, mantida até a requisição seguinte, exibida e depois descartada.

4.8.1. O serviço: services/tasks.py

# services/tasks.py: a lista de tarefas, em memória, compartilhada por todos
from threading import Lock

from flask import current_app


class TasksService:

    def __init__(self):
        self._tasks = ["Read chapter 3"]
        # várias requisições podem ser executadas AO MESMO TEMPO (o servidor as trata
        # em várias threads): um lock (Lock) garante que uma única
        # thread por vez leia ou modifique a lista
        self._lock = Lock()

    def list(self) -> list[str]:
        with self._lock:
            return list(self._tasks)  # uma CÓPIA: o chamador não pode modificar a nossa

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


def tasks_service() -> TasksService:
    return current_app.extensions["tasks"]
  • Linha 14: a lista de tarefas é compartilhada por todas as requisições. No entanto, o servidor de desenvolvimento processa cada requisição em uma thread diferente: duas requisições podem ser executadas ao mesmo tempo e modificar a lista simultaneamente. Um lock ([Lock], do módulo padrão [threading]) garante que apenas uma thread por vez execute o código que ele protege. O prefixo [_] indica, por convenção, um atributo interno da classe;
  • linha 17: a instrução [with] adquire o lock, executa o bloco e depois libera o lock, mesmo que o bloco lance uma exceção. Uma thread que encontra o lock adquirido espera até que ele seja liberado;
  • linha 18: o método retorna uma cópia da lista: quem chama pode iterar sobre ela com segurança enquanto outra thread adiciona uma tarefa à original.

4.8.2. O controller: controllers/tasks.py

# controllers/tasks.py: o padrão 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: a lista e o formulário de adição
@tasks.get("")
def display():
    return render_template("tasks/tasks.html", tasks=tasks_service().list())


# POST /tasks: o padrão 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: exibimos a página de novo, sem redirecionamento
        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)
    # uma mensagem "flash": ela sobreviverá ao redirecionamento, para a PRÓXIMA requisição
    flash(f"The task [{text}] has been added.")
    # sem página: um redirecionamento para a página GET
    return redirect(url_for("tasks.display"))


# POST /tasks/without-prg: o contraexemplo (uma página em resposta ao 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)
  • linhas 18–24: a entrada é validada manualmente, sem [WTForms], para manter o exemplo simples. Uma entrada inválida é exibida novamente sem redirecionamento: não há nada a proteger contra um envio duplicado, já que nada foi modificado;
  • linha 27: [flash] define uma mensagem para a próxima requisição;
  • linha 29: o redirecionamento para a página GET;
  • linhas 34–38: o contraexemplo: uma página em resposta a um POST.

4.8.3. As views

<!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">
    {# as mensagens flash, no topo da página: deixadas ANTES do redirecionamento;
       get_flashed_messages as retorna e depois as esquece #}
    {% 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>
  • linhas 13–15: a função [get_flashed_messages()], disponível em todas as views, retorna a lista de mensagens flash pendentes e depois as descarta: elas serão exibidas uma única vez. A classe [alert alert-success] do [Bootstrap] as exibe em uma moldura 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ão envia o MESMO formulário para outro endereço #}
    <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 %}
  • Linha 14: o atributo [formaction] de um botão envia o formulário para um endereço diferente do indicado por seu atributo [action]: um único formulário pode, assim, disparar duas ações diferentes.

4.8.4. Onde as mensagens flash são armazenadas?

Entre a requisição POST e a requisição GET seguinte, a mensagem precisa ser armazenada em algum lugar. O [Flask] a armazena na sessão do usuário (veja o capítulo sobre escopos). Por padrão, a sessão do [Flask] não é armazenada no servidor: ela é armazenada em um cookie enviado ao navegador, que o reenvia a cada requisição. Para impedir que o usuário o adultere, o cookie é assinado com a chave secreta — e é por isso que [app.py] a define. Vamos examinar isso usando [curl]. A opção [-c] grava os cookies recebidos em um arquivo, enquanto a opção [-b] devolve os que estão no arquivo:

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=/
...

A resposta ao POST é um redirecionamento (código de status 302, cabeçalho [Location]), acompanhado de um cookie [session]. Seu valor é composto de três partes, separadas por pontos: os dados, codificados em Base64 (não comprimidos: o [Flask] só os comprime quando isso os torna menores); a data da assinatura; e a assinatura. Depois de decodificados, os dados são legíveis:

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

A sessão de uma aplicação chamada [Flask] é, portanto, legível pelo usuário (não é criptografada), mas à prova de adulteração (é assinada): nada de secreto é armazenado nela. O atributo [HttpOnly] impede que o [JavaScript] da página leia o cookie. Vamos seguir o redirecionamento enviando o cookie de volta:

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

A mensagem é exibida, e a sessão — agora vazia — é excluída: o servidor retorna um cookie vazio cuja data de expiração já passou. Uma nova requisição GET não exibiria mais a mensagem.

4.8.5. Execução

Adição de uma tarefa: o navegador seguiu o redirecionamento; a URL é a da página GET, que pode ser recarregada com segurança.

Image

Uma entrada inválida, exibida novamente com sua mensagem de erro:

Image

O contraexemplo: a página é a resposta a um POST, e sua URL é [/tasks/without-prg]. Se você clicar em [F5], o navegador pergunta se você deseja reenviar o formulário; se você concordar, a tarefa é adicionada uma segunda vez.

Image

Um princípio do protocolo HTTP: uma requisição GET não altera nada. Navegadores, mecanismos de busca e ferramentas que pré-carregam páginas seguem links livremente, sem pedir permissão ao usuário. Um link “excluir” ([<a href="/contacts/2/delete">]) seria, portanto, perigoso: um bot que percorresse o site apagaria tudo. Em uma aplicação web:

  • a visualização é feita por meio de um link ([<a href>]), que envia uma requisição GET;
  • a edição (salvar, duplicar, excluir) é feita por meio de um botão colocado em um formulário (POST), protegido por um token anti-CSRF.

Este exemplo gerencia uma lista de contatos e exibe uma janela de confirmação antes de cada exclusão.

4.9.1. O serviço: services/contacts.py

# services/contacts.py: os contatos, em memória, compartilhados por todos
from dataclasses import dataclass, replace
from threading import Lock

from flask import current_app


# um contato: um identificador, um nome, um número de telefone
@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)

    # o contato, ou None se ele não existir
    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:
                    # um contato é imutável (frozen): replace constrói um
                    # novo, que substitui o antigo na 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"]

Um serviço em memória, protegido por um lock como o do Exemplo 20. Alguns pontos sobre o [Python]:

  • linha 34: a expressão entre parênteses é um gerador (veja o Exemplo 05) de contatos cujo ID corresponde ao que está sendo procurado; [next] retorna o primeiro elemento, ou o valor padrão [None] se nenhum existir;
  • linha 38: [enumerate] percorre uma lista, retornando o índice e o elemento de cada item;
  • linha 42: um contato é imutável ([frozen=True]); a função [replace] do módulo [dataclasses] cria uma cópia dele, com alguns atributos alterados;
  • Os métodos retornam [None] para um contato inexistente: cabe ao controller decidir a resposta.

4.9.2. O controller: controllers/contacts.py

# controllers/contacts.py: links (GET) e botões (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")


# o contato, ou uma resposta 404 se ele não existir
def contact_or_404(contact):
    if contact is None:
        abort(404, "unknown contact")
    return contact


# um LINK (<a href>): uma requisição GET, que não 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)


# um BOTÃO em um formulário POST: uma requisição que modifica dados
@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"))


# mesmo formulário, outro botão (atributo formaction): outra ação
@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"))
  • linhas 10–13: uma função utilitária: um contato inexistente interrompe a ação com uma resposta 404;
  • linhas 17–23: as duas ações GET, que não modificam nada: a lista e a ficha de um contato;
  • linhas 29–34: o salvamento da ficha: uma ação POST, que segue o padrão PRG. A mesma URL, [/contacts/2], é tratada por duas ações diferentes, dependendo do método: GET exibe, POST salva;
  • Linhas 38–43: a duplicação — outra ação POST, disparada por um segundo botão no mesmo formulário;
  • linhas 46–50: a exclusão.

4.9.3. Proteção anti-CSRF: app.py

# app.py: a aplicação do exemplo 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, compartilhado pelos exemplos (veja o exemplo 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)
    # proteção anti-CSRF do Flask-WTF, para TODAS as requisições POST da
    # aplicação: cada formulário deve enviar de volta o token csrf_token()
    CSRFProtect(app)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • linha 26: nos exemplos 18 e 19, era o formulário [WTForms] que verificava seu token, em [validate()]. Aqui, os formulários são escritos à mão, sem [WTForms]. [CSRFProtect] estende a proteção a toda a aplicação: antes de cada requisição (POST, bem como PUT, PATCH, DELETE), ele verifica o token e retorna o código de status 400 se estiver ausente ou inválido, antes mesmo de a ação ser chamada. Uma ação não pode omiti-lo. Essa é a configuração que o estudo de caso usará.

4.9.4. As views

{% 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: um link simples; url_for coloca o id no caminho: /contacts/2 #}
          <a class="btn btn-sm btn-outline-primary" href="{{ url_for('contacts.details', id=contact.id) }}">View</a>
          {# delete: um formulário POST, cujo envio será confirmado #}
          <form method="post" class="d-inline" action="{{ url_for('contacts.delete', id=contact.id) }}"
                data-confirmation="Delete the contact {{ contact.name }}?">
            {# o token anti-CSRF, exigido pelo CSRFProtect (veja 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 %}
  • Linha 13: um link, apresentado como botão pelas classes do [Bootstrap] ([btn]...): a aparência não tem nada a ver com o método HTTP. [url_for('contacts.details', id=contact.id)] coloca o ID no caminho: [/contacts/2];
  • linhas 15–20: um formulário POST para cada botão “Excluir”, sem outros campos além do token. A classe [d-inline] o exibe na mesma linha que o link. O atributo [data-confirmation] contém a mensagem de confirmação: os atributos [data-...] não têm atribuição predefinida e se destinam ao [JavaScript] da página;
  • Linha 18: a função [csrf_token()], fornecida às views pelo [Flask-WTF], retorna o token anti-CSRF da sessão; ele é colocado em um campo oculto chamado [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>
    {# dois botões de envio para o mesmo formulário #}
    <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 %}
  • Linhas 16–18: dois botões de envio para o mesmo formulário: “Salvar” envia o formulário para o endereço indicado por seu atributo [action], e “Duplicar” o envia para o endereço indicado por seu atributo [formaction] (Exemplo 20);
  • Linha 19: retorno à lista: um link.

4.9.5. A janela de confirmação

O navegador pode exibir uma caixa de confirmação (função [JavaScript] [confirm]), mas ela não é muito atraente, e sua aparência depende do navegador. Aqui usamos uma janela modal do [Bootstrap], exibida por algumas linhas de [JavaScript]. A janela é um fragmento incluído no template e, portanto, está presente — embora oculta — em todas as páginas:

{# uma única janela para a página inteira, oculta (d-none) no início #}
<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>
  • linha 2: a classe [d-none] do [Bootstrap] oculta o elemento;
  • linhas 3–4: o fundo cinza, seguido da janela, são renderizados pelas classes do [Bootstrap];
  • linha 11: a posição da mensagem;
  • linhas 14–15: os dois botões, do tipo [button] (e não [submit]: eles não enviam nenhum formulário), distinguidos por seu 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>
  {# a janela de confirmação, presente em todas as páginas #}
  {% include "fragments/confirmation.html" %}
  {# o script, no final da página: os elementos que ele procura já existem #}
  <script src="{{ url_for('static', filename='js/app.js') }}"></script>
</body>
</html>
  • linha 19: a janela, incluída em todas as páginas;
  • linha 21: o script, colocado no final da página: quando ele é executado, os elementos que procura já existem.

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

// confirmação dos formulários que carregam o atributo data-confirmation="..."
// Sem JavaScript, esses formulários são simplesmente enviados sem confirmação.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // o formulário a enviar se o usuário confirmar

  // 1. interceptamos o envio dos formulários a confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // o envio é suspenso
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // a janela aparece
    });
  });

  // 2. os dois botões da janela
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // envio, SEM disparar o evento 'submit' novamente
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • linha 3: o código está envolvido em uma função anônima, executada imediatamente; suas variáveis não interferem nas dos outros scripts da página;
  • linhas 4–6: a janela, o local da mensagem e o formulário que aguarda confirmação;
  • linhas 9–14: para cada formulário que tem um atributo [data-confirmation], o evento [submit] — disparado quando o formulário é enviado — é interceptado. [preventDefault()] suspende o envio; o formulário fica em espera, e sua mensagem ([dataset.confirmation], o valor do atributo [data-confirmation]) é exibida na janela, que aparece;
  • linhas 19–25: um único handler para os cliques na janela: [event.target] é o elemento clicado; seu atributo [data-action] indica de qual botão se trata. “Sim” envia o formulário pendente usando o método [submit()], que — ao contrário de clicar em um botão — não dispara o evento [submit] (caso contrário, a janela reapareceria); “Não” oculta a janela.

Sem [JavaScript], o formulário é simplesmente enviado sem confirmação: a página continua utilizável. Isso é aprimoramento progressivo: [JavaScript] acrescenta comodidade, mas a aplicação não depende dele.

4.9.6. Execução

A lista de contatos:

Image

Clicar em “Excluir” exibe a janela de confirmação:

Image

Após a confirmação, o POST, o redirecionamento e a mensagem pop-up:

Image

A ficha de um contato, com seus dois botões de envio:

Image

Uma requisição POST sem token anti-CSRF é rejeitada pelo [CSRFProtect], e um contato inexistente retorna um erro 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>

As páginas de erro ainda são as páginas em inglês do [Werkzeug]. O capítulo sobre o ciclo de vida de uma requisição mostrará como substituí-las por páginas personalizadas.