4. A view e seu modelo
Até aqui, as ações geravam suas próprias respostas. 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 ação lhe passa — o modelo da view. Usaremos a engine de views [Handlebars] por meio do pacote [hbs], que a adapta ao [Express].
4.1. Exemplo 13: Uma primeira view
| 13-first-view/
├── src/
│ ├── app.module.ts
│ ├── main.ts
│ └── views.controller.ts
├── views/
│ ├── index.hbs
│ └── unknown.hbs
├── nest-cli.json
└── tsconfig.json
|
O arquivo [src/main.ts]:
| import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import { join } from 'path';
import { AppModule } from './app.module';
async function bootstrap() {
// NestExpressApplication: dá acesso aos métodos específicos do Express
const app = await NestFactory.create<NestExpressApplication>(AppModule);
// as views ficam na pasta [views], na raiz do projeto;
// depois de compilado, este arquivo fica em dist/: a raiz é portanto '..'
app.setBaseViewsDir(join(__dirname, '..', 'views'));
// a engine de views: Handlebars, fornecida pelo pacote [hbs]
app.setViewEngine('hbs');
await app.listen(3000);
console.log('Server started on http://localhost:3000');
}
bootstrap();
|
Vamos detalhar este código:
- Linha 2: [NestExpressApplication] é o tipo de uma aplicação [NestJS] que se apoia no [Express] (o [NestJS] também pode usar o servidor [Fastify]). Especificar esse tipo dá acesso aos métodos específicos do [Express]: [setBaseViewsDir], [setViewEngine], [useStaticAssets];
- linha 8: o tipo é passado para [NestFactory.create];
- Linha 11: a pasta das views. [__dirname] é a pasta do arquivo em execução: [dist], já que [dist/main.js] é o arquivo em execução. A pasta [views] fica, portanto, em [dist/../views];
- linha 13: a engine de views: [hbs]. As views são os arquivos [.hbs] da pasta de views.
O arquivo [src/views.controller.ts]:
| import { Controller, Get, Param, Render, Res } from '@nestjs/common';
import { Response } from 'express';
@Controller()
export class ViewsController {
// @Render('index'): o objeto retornado pela action é o MODELO da view
// views/index.hbs; o NestJS chama ele mesmo a engine de views
@Get()
@Render('index')
home(): object {
return {
title: 'My first view',
message: 'This page was built by Handlebars, on the server.',
time: new Date().toLocaleTimeString('en-US'),
};
}
// res.render(view, model): a view é escolhida DURANTE a execução da action
@Get('hello/:name')
hello(@Param('name') name: string, @Res() res: Response): void {
if (name === 'unknown') {
res.status(404).render('unknown', { name });
return;
}
res.render('index', {
title: `Hello ${name}`,
message: 'This time, the view was chosen by res.render.',
time: new Date().toLocaleTimeString('en-US'),
});
}
}
|
- linhas 8–9: [@Render('index')] refere-se à view [views/index.hbs]. O objeto retornado pela ação deixa de ser a resposta; ele é o modelo da view;
- linhas 11–15: o modelo: três valores, [title], [message] e [time];
- linhas 19–30: quando a view depende da requisição, a ação usa [res.render(view, model)] da resposta do [Express] (injetada por [@Res()]; veja o Exemplo 05). Aqui, o nome [unknown] exibe outra view, com o código de status 404.
O arquivo [views/index.hbs]:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{title}}</title>
</head>
<body>
<h1>{{title}}</h1>
<p>{{message}}</p>
<p>Page built at {{time}}.</p>
</body>
</html>
|
Uma view [Handlebars] é um arquivo HTML. Cada ocorrência de [{{title}}] (linhas 5 e 8) é substituída pelo valor do campo correspondente no modelo. O resultado:

O código-fonte da página recebida pelo navegador não contém mais nenhum vestígio do [Handlebars]:
| <!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 Handlebars, on the server.</p>
<p>Page built at 4:10:29 PM.</p>
</body>
</html>
|
A URL [/hello/martin] exibe a mesma view com um modelo diferente:

e [/hello/unknown] exibe ainda outra view:
| curl -i http://localhost:3000/hello/unknown
|
| 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>
|
4.2. Exemplo 14: A linguagem Handlebars
O [Handlebars] é uma linguagem de templates sem lógica: uma view não contém código [JavaScript], apenas expressões [{{...}}] e alguns blocos ([{{#if}}], [{{#each}}]...). Todos os cálculos são feitos antes pela ação. O Exemplo 14 demonstra isso. O modelo:
O arquivo [src/basics.controller.ts]:
| import { Controller, Get, Render } from '@nestjs/common';
@Controller()
export class BasicsController {
@Get()
@Render('basics')
basics(): object {
return {
title: 'Handlebars basics',
name: 'Martin',
html: '<b>this is HTML</b>',
loggedIn: true,
currency: '€',
products: [
{ name: 'Keyboard', price: 25, inStock: true },
{ name: 'Mouse', price: 12.5, inStock: false },
{ name: 'Screen', price: 149, inStock: true },
],
cart: [],
address: { street: '12 rue des Lilas', city: 'Angers' },
};
}
}
|
A view:
O arquivo [views/basics.hbs]:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{title}}</title>
</head>
<body>
<h1>{{title}}</h1>
{{!-- 1. exibe um valor do modelo --}}
<p>1. Name: {{name}} - missing variable: [{{nonexistent}}]</p>
{{!-- 2. {{ }} escapa o HTML, {{{ }}} o insere como está --}}
<p>2a. {{html}}</p>
<p>2b. {{{html}}}</p>
{{!-- 3. uma condição --}}
{{#if loggedIn}}
<p>3. You are logged in.</p>
{{else}}
<p>3. You are not logged in.</p>
{{/if}}
{{#unless loggedIn}}
<p>This paragraph is not displayed.</p>
{{/unless}}
{{!-- 4. um laço; dentro do laço, o contexto é o item atual --}}
<p>4. Our products:</p>
<ul>
{{#each products}}
<li>no. {{@index}}: {{name}}, {{price}} {{../currency}}
{{#if inStock}}(in stock){{else}}(sold out){{/if}}
{{#if @first}}- the first one{{/if}}
{{#if @last}}- the last one, seen by {{@root.name}}{{/if}}
</li>
{{/each}}
</ul>
{{!-- 5. {{else}} em um laço: o caso da lista vazia --}}
<p>5. Your cart:
{{#each cart}}{{name}}{{else}}it is empty.{{/each}}
</p>
{{!-- 6. muda o contexto, ou usa um caminho com pontos --}}
{{#with address}}
<p>6a. Address: {{street}}, {{city}}</p>
{{/with}}
<p>6b. City: {{address.city}}</p>
</body>
</html>
|
Vamos comentar este código:
- Linha 9: [{{!-- ... --}}] é um comentário ([Handlebars]): ele não aparece na página gerada (ao contrário de um comentário HTML como [<!-- -->]);
- linha 10: uma variável ausente do modelo ([nonexistent]) produz uma string vazia, sem erro;
- linhas 12–13: [{{html}}] escapa os caracteres especiais do HTML ([<] torna-se [<]...): o texto é exibido como está. [{{{html}}}] (três chaves) é inserido sem escape: ele é interpretado como HTML. As três chaves são usadas apenas para HTML gerado pela aplicação, nunca para dados digitados pelo usuário: um usuário poderia injetar HTML, ou até mesmo [JavaScript], na página (um ataque chamado [XSS]);
- linhas 15–19: [{{#if}}] / [{{else}}] / [{{/if}}]: um bloco condicional. A condição é um valor do modelo, não uma expressão: [false], [undefined], [null], [''], [0] e o array vazio são falsos;
- linhas 20–22: [{{#unless}}] é o inverso de [{{#if}}];
- Linhas 26–32: [{{#each}}] repete seu conteúdo para cada elemento de um array. Dentro do bloco, o contexto é o elemento atual: [{{name}}] é o nome do produto atual. Há variáveis especiais disponíveis: [@index] (posição a partir de 0), [@first], [@last]. [../currency] aponta para o contexto pai, [@root.name] para o modelo raiz;
- linha 36: um [{{else}}] dentro de um [{{#each}}] trata o caso de um array vazio;
- Linhas 39–41: [{{#with}}] muda o contexto; também é possível usar um caminho relativo (linha 42).

O código HTML produzido:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Handlebars basics</title>
</head>
<body>
<h1>Handlebars basics</h1>
<p>1. Name: Martin - missing variable: []</p>
<p>2a. <b>this is HTML</b></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>6a. Address: 12 rue des Lilas, Angers</p>
<p>6b. City: Angers</p>
</body>
</html>
|
Observe as linhas em branco deixadas pelos blocos: elas não têm efeito na exibição.
4.3. Exemplo 15: Layout, views parciais, arquivos estáticos
As páginas de um site compartilham um layout comum (cabeçalho, barra de navegação, rodapé). O [hbs] trata isso da seguinte forma: se a pasta de views contém um arquivo chamado [layout.hbs], toda view é inserida nesse layout. Os fragmentos de página reutilizáveis são chamados de views parciais.
| 15-layout-partials/
├── public/
│ └── css/
│ └── styles.css
├── src/
│ ├── app.module.ts
│ ├── main.ts
│ └── pages.controller.ts
├── views/
│ ├── partials/
│ │ ├── card.hbs
│ │ └── navbar.hbs
│ ├── home.hbs
│ ├── layout.hbs
│ ├── raw.hbs
│ └── team.hbs
├── nest-cli.json
└── tsconfig.json
|
O arquivo [src/main.ts]:
| import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import { NextFunction, Request, Response } from 'express';
import * as hbs from 'hbs';
import { dirname, join } from 'path';
import { AppModule } from './app.module';
const ROOT = join(__dirname, '..');
async function bootstrap() {
const app = await NestFactory.create<NestExpressApplication>(AppModule);
// 1. arquivos estáticos: public/css/styles.css é servido como /css/styles.css
app.useStaticAssets(join(ROOT, 'public'));
// o Bootstrap é servido diretamente de node_modules, em /bootstrap/
app.useStaticAssets(join(dirname(require.resolve('bootstrap/package.json')), 'dist'), { prefix: '/bootstrap/' });
// 2. as views; views/layout.hbs será o layout de TODAS as páginas
app.setBaseViewsDir(join(ROOT, 'views'));
app.setViewEngine('hbs');
// 3. os partials: views/partials/xxx.hbs é inserido por {{> xxx}}
await new Promise<void>((done) => hbs.registerPartials(join(ROOT, 'views', 'partials'), () => done()));
// 4. um middleware Express: o que ele coloca em res.locals é
// adicionado ao modelo de TODA view
app.use((req: Request, res: Response, next: NextFunction) => {
res.locals.path = req.path;
res.locals.year = new Date().getFullYear();
next();
});
await app.listen(3000);
console.log('Server started on http://localhost:3000');
}
bootstrap();
|
Vamos detalhar este código:
- linha 14: [useStaticAssets] serve arquivos estáticos de uma pasta: o arquivo [public/css/styles.css] é servido na URL [/css/styles.css] como está, sem passar por um controller;
- linha 16: o framework CSS [Bootstrap] é servido diretamente da pasta [node_modules], sob o prefixo [/bootstrap/]. [require.resolve] localiza a pasta do pacote [bootstrap], onde quer que ele esteja instalado (aqui em [examples/node_modules]);
- linha 22: os arquivos da pasta [views/partials] tornam-se views parciais: [partials/navbar.hbs] é inserido em uma view por [{{> navbar}}]. [registerPartials] lê a pasta de forma assíncrona: esperamos que ela termine (a função passada como segundo argumento é chamada no final) antes de iniciar o servidor;
- Linhas 26–30: um middleware do [Express] , executado antes de cada requisição. O que ele armazena em [res.locals] é adicionado ao modelo de cada view. É assim que fornecemos informações comuns (neste caso, o caminho solicitado e o ano) a todas as páginas sem repeti-las em cada ação.
O arquivo [views/layout.hbs]:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{{title}} - My site</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
<div class="container py-3">
{{> navbar}}
{{!-- a view solicitada pela action é inserida aqui --}}
{{{body}}}
<footer class="footer">Page [{{path}}] - © {{year}}</footer>
</div>
</body>
</html>
|
- linhas 7–8: as folhas de estilo, servidas por [useStaticAssets];
- linha 12: inserção da view parcial [navbar];
- linha 14: [{{{body}}}] é o local onde o [hbs] insere a view solicitada pela ação. Três chaves: a view é HTML já gerado e não deve ser escapada;
- linha 15: [path] e [year] vêm de [res.locals] (o middleware de [main.ts]).
O arquivo [views/partials/navbar.hbs]:
| <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>
|
O arquivo [views/partials/card.hbs]:
| {{!-- um "card" do Bootstrap; parâmetros: name, role --}}
<div class="card">
<div class="card-body">
<h5 class="card-title">{{name}}</h5>
<p class="card-text">{{role}}</p>
</div>
</div>
|
A view parcial [card] exibe um nome e um cargo. Ela é usada de duas maneiras:
O arquivo [views/home.hbs]:
| <h1>Welcome</h1>
<p>This page only contains its own content: the header, the navigation
bar and the footer come from the <code>layout.hbs</code> layout.</p>
{{> card name="A partial" role="inserted with named parameters"}}
|
linha 4: com parâmetros nomeados: a view parcial os recebe como contexto;
O arquivo [views/team.hbs]:
| <h1>{{title}}</h1>
<div class="row g-3">
{{#each members}}
<div class="col-md-4">
{{!-- sem parâmetros, o partial recebe o contexto atual: o membro --}}
{{> card}}
</div>
{{/each}}
</div>
|
linha 6: sem parâmetros: a view parcial recebe o contexto atual, neste caso o membro da equipe atual no laço [{{#each}}].
O arquivo [src/pages.controller.ts]:
| import { Controller, Get, Render } from '@nestjs/common';
@Controller()
export class PagesController {
@Get()
@Render('home')
home(): object {
return { title: 'Home' };
}
@Get('team')
@Render('team')
team(): object {
return {
title: 'Our team',
members: [
{ name: 'Marie Pélissier', role: 'Director' },
{ name: 'Jacques Bromard', role: 'Developer' },
{ name: 'Philippe Jandot', role: 'Graphic designer' },
],
};
}
// layout: false: a view é renderizada SOZINHA, sem o layout comum
@Get('raw')
@Render('raw')
raw(): object {
return { layout: false };
}
}
|
Linhas 25–29: O campo [layout: false] no modelo instrui o [hbs] a não usar o layout: a view [raw.hbs] é uma página HTML completa. Também poderíamos especificar um layout diferente ([layout: 'other']). As páginas resultantes:



O layout, as views parciais e [res.locals] são exatamente o que o estudo de caso usa: um layout ([layout.hbs]), views parciais para a barra de navegação, as mensagens e as janelas de confirmação, e um middleware que prepara o idioma e a mensagem a ser exibida.
4.4. Exemplo 16: Helpers
Um helper é uma função [TypeScript] que pode ser chamada de dentro de uma view. Ele compensa a falta de lógica do [Handlebars]: comparar dois valores, formatar uma data ou um preço, traduzir um texto... Os blocos [{{#if}}] e [{{#each}}] são, eles próprios, helpers predefinidos.
O arquivo [src/helpers.ts]:
| import { HelperOptions } from 'handlebars';
// o módulo 'hbs' não tem declarações de tipos: descrevemos o que usamos dele
interface Hbs {
registerHelper(name: string, fn: (...args: any[]) => unknown): void;
handlebars: { SafeString: new (html: string) => unknown; escapeExpression(text: string): string };
}
export function registerHelpers(hbs: Hbs): void {
// {{uppercase name}}: um helper simples, com um argumento
hbs.registerHelper('uppercase', (text: unknown) => String(text ?? '').toUpperCase());
// {{#if (eq a b)}}: usado como subexpressão, entre parênteses
hbs.registerHelper('eq', (a: unknown, b: unknown) => a === b);
// {{active path '/products'}}: "active" se a página atual estiver sob este caminho
hbs.registerHelper('active', (path: unknown, prefix: unknown) =>
typeof path === 'string' && typeof prefix === 'string' && path.startsWith(prefix) ? 'active' : '',
);
// {{money amount currency='USD'}}: o ÚLTIMO argumento de um helper é sempre
// o objeto [options] do Handlebars; options.hash contém os parâmetros
// nomeados, options.data.root o modelo completo da página (res.locals incluído)
hbs.registerHelper('money', (amount: unknown, options: HelperOptions) => {
const currency = options.hash.currency ?? 'EUR';
const language = options.data?.root?.lang ?? 'en-US';
return new Intl.NumberFormat(language, { style: 'currency', currency: currency }).format(Number(amount));
});
// {{date when}}: uma data no formato do idioma da página
hbs.registerHelper('date', (when: unknown, options: HelperOptions) => {
const language = options.data?.root?.lang ?? 'en-US';
return new Intl.DateTimeFormat(language, { dateStyle: 'full' }).format(new Date(String(when)));
});
// {{badge stock}}: um helper que constrói HTML. SafeString diz ao
// Handlebars para NÃO escapá-lo; cabe então ao helper escapar
// ele mesmo os dados que insere nele (escapeExpression)
hbs.registerHelper('badge', (stock: unknown) => {
const n = Number(stock);
const cssClass = n > 0 ? 'text-bg-success' : 'text-bg-danger';
const text = hbs.handlebars.escapeExpression(n > 0 ? `${n} in stock` : 'sold out');
return new hbs.handlebars.SafeString(`<span class="badge ${cssClass}">${text}</span>`);
});
}
|
Vamos comentar este código:
- linhas 4–7: o pacote [hbs] não tem declarações de tipos [TypeScript]: descrevemos quais delas usamos;
- linha 11: [hbs.registerHelper(name, fn)] define um helper. Em uma view, [{{uppercase name}}] chama a função com o valor de [name];
- linha 14: [eq] retorna um booleano. Ele é usado como uma subexpressão, entre parênteses, dentro de outro helper: [{{#if (eq path '/')}}];
- linhas 17–19: [active] retorna a classe CSS [active] se o caminho da página começa com um determinado prefixo;
- linhas 24–28: O último argumento de um helper é sempre o objeto [options] fornecido pelo [Handlebars]. [options.hash] contém os parâmetros nomeados ([{{money amount currency='USD'}}]), e [options.data.root] contém o modelo raiz da página, ao qual [res.locals] foi adicionado. O helper obtém daí o idioma da página, mesmo quando é chamado dentro de um [{{#each}}]. A formatação é feita pelo objeto padrão [Intl.NumberFormat];
- linhas 31–34: o mesmo princípio vale para uma data, com [Intl.DateTimeFormat];
- Linhas 39–44: Um helper que gera HTML. Por padrão, a saída de um helper é escapada, como qualquer expressão [{{...}}]. Para evitar isso, ela é retornada na forma de [SafeString]. O helper deve então escapar ele mesmo os dados que insere em seu HTML ([escapeExpression]) .
O arquivo [src/main.ts]:
| import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import { NextFunction, Request, Response } from 'express';
import * as hbs from 'hbs';
import { dirname, join } from 'path';
import { AppModule } from './app.module';
import { registerHelpers } from './helpers';
const ROOT = join(__dirname, '..');
async function bootstrap() {
const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.useStaticAssets(join(ROOT, 'public'));
app.useStaticAssets(join(dirname(require.resolve('bootstrap/package.json')), 'dist'), { prefix: '/bootstrap/' });
app.setBaseViewsDir(join(ROOT, 'views'));
app.setViewEngine('hbs');
// os helpers: funções TypeScript chamáveis a partir das views
registerHelpers(hbs);
await new Promise<void>((done) => hbs.registerPartials(join(ROOT, 'views', 'partials'), () => done()));
app.use((req: Request, res: Response, next: NextFunction) => {
res.locals.path = req.path;
res.locals.lang = req.query.lang === 'fr' ? 'fr-FR' : 'en-US';
next();
});
await app.listen(3000);
console.log('Server started on http://localhost:3000');
}
bootstrap();
|
- linha 18: os helpers são registrados na inicialização;
- linha 22: o middleware seleciona o idioma de formatação com base no parâmetro [lang] da URL (uma forma simples de testar; o próximo capítulo explicará isso melhor).
O arquivo [views/partials/navbar.hbs]:
| <nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
<span class="navbar-brand">Helpers</span>
<div class="navbar-nav">
{{!-- o link da página atual recebe a classe "active" --}}
<a class="nav-link {{#if (eq path '/')}}active{{/if}}" href="/">Home</a>
<a class="nav-link {{active path '/products'}}" href="/products">Products</a>
</div>
</nav>
|
Linhas 5–6: As duas formas de destacar o link da página atual: [eq] como subexpressão dentro de um [{{#if}}], ou o helper [active], que é mais conciso. O estudo de caso usa [active].
O arquivo [views/products.hbs]:
| <h1>{{title}}</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>
{{#each products}}
<tr>
<td>{{uppercase name}}</td>
<td>{{money price}}</td>
<td>{{money price currency='USD'}}</td>
<td>{{badge stock}}</td>
</tr>
{{/each}}
</tbody>
</table>
|
As páginas resultantes, primeiro em francês ([?lang=fr]) e depois em inglês ([?lang=en]):



Um formulário HTML enviado pelo método GET coloca seus campos na URL. Esse é o método adequado para uma busca: ela não modifica nada, e a URL resultante pode ser adicionada aos favoritos ou compartilhada. O estudo de caso o usa para selecionar um médico e uma data.
O arquivo [src/books.controller.ts]:
| import { Controller, Get, Query, Render } from '@nestjs/common';
interface Book {
title: string;
author: string;
genre: string;
}
const BOOKS: Book[] = [
{ title: 'Le Rouge et le Noir', author: 'Stendhal', genre: 'novel' },
{ title: 'Les Fleurs du mal', author: 'Baudelaire', genre: 'poetry' },
{ title: 'Madame Bovary', author: 'Flaubert', genre: 'novel' },
{ title: 'Alcools', author: 'Apollinaire', genre: 'poetry' },
{ title: 'Le Cid', author: 'Corneille', genre: 'drama' },
];
const GENRES = ['novel', 'poetry', 'drama'];
@Controller()
export class BooksController {
// GET /search?keyword=...&genre=...: o formulário E seus resultados
@Get(['/', 'search'])
@Render('search')
search(@Query('keyword') keyword = '', @Query('genre') genre = ''): object {
const word = keyword.trim().toLowerCase();
const results = BOOKS.filter(
(b) =>
(word === '' || b.title.toLowerCase().includes(word) || b.author.toLowerCase().includes(word)) &&
(genre === '' || b.genre === genre),
);
return { keyword, genre, genres: GENRES, results, count: results.length };
}
}
|
- linhas 9–15: os livros, em memória;
- linha 21: um array de caminhos: a ação processa [GET /] e [GET /search];
- linha 23: um valor padrão, [TypeScript], substitui um parâmetro ausente (na primeira visita, o formulário ainda não foi enviado);
- linhas 24–29: filtragem;
- linha 30: o modelo contém os valores digitados ([keyword], [genre]), para que o formulário possa exibi-los novamente, junto com a lista de gêneros e os resultados.
O arquivo [views/search.hbs]:
| <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="{{keyword}}": o campo exibe novamente o que foi digitado --}}
<input class="form-control" id="keyword" name="keyword" value="{{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>
{{#each genres}}
<option value="{{this}}" {{#if (eq this ../genre)}}selected{{/if}}>{{this}}</option>
{{/each}}
</select>
</div>
<div class="col-auto">
<button class="btn btn-primary" type="submit">Search</button>
</div>
</form>
<p>{{count}} book(s) found.</p>
<ul>
{{#each results}}
<li><i>{{title}}</i>, {{author}} ({{genre}})</li>
{{/each}}
</ul>
|
- Linha 3: [method="get"] e [action="/search"]: o envio do formulário é uma requisição [GET /search?keyword=...&genre=...]. Os nomes dos parâmetros são o atributo [name] de cada campo;
- Linha 7: O atributo [value] exibe novamente o valor digitado;
- linhas 13–15: na lista suspensa, a opção correspondente à categoria selecionada recebe o atributo [selected]. No laço, [this] é o elemento atual (uma string) e [../genre] é o gênero do modelo pai.
Na exibição inicial e, depois, após uma busca:


A barra de endereços mostra os parâmetros que foram enviados. Os caracteres acentuados e os espaços são codificados ali ([%C3%A9]...): trata-se da codificação de URL, que o [NestJS] decodifica antes de preencher [@Query].
O Exemplo 18 inclui todos os tipos de campos HTML: texto, senha, data, botões de opção, caixas de seleção, lista suspensa, lista de seleção múltipla, caixa de texto e campo oculto. Ele mostra como o servidor os recebe e como a view os exibe.
O arquivo [src/lists.service.ts]:
| import { Injectable } from '@nestjs/common';
// as listas oferecidas pelo formulário. Em uma aplicação real, elas
// viriam de um banco de dados: seriam lidas UMA vez, na inicialização,
// já que são iguais para todos os usuários
@Injectable()
export class ListsService {
readonly titles = ['Mr', 'Mme', 'Melle'];
readonly countries = [
{ code: 'fr', name: 'France' },
{ code: 'be', name: 'Belgium' },
{ code: 'ch', name: 'Switzerland' },
{ code: 'ca', name: 'Canada' },
];
readonly hobbies = ['reading', 'music', 'sport', 'cinema'];
readonly languages = ['French', 'English', 'Spanish', 'German'];
}
|
As listas oferecidas pelo formulário são fornecidas por um serviço. Elas são as mesmas para todos os usuários: um serviço, instanciado uma única vez (escopo de aplicação; veja o Capítulo 6), é o lugar natural para armazená-las.
O arquivo [src/form.controller.ts]:
| import { Body, Controller, Get, HttpCode, Post, Render } from '@nestjs/common';
import { ListsService } from './lists.service';
// o que o usuário digitou, depois de reformatado
interface Input {
name: string;
password: string;
comment: string;
title: string;
hobbies: string[];
country: string;
languages: string[];
birthDate: string;
token: string;
}
@Controller('form')
export class FormController {
constructor(private readonly lists: ListsService) {}
// GET: o formulário, com valores iniciais
@Get()
@Render('form')
display(): object {
const initial: Input = {
name: '', password: '', comment: '', title: 'Mme', hobbies: [],
country: 'fr', languages: ['French'], birthDate: '', token: 'A7X2',
};
return this.model(initial, null);
}
// POST: recebemos os valores digitados e exibimos o formulário novamente
@Post()
@HttpCode(200) // um POST responde 201 por padrão; aqui retornamos uma página
@Render('form')
process(@Body() body: Record<string, string | string[]>): object {
const input: Input = {
name: text(body.name),
password: text(body.password),
comment: text(body.comment),
title: text(body.title),
hobbies: array(body.hobbies),
country: text(body.country),
languages: array(body.languages),
birthDate: text(body.birthDate),
token: text(body.token),
};
return this.model(input, body);
}
// o modelo da view: as listas, cada opção sendo marcada
// checked / selected de acordo com a entrada
private model(input: Input, received: object | null): object {
return {
input,
titles: this.lists.titles.map((t) => ({ value: t, checked: t === input.title })),
hobbies: this.lists.hobbies.map((h) => ({ value: h, checked: input.hobbies.includes(h) })),
countries: this.lists.countries.map((c) => ({ ...c, selected: c.code === input.country })),
languages: this.lists.languages.map((l) => ({ value: l, selected: input.languages.includes(l) })),
received: received ? JSON.stringify(received, null, 2) : null,
};
}
}
// um campo ausente (caixa desmarcada...) não é enviado de forma alguma
function text(value: unknown): string {
return typeof value === 'string' ? value : '';
}
// um valor marcado: "sport"; dois: ["sport", "music"]; nenhum: undefined
function array(value: unknown): string[] {
if (value === undefined) return [];
return Array.isArray(value) ? value : [String(value)];
}
|
Vamos comentar este código:
- linhas 5–15: entrada e formatação dos dados: as caixas de seleção e a lista suspensa são arrays;
- linha 19: o serviço de listas é injetado;
- linhas 22–30: [GET /form] exibe o formulário com valores iniciais;
- linha 34: [POST /form] retorna uma página, e não um recurso criado: substituímos o código 201 por 200;
- linhas 37–47: os campos recebidos são reformatados. Dois casos exigem atenção: um campo ausente (uma caixa não marcada simplesmente não é enviada, veja a função [text], linhas 66–68) e um campo multivalorado, que chega como string quando tem apenas um valor (função [array], linhas 71–74, veja o Exemplo 10);
- linhas 53–62: o modelo da view. Para cada lista, a ação calcula quais opções devem ser marcadas ou selecionadas: a view só precisa então avaliar um booleano. O campo [received] contém o que o servidor recebeu, para fins de exibição.
O arquivo [views/form.hbs]:
| <h1 class="h3">A complete form</h1>
<form method="post" action="/form" style="max-width: 40rem">
{{!-- campo oculto: enviado com o formulário, mas invisível --}}
<input type="hidden" name="token" value="{{input.token}}">
<div class="mb-2">
<span class="form-label me-3">Title</span>
{{#each titles}}
{{!-- botões de opção (radio): mesmo [name], um único valor enviado --}}
<div class="form-check form-check-inline">
<input class="form-check-input" type="radio" name="title" id="title-{{value}}"
value="{{value}}" {{#if checked}}checked{{/if}}>
<label class="form-check-label" for="title-{{value}}">{{value}}</label>
</div>
{{/each}}
</div>
<div class="row g-2 mb-2">
<div class="col">
<label class="form-label" for="name">Name</label>
<input class="form-control" type="text" id="name" name="name" value="{{input.name}}">
</div>
<div class="col">
<label class="form-label" for="password">Password</label>
{{!-- uma senha NUNCA é reenviada na página --}}
<input class="form-control" type="password" id="password" name="password">
</div>
<div class="col">
<label class="form-label" for="birthDate">Date of birth</label>
<input class="form-control" type="date" id="birthDate" name="birthDate" value="{{input.birthDate}}">
</div>
</div>
<div class="mb-2">
<span class="form-label me-3">Hobbies</span>
{{#each hobbies}}
{{!-- caixas de seleção (checkbox): mesmo [name], vários valores possíveis --}}
<div class="form-check form-check-inline">
<input class="form-check-input" type="checkbox" name="hobbies" id="hobby-{{@index}}"
value="{{value}}" {{#if checked}}checked{{/if}}>
<label class="form-check-label" for="hobby-{{@index}}">{{value}}</label>
</div>
{{/each}}
</div>
<div class="row g-2 mb-2">
<div class="col">
<label class="form-label" for="country">Country</label>
<select class="form-select" id="country" name="country">
{{#each countries}}
<option value="{{code}}" {{#if selected}}selected{{/if}}>{{name}}</option>
{{/each}}
</select>
</div>
<div class="col">
<label class="form-label" for="languages">Spoken languages</label>
{{!-- lista de seleção múltipla: vários valores possíveis --}}
<select class="form-select" id="languages" name="languages" multiple size="4">
{{#each languages}}
<option value="{{value}}" {{#if selected}}selected{{/if}}>{{value}}</option>
{{/each}}
</select>
</div>
</div>
<div class="mb-2">
<label class="form-label" for="comment">Comment</label>
{{!-- uma área de texto: o valor fica ENTRE as tags --}}
<textarea class="form-control" id="comment" name="comment" rows="2">{{input.comment}}</textarea>
</div>
<button class="btn btn-primary" type="submit">Send</button>
</form>
{{#if received}}
<h2 class="h5 mt-3">What the server received</h2>
<pre class="bg-light p-2 border">{{received}}</pre>
{{/if}}
|
Vamos comentar este código:
- linha 2: o formulário é enviado por POST; seus campos vão no corpo da requisição;
- linha 4: um campo oculto é enviado com o formulário, mas não é exibido. Ele serve para transmitir informações de uma página à seguinte (o estudo de caso o usa, por exemplo, para guardar a versão de um registro). Atenção: o usuário pode modificá-lo;
- linhas 8–15: os botões de opção compartilham o mesmo atributo [name]: apenas um pode ser selecionado, e apenas um valor é enviado. O atributo [checked] seleciona o botão;
- linha 26: uma senha nunca é devolvida em uma página: o campo não tem o atributo [value];
- linha 30: um campo de data. O navegador exibe a data no formato do usuário, mas sempre envia [yyyy-mm-dd];
- linhas 36–43: as caixas de seleção com o mesmo atributo [name]: cada caixa marcada envia seu valor; o parâmetro é, portanto, repetido;
- linhas 49–53: uma lista suspensa. A opção selecionada tem o atributo [selected];
- linhas 58–62: o atributo [multiple] permite selecionar várias opções;
- linha 69: o valor de um campo de texto fica entre as suas tags, e não em um atributo [value];
- Linhas 75–78: O que o servidor recebeu, exibido dentro de uma tag [<pre>].
O formulário inicial e, depois, após o envio:


Observe que a caixa de texto exibiu novamente [Hello <b>everyone</b>] exatamente como foi digitado: graças ao escape de [{{...}}], as tags digitadas não são interpretadas. A senha foi recebida, mas não é exibida. Com o [curl], podemos ver a diferença quando uma caixa de seleção é marcada:
| curl -d "token=A7X2&title=Mr&name=Martin&hobbies=sport" http://localhost:3000/form
|
| {
"token": "A7X2",
"title": "Mr",
"name": "Martin",
"hobbies": "sport"
}
|
e com duas caixas marcadas:
| curl -d "token=A7X2&title=Mr&name=Martin&hobbies=sport&hobbies=music" http://localhost:3000/form
|
| {
"token": "A7X2",
"title": "Mr",
"name": "Martin",
"hobbies": [
"sport",
"music"
]
}
|
(apenas a seção [What the server received] da página é mostrada)
Um formulário inválido deve ser reexibido, mostrando os valores digitados e, abaixo de cada campo com erro, uma mensagem. O Exemplo 19 aplica a técnica do Exemplo 09 (validação feita pela ação) a um formulário de cadastro.
O arquivo [src/registration.dto.ts]:
| import { Transform, Type } from 'class-transformer';
import { IsEmail, IsInt, IsNotEmpty, Max, MaxLength, Min, MinLength } from 'class-validator';
// remove os espaços supérfluos de uma entrada ANTES da sua validação
const clean = ({ value }: { value: unknown }) => (typeof value === 'string' ? value.trim() : value);
export class RegistrationDto {
@Transform(clean)
@IsNotEmpty({ message: 'The name is required.' })
@MaxLength(20, { message: 'The name must not exceed 20 characters.' })
name: string;
@Transform(clean)
@IsEmail({}, { message: 'Invalid email address.' })
email: string;
// tudo o que vem de um formulário é uma string: "42" -> 42
@Type(() => Number)
@IsInt({ message: 'The age must be an integer.' })
@Min(18, { message: 'You must be at least 18 years old.' })
@Max(120, { message: 'The age cannot exceed 120 years.' })
age: number;
@MinLength(6, { message: 'The password must have at least 6 characters.' })
password: string;
// "confirmation = password" envolve DOIS campos: é o
// controller que verifica
confirmation: string;
}
|
- Linha 5: Uma função de limpeza, aplicada por [@Transform] antes da validação: um nome formado por espaços é convertido em uma string vazia, e [@IsNotEmpty] o rejeita;
- Linhas 18–22: A idade é convertida em número e depois validada;
- Linhas 27–29: A regra “a confirmação é igual à senha” envolve dois campos: os decoradores não a enxergam, mas o controller a verificará.
O arquivo [src/validation.ts]:
| import { ClassConstructor, plainToInstance } from 'class-transformer';
import { validate } from 'class-validator';
// erros por campo: { name: 'The name is required.', ... }
export type Errors = Record<string, string>;
export async function validateForm<T extends object>(
cls: ClassConstructor<T>,
body: Record<string, unknown>,
): Promise<{ dto: T; errors: Errors }> {
// 1. objeto recebido -> instância da classe (@Transform / @Type são aplicados)
const dto = plainToInstance(cls, body);
// 2. verificação de todas as restrições
const violations = await validate(dto);
// 3. mantemos a primeira mensagem de cada campo inválido
const errors: Errors = {};
for (const v of violations) {
errors[v.property] = Object.values(v.constraints ?? {})[0];
}
return { dto, errors };
}
|
- linha 5: Os erros são organizados por campo: [{ name: 'The name is required.' }], o que permite exibir cada mensagem sob o campo correspondente;
- linhas 7–10: a função é genérica: ela valida qualquer classe de formulário. Retorna a instância convertida ([dto]) e os erros;
- Linhas 17–19: Um campo pode violar várias restrições; apenas a primeira mensagem de erro é mantida.
O estudo de caso tem a mesma função ([web/helpers/form.helper.ts]).
O arquivo [src/registration.controller.ts]:
| import { Body, Controller, Get, Post, Query, Render, Res } from '@nestjs/common';
import { Response } from 'express';
import { RegistrationDto } from './registration.dto';
import { validateForm } from './validation';
@Controller('register')
export class RegistrationController {
// ?html5=1: deixamos o navegador validar o formulário antes de enviar
@Get()
@Render('registration')
display(@Query('html5') html5?: string): object {
return { values: {}, errors: {}, html5: html5 === '1' };
}
@Post()
async register(
@Body() body: Record<string, string>,
@Query('html5') html5: string | undefined,
@Res() res: Response,
): Promise<void> {
const { dto, errors } = await validateForm(RegistrationDto, body);
// uma regra que envolve dois campos
if (!errors.password && body.confirmation !== body.password) {
errors.confirmation = 'The confirmation does not match the password.';
}
if (Object.keys(errors).length > 0) {
// EXIBIMOS o formulário NOVAMENTE: valores digitados (exceto as senhas)
// e uma mensagem sob cada campo inválido
res.render('registration', {
values: { name: body.name, email: body.email, age: body.age },
errors,
globalError: 'The form contains errors.',
html5: html5 === '1',
});
return;
}
res.render('welcome', { name: dto.name, email: dto.email, age: dto.age });
}
}
|
- linhas 9–13: o formulário vazio. O parâmetro [html5] será explicado mais adiante;
- linha 21: validação de cada campo;
- linhas 23–25: seguida da regra que envolve dois campos;
- linhas 26–36: se houver erros, o formulário é reexibido: os valores digitados (exceto as senhas), os erros por campo e uma mensagem geral;
- linha 37: caso contrário, a página de boas-vindas, com os valores convertidos por [dto] (a idade é um número, o nome foi limpo).
Todos os campos são construídos com o mesmo modelo: uma view parcial cuida deles.
O arquivo [views/partials/field.hbs]:
| {{!-- um campo de entrada; parâmetros: name, label, type, value, error e
attributes = os atributos de validação do HTML5 (required, maxlength...) --}}
<div class="mb-2">
<label class="form-label" for="{{name}}">{{label}}</label>
<input class="form-control {{#if error}}is-invalid{{/if}}" id="{{name}}" name="{{name}}"
type="{{type}}" value="{{value}}" {{{attributes}}}>
{{#if error}}<div class="invalid-feedback">{{error}}</div>{{/if}}
</div>
|
- linha 5: a classe [Bootstrap] [is-invalid] destaca em vermelho um campo inválido;
- linha 6: os atributos de validação HTML5 são passados como parâmetros e inseridos sem escape (três chaves): eles são escritos pelo desenvolvedor, e não digitados pelo usuário;
- linha 7: a mensagem de erro, abaixo do campo (classe [invalid-feedback]).
O arquivo [views/registration.hbs]:
| <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=1">enable it</a></p>
{{/if}}
{{!-- novalidate: o navegador ignora os atributos required, min... e
envia o formulário como está; só o servidor valida --}}
<form method="post" action="/register{{#if html5}}?html5=1{{/if}}" {{#unless html5}}novalidate{{/unless}}>
{{> field name="name" label="Name" type="text" value=values.name error=errors.name
attributes='required maxlength="20"'}}
{{> field name="email" label="Email address" type="email" value=values.email
error=errors.email attributes="required"}}
{{> field name="age" label="Age" type="number" value=values.age error=errors.age
attributes='required min="18" max="120"'}}
{{> field name="password" label="Password" type="password" error=errors.password
attributes='required minlength="6"'}}
{{> field name="confirmation" label="Confirmation" type="password" error=errors.confirmation
attributes="required"}}
<button class="btn btn-primary" type="submit">Register</button>
</form>
|
- linha 9: o atributo [novalidate] está presente quando [html5] é falso;
- linhas 10–19: cada campo é uma chamada à view parcial, com parâmetros nomeados. Um parâmetro pode ser um valor do modelo ([value=values.name]).
O arquivo [views/layout.hbs]:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Registration</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
<div class="container py-3" style="max-width: 36rem">
{{{body}}}
{{!-- o erro global, no pé da página, sobre um fundo rosa claro --}}
{{#if globalError}}
<div class="error-area" role="alert">{{globalError}}</div>
{{/if}}
</div>
</body>
</html>
|
linhas 13–15: a mensagem global é exibida na parte inferior da página sobre um fundo rosa claro (classe [error-area] de [public/css/styles.css]), como no estudo de caso.
Vamos enviar o formulário com vários erros:

e depois preenchido corretamente:

4.7.1. Validação pelo navegador
Os atributos [required], [maxlength], [min], [max], [type="email"]... instruem o navegador a validar o formulário antes de enviá-lo: o usuário é avisado imediatamente por uma dica de tela (tooltip), sem nenhuma comunicação de ida e volta com o servidor. Esse é o comportamento acionado pelo link “enable it” ([/register?html5=1]), que remove o atributo [novalidate] do formulário.
Essa validação é uma conveniência, e não uma medida de segurança: é possível contorná-la simplesmente removendo o atributo [required] com as ferramentas de desenvolvedor do navegador, ou enviando a requisição com o [curl]. A validação no servidor continua sendo essencial. É por isso que o exemplo desativa por padrão a validação do navegador: para demonstrar o funcionamento do servidor. O estudo de caso, por sua vez, mantém as duas: os atributos HTML5 por conveniência e a validação no servidor por segurança.
4.8. Exemplo 20: O padrão Post/Redirect/Get
Quando um formulário POST é enviado com sucesso, a ação pode exibir uma página diretamente. O problema surge se o usuário atualiza essa página (tecla F5): o navegador reenvia o formulário, e a operação é executada uma segunda vez (um pedido feito duas vezes, uma consulta marcada duas vezes...). O padrão Post / Redirect / Get (PRG) evita esse problema: uma ação POST bem-sucedida não gera uma página; em vez disso, ela redireciona para uma página GET. Recarregar essa página envia apenas a requisição GET, que não tem nenhum efeito.
Resta um detalhe: a página GET precisa exibir uma mensagem (“a tarefa foi adicionada”), embora essa mensagem tenha sido gerada pela ação POST em uma requisição diferente. Ela é transmitida em um cookie de curta duração, que é lido e apagado pela requisição seguinte: trata-se de uma mensagem flash.
O arquivo [src/flash.ts]:
| import { NextFunction, Request, Response } from 'express';
const FLASH_COOKIE = 'flash';
// armazena uma mensagem que será exibida pela PRÓXIMA página, e apenas uma vez
export function flash(res: Response, message: string): void {
res.cookie(FLASH_COOKIE, message, { httpOnly: true, sameSite: 'lax', maxAge: 60_000 });
}
// a cada requisição: a mensagem pendente passa do cookie para res.locals (ou seja,
// para o modelo da view), e o cookie é apagado
export function flashMiddleware(req: Request, res: Response, next: NextFunction): void {
res.locals.flash = req.cookies?.[FLASH_COOKIE] ?? null;
if (res.locals.flash) {
res.clearCookie(FLASH_COOKIE);
}
next();
}
|
- linhas 6–8: [res.cookie(name, value, options)] define um cookie: o navegador o enviará de volta a cada requisição subsequente. Opções: [httpOnly] (o [JavaScript] da página não consegue lê-lo), [sameSite: 'lax'] (ele não é enviado em requisições POST vindas de outros sites), [maxAge] (tempo de vida: um minuto, mais que suficiente para acompanhar o redirecionamento);
- Linhas 12–18: Middleware executado antes de cada requisição: qualquer mensagem é passada do cookie para [res.locals], e portanto para o modelo da view, e o cookie é apagado ([res.clearCookie]): a mensagem será exibida uma única vez.
O arquivo [src/main.ts]:
| import { NestFactory } from '@nestjs/core';
import { NestExpressApplication } from '@nestjs/platform-express';
import * as cookieParser from 'cookie-parser';
import { dirname, join } from 'path';
import { AppModule } from './app.module';
import { flashMiddleware } from './flash';
const ROOT = join(__dirname, '..');
async function bootstrap() {
const app = await NestFactory.create<NestExpressApplication>(AppModule);
app.useStaticAssets(join(ROOT, 'public'));
app.useStaticAssets(join(dirname(require.resolve('bootstrap/package.json')), 'dist'), { prefix: '/bootstrap/' });
app.setBaseViewsDir(join(ROOT, 'views'));
app.setViewEngine('hbs');
// cookie-parser preenche req.cookies com os cookies enviados pelo navegador
app.use(cookieParser());
// depois nosso middleware lê (e apaga) a mensagem flash pendente
app.use(flashMiddleware);
await app.listen(3000);
console.log('Server started on http://localhost:3000');
}
bootstrap();
|
- linha 17: o middleware [cookie-parser] decodifica o cabeçalho [Cookie] da requisição e preenche o objeto [req.cookies];
- linha 19: nosso middleware, que precisa de [req.cookies], é registrado depois dele: os middlewares são executados na ordem em que são registrados.
O arquivo [src/tasks.controller.ts]:
| import { Body, Controller, Get, Post, Res } from '@nestjs/common';
import { Response } from 'express';
import { flash } from './flash';
import { TasksService } from './tasks.service';
@Controller('tasks')
export class TasksController {
constructor(private readonly tasks: TasksService) {}
// GET /tasks: a lista e o formulário de adição
@Get()
display(@Res() res: Response): void {
res.render('tasks', { tasks: this.tasks.list() });
}
// POST /tasks: o padrão Post / Redirect / Get
@Post()
add(@Body('label') label: string | undefined, @Res() res: Response): void {
const text = (label ?? '').trim();
if (text === '' || text.length > 40) {
// entrada inválida: exibimos a página novamente, sem redirecionamento
res.render('tasks', {
tasks: this.tasks.list(),
label,
error: 'The label must have 1 to 40 characters.',
});
return;
}
this.tasks.add(text);
flash(res, `The task [${text}] has been added.`);
// nenhuma página: um redirecionamento para a página GET
res.redirect('/tasks');
}
// POST /tasks/without-prg: o contraexemplo (uma página em resposta ao POST)
@Post('without-prg')
addWithoutPrg(@Body('label') label: string | undefined, @Res() res: Response): void {
this.tasks.add((label ?? '').trim() || '(untitled)');
res.render('tasks', { tasks: this.tasks.list(), withoutPrg: true });
}
}
|
- linhas 11–14: a página de listagem;
- linhas 20–27: uma entrada inválida: a página é reexibida (sem redirecionamento: a entrada e a mensagem de erro devem ser mantidas);
- linhas 29–32: uma entrada válida: a operação, a mensagem pop-up e, em seguida, um redirecionamento 302 para a página GET;
- linhas 36–40: o contraexemplo, para comparação.
O arquivo [views/tasks.hbs]:
| <h1 class="h3">My tasks</h1>
<ol>
{{#each tasks}}<li>{{this}}</li>{{/each}}
</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 withoutPrg}}
<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>
{{/if}}
|
linha 9: o atributo [formaction] de um botão envia o formulário para um endereço diferente do atributo [action] do formulário. O formulário tem assim dois botões, que disparam duas ações diferentes. O estudo de caso usa esse método em sua página de login.
O arquivo [views/layout.hbs]:
| <!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Tasks</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
<div class="container py-3" style="max-width: 36rem">
{{!-- a mensagem flash, no topo da página --}}
{{#if flash}}
<div class="alert alert-success" role="status">{{flash}}</div>
{{/if}}
{{{body}}}
{{#if error}}
<div class="error-area" role="alert">{{error}}</div>
{{/if}}
</div>
</body>
</html>
|
A mensagem flash é exibida no topo da página (linhas 12–14), e a mensagem de erro na parte inferior (linhas 16–18).
Veja o que o [curl] enxerga quando o formulário é enviado com sucesso. A opção [-c file] salva os cookies recebidos, enquanto [-b file] os envia de volta:
| curl -i -c cookies.txt -b cookies.txt -d "label=Review NestJS" http://localhost:3000/tasks
|
| HTTP/1.1 302 Found
Set-Cookie: flash=The%20task%20%5BReview%20NestJS%5D%20has%20been%20added.; Max-Age=60; Path=/; Expires=Wed, 23 Sep 2026 14:24:23 GMT; HttpOnly; SameSite=Lax
Location: /tasks
Content-Type: text/plain; charset=utf-8
Content-Length: 28
Found. Redirecting to /tasks
|
A resposta é um redirecionamento, com o cookie [flash] (seu conteúdo é codificado). A requisição seguinte envia o cookie; a resposta o apaga (data de expiração no passado):
| curl -i -c cookies.txt -b cookies.txt http://localhost:3000/tasks
|
| HTTP/1.1 200 OK
Set-Cookie: flash=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT
Content-Type: text/html; charset=utf-8
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Tasks</title>
<link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
<link rel="stylesheet" href="/css/styles.css">
</head>
<body>
...
|
No navegador, após adicionar uma tarefa:

A barra de endereços exibe [/tasks]: é a página GET. Você pode recarregá-la sem risco; a mensagem desaparecerá. Uma entrada vazia:

E o contraexemplo:

Aqui, recarregar a página dispara um aviso do navegador (“Confirmar reenvio do formulário”), e depois adiciona a tarefa uma segunda vez. Todos os formulários POST do estudo de caso seguem o padrão PRG.
4.9. Exemplo 21: Links, botões e confirmação
Uma regra simples orienta a escolha entre um link e um botão:
- um link ([<a href>]) gera uma requisição GET. Uma requisição GET não deve modificar nada: navegadores, mecanismos de busca e antivírus podem seguir links por conta própria para preparar ou analisar uma página;
- uma operação que modifica dados (adicionar, editar, excluir, sair) é um botão em um formulário POST.
O Exemplo 21 gerencia uma lista de contatos: você consulta um contato por meio de um link e o exclui por meio de um botão, que abre uma janela de confirmação.
O arquivo [src/contacts.controller.ts]:
| import { Body, Controller, Get, Param, ParseIntPipe, Post, Render, Res } from '@nestjs/common';
import { Response } from 'express';
import { flash } from './flash';
import { ContactsService } from './contacts.service';
@Controller('contacts')
export class ContactsController {
constructor(private readonly contacts: ContactsService) {}
// um LINK (<a href>): uma requisição GET, que não modifica nada
@Get()
@Render('list')
list(): object {
return { contacts: this.contacts.list() };
}
@Get(':id')
@Render('details')
details(@Param('id', ParseIntPipe) id: number): object {
return { contact: this.contacts.read(id) };
}
// um BOTÃO em um formulário POST: uma requisição que modifica dados
@Post(':id')
save(
@Param('id', ParseIntPipe) id: number,
@Body() body: { name: string; phone: string },
@Res() res: Response,
): void {
const contact = this.contacts.edit(id, body.name, body.phone);
flash(res, `The contact [${contact.name}] has been modified.`);
res.redirect('/contacts');
}
// mesmo formulário, outro botão (atributo formaction): outra action
@Post(':id/duplicate')
duplicate(
@Param('id', ParseIntPipe) id: number,
@Body() body: { name: string; phone: string },
@Res() res: Response,
): void {
const copy = this.contacts.add(`${body.name} (copy)`, body.phone);
flash(res, `The contact [${copy.name}] has been created.`);
res.redirect('/contacts');
}
@Post(':id/delete')
delete(@Param('id', ParseIntPipe) id: number, @Res() res: Response): void {
const contact = this.contacts.delete(id);
flash(res, `The contact [${contact.name}] has been deleted.`);
res.redirect('/contacts');
}
}
|
- linhas 11–15 e 17–21: as duas páginas — a lista e a página de detalhes do contato. [ParseIntPipe] converte o ID; um contato inexistente resulta em um erro 404 (veja o serviço);
- linhas 24–29: gravação de um registro, com PRG;
- linhas 36–41: duplicação, acionada por um segundo botão no mesmo formulário (atributo [formaction]);
- linhas 47–52: exclusão, via POST.
O arquivo [views/list.hbs]:
| <h1 class="h3">Contacts</h1>
<table class="table align-middle">
<tbody>
{{#each contacts}}
<tr>
<td>{{name}}</td>
<td>{{phone}}</td>
<td class="text-end">
{{!-- view: um link simples --}}
<a class="btn btn-sm btn-outline-primary" href="/contacts/{{id}}">View</a>
{{!-- delete: um formulário POST, cujo envio será confirmado --}}
<form method="post" action="/contacts/{{id}}/delete" class="d-inline"
data-confirmation="Delete the contact {{name}}?">
<button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
</form>
</td>
</tr>
{{/each}}
</tbody>
</table>
|
- linha 10: consultar: um link, exibido como botão pelo [Bootstrap];
- linhas 12–15: excluir: um pequeno formulário (POST), reduzido ao seu botão. O atributo [data-confirmation] contém a pergunta a ser feita antes do envio. Os atributos [data-*] são opcionais: o HTML os ignora, enquanto o [JavaScript] da página pode lê-los.
O arquivo [views/details.hbs]:
| <h1 class="h3">Contact no. {{contact.id}}</h1>
<form method="post" action="/contacts/{{contact.id}}">
<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="/contacts/{{contact.id}}/duplicate">Duplicate</button>
<a class="btn btn-link" href="/contacts">Back to the list</a>
</form>
|
Linha 13: dois botões de envio para o mesmo formulário.
4.9.1. A janela de confirmação
A caixa de diálogo do navegador ([window.confirm]) não pode ser formatada nem traduzida: seus botões permanecem no idioma do navegador. Ela é substituída por uma janela [Bootstrap], escrita na página e oculta até que seja necessária:
O arquivo [views/partials/confirmation.hbs]:
| {{!-- 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] oculta a janela;
- linha 3: o fundo cinza;
- linha 11: a posição da pergunta;
- linhas 14–15: os dois botões, identificados pelo atributo [data-action].
Um pouco de [JavaScript] vincula os formulários à janela:
O arquivo [public/js/app.js]:
| // confirmação dos formulários que têm 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 novamente o evento 'submit'
} else if (action === 'no') {
modal.classList.add('d-none');
pending = null;
}
});
})();
|
- Linha 3: o código é envolvido por uma função executada imediatamente, para evitar a criação de variáveis globais;
- linhas 9–16: o envio de cada formulário que possui o atributo [data-confirmation] é interceptado. [preventDefault()] suspende o envio; o formulário é guardado, a pergunta é colocada na janela ([textContent], e não [innerHTML]: a pergunta é exibida como texto, nunca interpretada como HTML) e a janela é exibida;
- Linhas 19–27: “Sim” envia o formulário guardado. O método [submit()] de um formulário o envia sem disparar o evento [submit]: não há nova pergunta de confirmação. “Não” oculta a janela.
Se o [JavaScript] estiver desativado, os formulários são simplesmente enviados sem confirmação: a aplicação continua funcionando. Esse é o princípio do aprimoramento progressivo: [JavaScript] acrescenta conveniência, mas não é essencial. O estudo de caso segue esse princípio (seu [public/js/app.js] acrescenta o tratamento do teclado: tecla Esc, foco). As páginas resultantes:




Por fim, verificamos que a exclusão não pode ser disparada por uma requisição GET:
| curl -i http://localhost:3000/contacts/3/delete
|
| HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8
Content-Length: 80
{"message":"Cannot GET /contacts/3/delete","error":"Not Found","statusCode":404}
|
| curl -i -X POST http://localhost:3000/contacts/3/delete
|
| HTTP/1.1 302 Found
Set-Cookie: flash=The%20contact%20%5BPhilippe%20Jandot%5D%20has%20been%20deleted.; Max-Age=60; Path=/; Expires=Wed, 23 Sep 2026 14:24:35 GMT; HttpOnly; SameSite=Lax
Location: /contacts
Content-Type: text/plain; charset=utf-8
Content-Length: 31
Found. Redirecting to /contacts
|