Skip to content

4. La vista y su modelo

Hasta ahora, las acciones han generado sus propias respuestas. En una aplicación MVC, este es el papel de una vista: un archivo que describe la página HTML, con marcadores de posición para los datos que la acción le pasa, es decir, el modelo de la vista. Usaremos el motor de vistas [Handlebars] mediante el paquete [hbs], que lo adapta a [Express].

4.1. Ejemplo 13: una primera vista

13-first-view/
├── src/
│   ├── app.module.ts
│   ├── main.ts
│   └── views.controller.ts
├── views/
│   ├── index.hbs
│   └── unknown.hbs
├── nest-cli.json
└── tsconfig.json

El archivo [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: da acceso a los métodos específicos de Express
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  // las vistas están en la carpeta [views], en la raíz del proyecto;
  // una vez compilado, este archivo está en dist/: la raíz es entonces '..'
  app.setBaseViewsDir(join(__dirname, '..', 'views'));
  // el motor de vistas: Handlebars, proporcionado por el paquete [hbs]
  app.setViewEngine('hbs');
  await app.listen(3000);
  console.log('Server started on http://localhost:3000');
}

bootstrap();

Analicemos este código:

  • Línea 2: [NestExpressApplication] es el tipo de una aplicación [NestJS] que se apoya en [Express] ([NestJS] también puede usar el servidor [Fastify]). Al especificarlo se accede a los métodos propios de [Express]: [setBaseViewsDir], [setViewEngine], [useStaticAssets];
  • línea 8: el tipo se pasa a [NestFactory.create];
  • Línea 11: la carpeta de vistas. [__dirname] es la carpeta del archivo que se está ejecutando: [dist], ya que se está ejecutando [dist/main.js]. Por lo tanto, la carpeta [views] está en [dist/../views];
  • línea 13: el motor de vistas: [hbs]. Las vistas son los archivos [.hbs] de la carpeta de vistas.

El archivo [src/views.controller.ts]:

import { Controller, Get, Param, Render, Res } from '@nestjs/common';
import { Response } from 'express';

@Controller()
export class ViewsController {
  // @Render('index'): el objeto devuelto por la acción es el MODELO de la vista
  // views/index.hbs; NestJS llama al motor de vistas por sí mismo
  @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): la vista se elige DURANTE la ejecución de la acción
  @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'),
    });
  }
}
  • líneas 8–9: [@Render('index')] hace referencia a la vista [views/index.hbs]. El objeto devuelto por la acción ya no es la respuesta; es el modelo de la vista;
  • líneas 11–15: el modelo: tres valores, [title], [message] y [time];
  • líneas 19–30: cuando la vista depende de la solicitud, la acción usa [res.render(view, model)] de la respuesta [Express] (inyectada por [@Res()]; véase el ejemplo 05). Aquí, el nombre [unknown] muestra otra vista, con código de estado 404.

El archivo [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>

Una vista [Handlebars] es un archivo HTML. Cada aparición de [{{title}}] (líneas 5, 8) se reemplaza por el valor del campo correspondiente del modelo. El resultado:

Image

El código fuente de la página que recibe el navegador ya no contiene ningún rastro de [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>

La URL [/hello/martin] muestra la misma vista con un modelo diferente:

Image

y [/hello/unknown] muestra otra vista más:

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. Ejemplo 14: el lenguaje Handlebars

[Handlebars] es un lenguaje de plantillas sin lógica: una vista no contiene código [JavaScript], solo expresiones [{{...}}] y algunos bloques ([{{#if}}], [{{#each}}]...). Todos los cálculos los realiza previamente la acción. El ejemplo 14 lo demuestra. El modelo:

El archivo [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' },
    };
  }
}

La vista:

El archivo [views/basics.hbs]:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{title}}</title>
</head>
<body>
  <h1>{{title}}</h1>
  {{!-- 1. mostrar un valor del modelo --}}
  <p>1. Name: {{name}} - missing variable: [{{nonexistent}}]</p>
  {{!-- 2. {{ }} escapa el HTML, {{{ }}} lo inserta tal cual --}}
  <p>2a. {{html}}</p>
  <p>2b. {{{html}}}</p>
  {{!-- 3. una condición --}}
  {{#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. un bucle; dentro del bucle, el contexto es el elemento actual --}}
  <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}} en un bucle: el caso de la lista vacía --}}
  <p>5. Your cart:
    {{#each cart}}{{name}}{{else}}it is empty.{{/each}}
  </p>
  {{!-- 6. cambiar el contexto, o usar una ruta con puntos --}}
  {{#with address}}
    <p>6a. Address: {{street}}, {{city}}</p>
  {{/with}}
  <p>6b. City: {{address.city}}</p>
</body>
</html>

Comentemos este código:

  • Línea 9: [{{!-- ... --}}] es un comentario ([Handlebars]): no aparece en la página generada (a diferencia de un comentario HTML como [<!-- -->]);
  • línea 10: una variable ausente del modelo ([nonexistent]) produce una cadena vacía, sin error;
  • líneas 12–13: [{{html}}] escapa los caracteres especiales de HTML ([<] se convierte en [&lt;]...): el texto se muestra tal cual. [{{{html}}}] (tres llaves) se inserta sin escapar: se interpreta como HTML. Las tres llaves se usan solo para HTML generado por la aplicación, nunca para datos ingresados por el usuario: un usuario podría inyectar HTML, o incluso [JavaScript], en la página (un ataque conocido como [XSS]);
  • líneas 15–19: [{{#if}}] / [{{else}}] / [{{/if}}]: un bloque condicional. La condición es un valor del modelo, no una expresión: [false], [undefined], [null], [''], [0] y el arreglo vacío son falsos;
  • líneas 20–22: [{{#unless}}] es el inverso de [{{#if}}];
  • Líneas 26–32: [{{#each}}] repite su contenido para cada elemento de un arreglo. Dentro del bloque, el contexto es el elemento actual: [{{name}}] es el nombre del producto actual. Hay variables especiales disponibles: [@index] (posición a partir de 0), [@first], [@last]. [../currency] apunta al contexto padre, [@root.name] al modelo raíz;
  • línea 36: un [{{else}}] dentro de un [{{#each}}] maneja el caso de un arreglo vacío;
  • Líneas 39–41: [{{#with}}] cambia el contexto; también se puede usar una ruta relativa (línea 42).

Image

El código HTML que se produce:

<!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 las líneas en blanco que dejan los bloques: no tienen ningún efecto en la visualización.

4.3. Ejemplo 15: plantilla, vistas parciales, archivos estáticos

Las páginas de un sitio comparten una plantilla común (encabezado, barra de navegación, pie de página). [hbs] lo maneja así: si la carpeta de vistas contiene un archivo llamado [layout.hbs], cada vista se inserta en esta plantilla. Los fragmentos de página reutilizables se llaman vistas parciales.

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

El archivo [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. archivos estáticos: public/css/styles.css se sirve como /css/styles.css
  app.useStaticAssets(join(ROOT, 'public'));
  // Bootstrap se sirve directamente desde node_modules, bajo /bootstrap/
  app.useStaticAssets(join(dirname(require.resolve('bootstrap/package.json')), 'dist'), { prefix: '/bootstrap/' });

  // 2. las vistas; views/layout.hbs será el diseño (layout) de TODAS las páginas
  app.setBaseViewsDir(join(ROOT, 'views'));
  app.setViewEngine('hbs');
  // 3. los parciales (partials): views/partials/xxx.hbs se inserta con {{> xxx}}
  await new Promise<void>((done) => hbs.registerPartials(join(ROOT, 'views', 'partials'), () => done()));

  // 4. un middleware de Express: lo que ponga en res.locals se
  //    agrega al modelo de CADA vista
  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();

Analicemos este código:

  • línea 14: [useStaticAssets] sirve archivos estáticos de una carpeta: el archivo [public/css/styles.css] se sirve en la URL [/css/styles.css] tal cual, sin pasar por un controlador;
  • línea 16: el framework CSS [Bootstrap] se sirve directamente desde la carpeta [node_modules], bajo el prefijo [/bootstrap/]. [require.resolve] localiza la carpeta del paquete [bootstrap], dondequiera que esté instalado (aquí en [examples/node_modules]);
  • línea 22: los archivos de la carpeta [views/partials] se convierten en archivos parciales: [partials/navbar.hbs] se inserta en una vista con [{{> navbar}}]. [registerPartials] lee la carpeta de forma asíncrona: esperamos a que termine (la función pasada como segundo argumento se llama al final) antes de iniciar el servidor;
  • Líneas 26–30: un [Express] middleware, que se ejecuta antes de cada solicitud. Lo que guarda en [res.locals] se agrega al modelo de cada vista. Así proporcionamos información común (en este caso, la ruta solicitada y el año) a todas las páginas sin repetirla en cada acción.

El archivo [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}}
    {{!-- la vista solicitada por la acción se inserta aquí --}}
    {{{body}}}
    <footer class="footer">Page [{{path}}] - © {{year}}</footer>
  </div>
</body>
</html>
  • líneas 7–8: las hojas de estilo, servidas por [useStaticAssets];
  • línea 12: inserción del parcial [navbar];
  • línea 14: [{{{body}}}] es el lugar donde [hbs] inserta la vista solicitada por la acción. Tres llaves: la vista proviene de HTML ya generado y no debe escaparse;
  • línea 15: [path] y [year] provienen de [res.locals] (el middleware de [main.ts]).

El archivo [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>

El archivo [views/partials/card.hbs]:

1
2
3
4
5
6
7
{{!-- una "tarjeta" (card) de 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>

El parcial [card] muestra un nombre y un cargo. Se usa de dos maneras:

El archivo [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"}}

línea 4: con parámetros con nombre: el parcial los recibe como contexto;

El archivo [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">
      {{!-- sin parámetros, el partial recibe el contexto actual: el miembro --}}
      {{> card}}
    </div>
  {{/each}}
</div>

línea 6: sin parámetros: el parcial recibe el contexto actual, en este caso el miembro del equipo actual en el bucle [{{#each}}].

El archivo [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: la vista se renderiza SOLA, sin el diseño común
  @Get('raw')
  @Render('raw')
  raw(): object {
    return { layout: false };
  }
}

Líneas 25–29: el campo [layout: false] del modelo indica a [hbs] que no use la plantilla: la vista [raw.hbs] es una página HTML completa. También se podría especificar una plantilla distinta ([layout: 'other']). Las páginas resultantes:

Image

Image

Image

La plantilla, las vistas parciales y [res.locals] son exactamente lo que usa el caso de estudio: una plantilla ([layout.hbs]), vistas parciales para la barra de navegación, los mensajes y las ventanas de confirmación, y un middleware que prepara el idioma y el mensaje que se mostrará.

4.4. Ejemplo 16: helpers

Un helper es una función [TypeScript] que se puede llamar desde una vista. Compensa la falta de lógica de [Handlebars]: comparar dos valores, dar formato a una fecha o a un precio, traducir un texto... Los bloques [{{#if}}] y [{{#each}}] son en sí mismos helpers predefinidos.

El archivo [src/helpers.ts]:

import { HelperOptions } from 'handlebars';

// el módulo 'hbs' no tiene declaraciones de tipos: describimos lo que usamos de él
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}}: un helper simple, con un argumento
  hbs.registerHelper('uppercase', (text: unknown) => String(text ?? '').toUpperCase());

  // {{#if (eq a b)}}: usado como subexpresión, entre paréntesis
  hbs.registerHelper('eq', (a: unknown, b: unknown) => a === b);

  // {{active path '/products'}}: "active" si la página actual está bajo esta ruta
  hbs.registerHelper('active', (path: unknown, prefix: unknown) =>
    typeof path === 'string' && typeof prefix === 'string' && path.startsWith(prefix) ? 'active' : '',
  );

  // {{money amount currency='USD'}}: el ÚLTIMO argumento de un helper es siempre
  // el objeto [options] de Handlebars; options.hash contiene los
  // parámetros con nombre, options.data.root el modelo completo de la página (res.locals incluido)
  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}}: una fecha en el formato del idioma de la 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}}: un helper que construye HTML. SafeString le indica
  // a Handlebars que NO lo escape; le corresponde entonces al helper escapar
  // por sí mismo los datos que inserta en él (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>`);
  });
}

Comentemos este código:

  • líneas 4–7: el paquete [hbs] no tiene declaraciones de tipos [TypeScript]: describimos las que usamos;
  • línea 11: [hbs.registerHelper(name, fn)] define un helper. En una vista, [{{uppercase name}}] llama a la función con el valor de [name];
  • línea 14: [eq] devuelve un valor booleano. Se usa como subexpresión, entre paréntesis, dentro de otro helper: [{{#if (eq path '/')}}];
  • líneas 17–19: [active] devuelve la clase CSS [active] si la ruta de la página comienza con un prefijo dado;
  • líneas 24–28: el último argumento de un helper es siempre el objeto [options] que proporciona [Handlebars]. [options.hash] contiene los parámetros con nombre ([{{money amount currency='USD'}}]), y [options.data.root] contiene el modelo raíz de la página, al que se ha agregado [res.locals] . El helper obtiene de allí el idioma de la página, incluso si se lo llama desde dentro de un [{{#each}}]. El formato lo maneja el objeto estándar [Intl.NumberFormat];
  • líneas 31–34: el mismo principio se aplica a una fecha, con [Intl.DateTimeFormat];
  • Líneas 39–44: un helper que genera HTML. Por defecto, la salida de un helper se escapa, igual que cualquier expresión [{{...}}]. Para evitarlo, se devuelve en forma de [SafeString]. El helper debe entonces escapar [escapeExpression] por sí mismo los datos que inserta en su HTML.

El archivo [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');
  // los helpers: funciones TypeScript invocables desde las vistas
  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();
  • línea 18: los helpers se registran al iniciar;
  • línea 22: el middleware elige el idioma de formato según el parámetro [lang] de la URL (una forma sencilla de probar; el siguiente capítulo lo explicará mejor).

El archivo [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">
    {{!-- el enlace de la página actual recibe la clase "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>

Líneas 5–6: las dos maneras de resaltar el enlace de la página actual: [eq] como subexpresión dentro de un [{{#if}}], o el helper [active], que es más conciso. El caso de estudio usa [active].

El archivo [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>

Las páginas resultantes, primero en francés ([?lang=fr]) y luego en inglés ([?lang=en]):

Image

Image

Image

4.5. Ejemplo 17: un formulario GET

Un formulario HTML enviado con el método GET coloca sus campos en la URL. Es el método adecuado para una búsqueda: no modifica nada, y la URL resultante se puede guardar como marcador o compartir. El caso de estudio lo usa para seleccionar un médico y una fecha.

El archivo [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=...: el formulario Y sus 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 };
  }
}
  • líneas 9–15: los libros, en memoria;
  • línea 21: un arreglo de rutas: la acción procesa [GET /] y [GET /search];
  • línea 23: un valor por defecto, [TypeScript], reemplaza a un parámetro ausente (en la primera visita, el formulario aún no se ha enviado);
  • líneas 24–29: filtrado;
  • línea 30: el modelo contiene los valores ingresados ([keyword], [genre]), para que el formulario pueda volver a mostrarlos, junto con la lista de géneros y los resultados.

El archivo [views/search.hbs]:

<h1 class="h3">Book search</h1>
{{!-- method="get": los campos se envían en la URL (?keyword=...&genre=...) --}}
<form method="get" action="/search" class="row g-2 align-items-end mb-3">
  <div class="col-auto">
    <label class="form-label" for="keyword">Title or author</label>
    {{!-- value="{{keyword}}": el campo vuelve a mostrar lo que se escribió --}}
    <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>
  • Línea 3: [method="get"] y [action="/search"]: el envío del formulario es una solicitud [GET /search?keyword=...&genre=...]. Los nombres de los parámetros son el atributo [name] de cada campo;
  • Línea 7: el atributo [value] vuelve a mostrar lo ingresado;
  • líneas 13–15: en la lista desplegable, a la opción que corresponde a la categoría seleccionada se le asigna el atributo [selected]. En el bucle, [this] es el elemento actual (una cadena) y [../genre] es el género del modelo padre.

En la visualización inicial y luego de una búsqueda:

Image

Image

La barra de direcciones muestra los parámetros que se enviaron. Los caracteres acentuados y los espacios se codifican allí ([%C3%A9]...): es la codificación de URL, que [NestJS] decodifica antes de llenar [@Query].

4.6. Ejemplo 18: campos de formulario

El ejemplo 18 incluye todos los tipos de campos HTML: texto, contraseña, fecha, botones de opción, casillas de verificación, lista desplegable, lista de selección múltiple, cuadro de texto y campo oculto. Muestra cómo el servidor los recibe y cómo la vista los muestra.

El archivo [src/lists.service.ts]:

import { Injectable } from '@nestjs/common';

// las listas que ofrece el formulario. En una aplicación real, provendrían
// de una base de datos: las leeríamos UNA SOLA VEZ, al inicio,
// ya que son las mismas para todos los usuarios
@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'];
}

Las listas que ofrece el formulario las proporciona un servicio. Son las mismas para todos los usuarios: un servicio, instanciado una sola vez (ámbito de aplicación; véase el capítulo 6), es el lugar natural para almacenarlas.

El archivo [src/form.controller.ts]:

import { Body, Controller, Get, HttpCode, Post, Render } from '@nestjs/common';
import { ListsService } from './lists.service';

// lo que escribió el usuario, una vez puesto en forma
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: el formulario, con valores iniciales
  @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: recibimos los valores escritos y mostramos el formulario de nuevo
  @Post()
  @HttpCode(200) // un POST responde 201 por defecto; aquí devolvemos una 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);
  }

  // el modelo de la vista: las listas, cada opción marcada
  // checked / selected según la 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,
    };
  }
}

// un campo ausente (casilla sin marcar...) no se envía en absoluto
function text(value: unknown): string {
  return typeof value === 'string' ? value : '';
}

// un valor marcado: "sport"; dos: ["sport", "music"]; ninguno: undefined
function array(value: unknown): string[] {
  if (value === undefined) return [];
  return Array.isArray(value) ? value : [String(value)];
}

Comentemos este código:

  • líneas 5–15: ingreso y formato de los datos: las casillas de verificación y la lista desplegable son arreglos;
  • línea 19: se inyecta el servicio de listas;
  • líneas 22–30: [GET /form] muestra el formulario con valores iniciales;
  • línea 34: [POST /form] devuelve una página, no un recurso creado: reemplazamos el código 201 por 200;
  • líneas 37–47: los campos recibidos se reformatean. Dos casos requieren atención: un campo ausente (una casilla sin marcar no se envía en absoluto, véase la función [text], líneas 66–68), y un campo multivalor, que llega como cadena si tiene un solo valor (función [array], líneas 71–74, véase el ejemplo 10);
  • líneas 53–62: el modelo de la vista. Para cada lista, la acción calcula qué opciones deben aparecer marcadas o seleccionadas: la vista solo necesita evaluar un valor booleano. El campo [received] contiene lo que recibió el servidor, con fines de visualización.

El archivo [views/form.hbs]:

<h1 class="h3">A complete form</h1>
<form method="post" action="/form" style="max-width: 40rem">
  {{!-- campo oculto: se envía con el formulario, pero es invisible --}}
  <input type="hidden" name="token" value="{{input.token}}">

  <div class="mb-2">
    <span class="form-label me-3">Title</span>
    {{#each titles}}
      {{!-- botones de opción (radio): mismo [name], se envía un solo valor --}}
      <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>
      {{!-- una contraseña NUNCA se devuelve en la 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}}
      {{!-- casillas de verificación: mismo [name], varios valores posibles --}}
      <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 selección múltiple: varios valores posibles --}}
      <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>
    {{!-- un área de texto: el valor va ENTRE las etiquetas --}}
    <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}}

Comentemos este código:

  • línea 2: el formulario se envía mediante POST; sus campos se incluyen en el cuerpo de la solicitud;
  • línea 4: un campo oculto se envía con el formulario pero no se muestra. Sirve para transmitir información de una página a la siguiente (el caso de estudio lo usa, por ejemplo, para guardar la versión de un registro). Atención: el usuario puede modificarlo;
  • líneas 8–15: los botones de opción comparten el mismo atributo [name]: solo se puede seleccionar uno y solo se envía un valor. El atributo [checked] selecciona el botón;
  • línea 26: una contraseña nunca se reenvía en una página: el campo no tiene el atributo [value];
  • línea 30: un campo de fecha. El navegador muestra la fecha en el formato del usuario, pero siempre envía [yyyy-mm-dd];
  • líneas 36–43: casillas de verificación con el mismo atributo [name]: cada casilla marcada envía su valor; el parámetro se repite, por lo tanto;
  • líneas 49–53: una lista desplegable. La opción seleccionada tiene el atributo [selected];
  • líneas 58–62: el atributo [multiple] permite seleccionar varias opciones;
  • línea 69: el valor de un campo de texto va entre sus etiquetas, no en un atributo [value];
  • Líneas 75–78: lo que recibió el servidor, mostrado dentro de una etiqueta [<pre>].

El formulario inicial y luego después del envío:

Image

Image

Observe que el cuadro de texto volvió a mostrar [Hello <b>everyone</b>] exactamente como se ingresó: gracias al escape de [{{...}}], las etiquetas ingresadas no se interpretan. La contraseña se recibió pero no se muestra. Con [curl], podemos ver la diferencia cuando se selecciona una casilla:

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"
}

y dos casillas 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"
  ]
}

(solo se muestra la sección [What the server received] de la página)

4.7. Ejemplo 19: validación de formularios

Un formulario no válido debe volver a mostrarse, con los valores ingresados y un mensaje debajo de cada campo con error. El ejemplo 19 aplica la técnica del ejemplo 09 (validación realizada por la acción) a un formulario de registro.

El archivo [src/registration.dto.ts]:

import { Transform, Type } from 'class-transformer';
import { IsEmail, IsInt, IsNotEmpty, Max, MaxLength, Min, MinLength } from 'class-validator';

// elimina los espacios sobrantes de una entrada ANTES de su validación
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;

  // todo lo que proviene de un formulario es una cadena: "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" involucra DOS campos: es el
  // controlador quien lo verifica
  confirmation: string;
}
  • Línea 5: una función de limpieza, aplicada por [@Transform] antes de la validación: un nombre formado por espacios se convierte en una cadena vacía, y [@IsNotEmpty] lo rechaza;
  • Líneas 18–22: la edad se convierte en número y luego se valida;
  • Líneas 27–29: la regla “la confirmación coincide con la contraseña” afecta a dos campos: los decoradores no la ven, pero el controlador la verificará.

El archivo [src/validation.ts]:

import { ClassConstructor, plainToInstance } from 'class-transformer';
import { validate } from 'class-validator';

// errores 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 recibido -> instancia de la clase (se aplican @Transform / @Type)
  const dto = plainToInstance(cls, body);
  // 2. verificación de todas las restricciones
  const violations = await validate(dto);
  // 3. conservamos el primer mensaje de cada campo inválido
  const errors: Errors = {};
  for (const v of violations) {
    errors[v.property] = Object.values(v.constraints ?? {})[0];
  }
  return { dto, errors };
}
  • línea 5: los errores se organizan por campo: [{ name: 'The name is required.' }], lo que permite mostrar cada mensaje debajo de su campo correspondiente;
  • líneas 7–10: la función es genérica: valida cualquier clase de formulario. Devuelve la instancia convertida ([dto]) y los errores;
  • Líneas 17–19: un campo puede infringir varias restricciones; solo se conserva el primer mensaje de error.

El caso de estudio tiene la misma función ([web/helpers/form.helper.ts]).

El archivo [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: dejamos que el navegador valide el formulario antes de enviarlo
  @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);
    // una regla que involucra dos campos
    if (!errors.password && body.confirmation !== body.password) {
      errors.confirmation = 'The confirmation does not match the password.';
    }
    if (Object.keys(errors).length > 0) {
      // MOSTRAMOS el formulario DE NUEVO: valores escritos (excepto las contraseñas)
      // y un mensaje bajo 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 });
  }
}
  • líneas 9–13: el formulario vacío. El parámetro [html5] se explicará más adelante;
  • línea 21: validación de cada campo;
  • líneas 23–25: seguida de la regla que afecta a dos campos;
  • líneas 26–36: si hay errores, se vuelve a mostrar el formulario: los valores ingresados (excepto las contraseñas), los errores por campo y un mensaje general;
  • línea 37: en caso contrario, la página de bienvenida, con los valores convertidos por [dto] (la edad es un número, el nombre ha sido limpiado).

Todos los campos se construyen con la misma plantilla: un archivo parcial se encarga de ello.

El archivo [views/partials/field.hbs]:

1
2
3
4
5
6
7
8
{{!-- un campo de entrada; parámetros: name, label, type, value, error, y
      attributes = los atributos de validación 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>
  • línea 5: la clase [Bootstrap] [is-invalid] resalta en rojo un campo no válido;
  • línea 6: los atributos de validación HTML5 se pasan como parámetros y se insertan sin escapar (tres llaves): los escribe el desarrollador, no los ingresa el usuario;
  • línea 7: el mensaje de error, debajo del campo (clase [invalid-feedback]).

El archivo [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: el navegador ignora los atributos required, min... y
      envía el formulario tal cual; solo el 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>
  • línea 9: el atributo [novalidate] está presente cuando [html5] es falso;
  • líneas 10–19: cada campo es una llamada al parcial, con parámetros con nombre. Un parámetro puede ser un valor del modelo ([value=values.name]).

El archivo [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}}}
    {{!-- el error global, al pie de la página, sobre un fondo rosa claro --}}
    {{#if globalError}}
      <div class="error-area" role="alert">{{globalError}}</div>
    {{/if}}
  </div>
</body>
</html>

líneas 13–15: el mensaje global se muestra al final de la página sobre un fondo rosa claro (clase [error-area] de [public/css/styles.css]), como en el caso de estudio.

Enviemos el formulario con varios errores:

Image

y luego correctamente completado:

Image

4.7.1. Validación por el navegador

Los atributos [required], [maxlength], [min], [max], [type="email"]... indican al navegador que valide el formulario antes de enviarlo: el usuario recibe un aviso inmediato mediante un globo de ayuda, sin ninguna comunicación de ida y vuelta con el servidor. Este es el comportamiento que activa el enlace “enable it” ([/register?html5=1]), que elimina el atributo [novalidate] del formulario.

Esta validación es una comodidad, no una medida de seguridad: se puede eludir simplemente eliminando el atributo [required] con las herramientas de desarrollo del navegador, o enviando la solicitud con [curl]. La validación en el servidor sigue siendo esencial. Por eso el ejemplo desactiva por defecto la validación del navegador: para demostrar cómo funciona el servidor. El caso de estudio, en cambio, conserva ambas: los atributos HTML5 por comodidad y la validación en el servidor por seguridad.

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

Cuando un formulario POST se envía con éxito, la acción puede mostrar una página directamente. El problema surge si el usuario actualiza esa página (tecla F5): el navegador reenvía el formulario, y la operación se ejecuta por segunda vez (un pedido realizado dos veces, una cita reservada dos veces...). El patrón Post / Redirect / Get (PRG) evita este problema: una acción POST exitosa no genera una página; en su lugar, redirige a una página GET. Al recargar esta página solo se envía la solicitud GET, que no tiene ningún efecto.

Queda un detalle: la página GET debe mostrar un mensaje (“la tarea se ha agregado”), aunque este mensaje lo haya generado la acción POST en una solicitud distinta. Se transmite en una cookie de corta duración, que la siguiente solicitud lee y elimina: es un mensaje flash.

El archivo [src/flash.ts]:

import { NextFunction, Request, Response } from 'express';

const FLASH_COOKIE = 'flash';

// almacena un mensaje que mostrará la página SIGUIENTE, y solo una vez
export function flash(res: Response, message: string): void {
  res.cookie(FLASH_COOKIE, message, { httpOnly: true, sameSite: 'lax', maxAge: 60_000 });
}

// en cada solicitud: el mensaje pendiente pasa de la cookie a res.locals (y por lo tanto
// al modelo de la vista), y la cookie se borra
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();
}
  • líneas 6–8: [res.cookie(name, value, options)] define una cookie: el navegador la reenviará con cada solicitud posterior. Opciones: [httpOnly] (el [JavaScript] de la página no puede leerla), [sameSite: 'lax'] (no se envía en solicitudes POST provenientes de otros sitios), [maxAge] (duración: un minuto, más que suficiente para seguir la redirección);
  • Líneas 12–18: un middleware que se ejecuta antes de cada solicitud: si hay un mensaje, pasa de la cookie a [res.locals], y por lo tanto al modelo de la vista, y la cookie se borra ([res.clearCookie]): el mensaje se mostrará una sola vez.

El archivo [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 llena req.cookies con las cookies enviadas por el navegador
  app.use(cookieParser());
  // luego nuestro middleware lee (y borra) el mensaje flash pendiente
  app.use(flashMiddleware);
  await app.listen(3000);
  console.log('Server started on http://localhost:3000');
}

bootstrap();
  • línea 17: el middleware [cookie-parser] decodifica el encabezado [Cookie] de la solicitud y completa el objeto [req.cookies];
  • línea 19: nuestro middleware, que requiere [req.cookies], se registra después de este: los middleware se ejecutan en el orden en que se registran.

El archivo [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: la lista y el formulario de adición
  @Get()
  display(@Res() res: Response): void {
    res.render('tasks', { tasks: this.tasks.list() });
  }

  // POST /tasks: el patrón 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: mostramos la página de nuevo, sin redirección
      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.`);
    // sin página: una redirección a la página GET
    res.redirect('/tasks');
  }

  // POST /tasks/without-prg: el contraejemplo (una página como respuesta al 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 });
  }
}
  • líneas 11–14: la página de la lista;
  • líneas 20–27: una entrada no válida: la página se vuelve a mostrar (sin redirección: se deben conservar la entrada y el mensaje de error);
  • líneas 29–32: una entrada válida: la operación, el mensaje emergente y luego una redirección 302 a la página GET;
  • líneas 36–40: el contraejemplo, para comparar.

El archivo [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ón envía el MISMO formulario a otra dirección --}}
  <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/tasks/without-prg">Add without PRG</button>
</form>
{{#if 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}}

línea 9: el atributo [formaction] de un botón envía el formulario a una dirección distinta de la del atributo [action] del formulario. Así, el formulario tiene dos botones, que activan dos acciones diferentes. El caso de estudio usa este método en su página de inicio de sesión.

El archivo [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">
    {{!-- el mensaje flash, en la parte superior de la 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>

El mensaje flash se muestra en la parte superior de la página (líneas 12–14) y el mensaje de error en la parte inferior (líneas 16–18).

Esto es lo que ve [curl] cuando el formulario se envía con éxito. La opción [-c file] guarda las cookies recibidas, mientras que [-b file] las reenvía:

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

La respuesta es una redirección, con la cookie [flash] (su contenido está codificado). La siguiente solicitud envía la cookie; la respuesta la elimina (fecha de expiración en el pasado):

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

En el navegador, después de agregar una tarea:

Image

La barra de direcciones muestra [/tasks]: es la página GET. Se puede recargar sin riesgo; el mensaje desaparecerá. Una entrada vacía:

Image

Y el contraejemplo:

Image

Aquí, recargar la página provoca una advertencia del navegador (“Confirmar reenvío del formulario”) y luego agrega la tarea por segunda vez. Todos los formularios POST del caso de estudio siguen el patrón PRG.

4.9. Ejemplo 21: enlaces, botones y confirmación

Una regla simple guía la elección entre un enlace y un botón:

  • un enlace ([<a href>]) genera una solicitud GET. Una solicitud GET no debe modificar nada: los navegadores, los motores de búsqueda y los antivirus pueden seguir los enlaces por su cuenta para preparar o analizar una página;
  • una operación que modifica datos (agregar, editar, eliminar, cerrar sesión) es un botón dentro de un formulario POST.

El ejemplo 21 administra una lista de contactos: se consulta un contacto mediante un enlace y se elimina mediante un botón, que abre una ventana de confirmación.

El archivo [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) {}

  // un ENLACE (<a href>): una solicitud GET, que no 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) };
  }

  // un BOTÓN en un formulario POST: una solicitud que modifica datos
  @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');
  }

  // mismo formulario, otro botón (atributo formaction): otra acción
  @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');
  }
}
  • líneas 11–15 y 17–21: las dos páginas, la lista y el detalle del contacto. [ParseIntPipe] convierte el identificador; un contacto inexistente genera un error 404 (véase el servicio);
  • líneas 24–29: guardado de un registro, mediante PRG;
  • líneas 36–41: duplicación, activada por un segundo botón del mismo formulario (atributo [formaction]);
  • líneas 47–52: eliminación, mediante POST.

El archivo [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">
          {{!-- vista: un enlace simple --}}
          <a class="btn btn-sm btn-outline-primary" href="/contacts/{{id}}">View</a>
          {{!-- eliminar: un formulario POST, cuyo envío 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>
  • línea 10: consultar: un enlace, mostrado como botón por [Bootstrap];
  • líneas 12–15: eliminar: un formulario pequeño (POST), reducido a su botón. El atributo [data-confirmation] contiene la pregunta que se debe hacer antes del envío. Los atributos [data-*] son opcionales: HTML los ignora, mientras que el [JavaScript] de la página puede leerlos.

El archivo [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>
  {{!-- dos botones de envío para el mismo formulario --}}
  <button class="btn btn-primary" type="submit">Save</button>
  <button class="btn btn-outline-primary" type="submit" formaction="/contacts/{{contact.id}}/duplicate">Duplicate</button>
  <a class="btn btn-link" href="/contacts">Back to the list</a>
</form>

Línea 13: dos botones de envío para el mismo formulario.

4.9.1. La ventana de confirmación

El cuadro de diálogo del navegador ([window.confirm]) no se puede formatear ni traducir: sus botones permanecen en el idioma del navegador. Se reemplaza por una ventana [Bootstrap], escrita en la página y oculta hasta que se necesita:

El archivo [views/partials/confirmation.hbs]:

{{!-- una sola ventana para toda la página, oculta (d-none) al inicio --}}
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title">Confirmation</h5>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-secondary" data-action="no">No, go back</button>
          <button type="button" class="btn btn-danger" data-action="yes">Yes, confirm</button>
        </div>
      </div>
    </div>
  </div>
</div>
  • línea 2: la clase [d-none] oculta la ventana;
  • línea 3: el fondo gris;
  • línea 11: la posición de la pregunta;
  • líneas 14–15: los dos botones, identificados por el atributo [data-action].

Un poco de [JavaScript] vincula los formularios con la ventana:

El archivo [public/js/app.js]:

// confirmación de los formularios que llevan el atributo data-confirmation="..."
// Sin JavaScript, estos formularios simplemente se envían sin confirmación.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // el formulario que se enviará si el usuario confirma

  // 1. interceptamos el envío de los formularios que requieren confirmación
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // el envío queda suspendido
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // aparece la ventana
    });
  });

  // 2. los dos botones de la ventana
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // envío, SIN disparar de nuevo el evento 'submit'
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • Línea 3: el código está envuelto en una función que se ejecuta de inmediato, para evitar crear variables globales;
  • líneas 9–16: se intercepta el envío de cada formulario que tenga el atributo [data-confirmation]. [preventDefault()] suspende el envío; el formulario se guarda, la pregunta se coloca en la ventana ([textContent], no [innerHTML]: la pregunta se muestra como texto, nunca se interpreta como HTML) y se muestra la ventana;
  • Líneas 19–27: «Yes» envía el formulario guardado. El método [submit()] de un formulario lo envía sin desencadenar el evento [submit]: no aparece una nueva solicitud de confirmación. «No» oculta la ventana.

Si [JavaScript] está deshabilitado, los formularios simplemente se envían sin confirmación: la aplicación sigue funcionando. Este es el principio de la mejora incremental: [JavaScript] aporta comodidad, pero no es esencial. El caso de estudio sigue este principio (su script [public/js/app.js] añade el manejo del teclado: tecla Esc, foco). Las páginas resultantes:

Image

Image

Image

Image

Por último, verificamos que la eliminación no se pueda activar mediante una solicitud 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