Skip to content

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:

Image

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:

Image

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 [&lt;]...): 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).

Image

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

1
2
3
4
5
6
7
8
<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]:

1
2
3
4
5
6
7
{{!-- 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]:

1
2
3
4
<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]:

1
2
3
4
5
6
7
8
9
<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:

Image

Image

Image

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

1
2
3
4
5
6
7
8
<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]):

Image

Image

Image

4.5. Exemplo 17: Um formulário GET

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:

Image

Image

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

4.6. Exemplo 18: Campos de formulário

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:

Image

Image

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
1
2
3
4
5
6
{
  "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
1
2
3
4
5
6
7
8
9
{
  "token": "A7X2",
  "title": "Mr",
  "name": "Martin",
  "hobbies": [
    "sport",
    "music"
  ]
}

(apenas a seção [What the server received] da página é mostrada)

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

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

1
2
3
4
5
6
7
8
{{!-- 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:

Image

e depois preenchido corretamente:

Image

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
1
2
3
4
5
6
7
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:

Image

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

Image

E o contraexemplo:

Image

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.

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:

Image

Image

Image

Image

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
1
2
3
4
5
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
1
2
3
4
5
6
7
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