Skip to content

4. Die View und ihr Modell

Bisher haben die Actions ihre Antworten selbst erzeugt. In einer MVC-Anwendung ist das die Aufgabe einer View: einer Datei, die die HTML-Seite beschreibt, mit Platzhaltern für die Daten, die die Action ihr übergibt – das Modell der View. Wir verwenden die View-Engine [Handlebars] über das Paket [hbs], das sie an [Express] anpasst.

4.1. Beispiel 13: Eine erste View

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

Die Datei [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: gibt Zugriff auf die Express-spezifischen Methoden
  const app = await NestFactory.create<NestExpressApplication>(AppModule);
  // die Views liegen im Ordner [views] im Wurzelverzeichnis des Projekts;
  // nach der Kompilierung liegt diese Datei in dist/: das Wurzelverzeichnis ist daher '..'
  app.setBaseViewsDir(join(__dirname, '..', 'views'));
  // die View-Engine: Handlebars, bereitgestellt durch das Paket [hbs]
  app.setViewEngine('hbs');
  await app.listen(3000);
  console.log('Server started on http://localhost:3000');
}

bootstrap();

Gehen wir diesen Code im Einzelnen durch:

  • Zeile 2: [NestExpressApplication] ist der Typ einer [NestJS] -Anwendung, die auf [Express] aufbaut ([NestJS] kann auch den Server [Fastify] verwenden). Durch diese Angabe erhält man Zugriff auf die für [Express] spezifischen Methoden: [setBaseViewsDir], [setViewEngine], [useStaticAssets];
  • Zeile 8: Der Typ wird an [NestFactory.create] übergeben;
  • Zeile 11: der Views-Ordner. [__dirname] ist der Ordner der aktuell ausgeführten Datei: [dist], da [dist/main.js] gerade ausgeführt wird. Der Ordner [views] liegt also in [dist/../views];
  • Zeile 13: die View-Engine: [hbs]. Die Views sind die [.hbs]-Dateien im Views-Ordner.

Die Datei [src/views.controller.ts]:

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

@Controller()
export class ViewsController {
  // @Render('index'): das von der Action zurückgegebene Objekt ist das MODELL der View
  // views/index.hbs; NestJS ruft die View-Engine selbst auf
  @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): die View wird WÄHREND der Ausführung der Action gewählt
  @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'),
    });
  }
}
  • Zeilen 8–9: [@Render('index')] verweist auf die View [views/index.hbs]. Das von der Action zurückgegebene Objekt ist nicht mehr die Antwort, sondern das Modell der View;
  • Zeilen 11–15: das Modell: drei Werte, [title], [message] und [time];
  • Zeilen 19–30: Hängt die View von der Anfrage ab, verwendet die Action [res.render(view, model)] der [Express] -Antwort (injiziert durch [@Res()]; siehe Beispiel 05). Hier zeigt der Name [unknown] eine andere View mit dem Statuscode 404 an.

Die Datei [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>

Eine [Handlebars]-View ist eine HTML-Datei. Jedes Vorkommen von [{{title}}] (Zeilen 5, 8) wird durch den Wert des entsprechenden Felds im Modell ersetzt. Das Ergebnis:

Image

Der Quellcode der vom Browser empfangenen Seite enthält keine Spur von [Handlebars] mehr:

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

Die URL [/hello/martin] zeigt dieselbe View mit einem anderen Modell an:

Image

und [/hello/unknown] zeigt wiederum eine andere View an:

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. Beispiel 14: Die Sprache Handlebars

[Handlebars] ist eine Template-Sprache ohne Logik: Eine View enthält keinen [JavaScript]-Code, sondern nur [{{...}}]-Ausdrücke und einige Blöcke ([{{#if}}], [{{#each}}] ...). Alle Berechnungen werden vorher von der Action durchgeführt. Beispiel 14 demonstriert das. Das Modell:

Die Datei [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' },
    };
  }
}

Die View:

Die Datei [views/basics.hbs]:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{title}}</title>
</head>
<body>
  <h1>{{title}}</h1>
  {{!-- 1. einen Wert des Modells anzeigen --}}
  <p>1. Name: {{name}} - missing variable: [{{nonexistent}}]</p>
  {{!-- 2. {{ }} maskiert HTML, {{{ }}} fügt es unverändert ein --}}
  <p>2a. {{html}}</p>
  <p>2b. {{{html}}}</p>
  {{!-- 3. eine Bedingung --}}
  {{#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. eine Schleife; innerhalb der Schleife ist der Kontext das aktuelle Element --}}
  <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}} in einer Schleife: der Fall der leeren Liste --}}
  <p>5. Your cart:
    {{#each cart}}{{name}}{{else}}it is empty.{{/each}}
  </p>
  {{!-- 6. den Kontext wechseln oder einen Punktpfad verwenden --}}
  {{#with address}}
    <p>6a. Address: {{street}}, {{city}}</p>
  {{/with}}
  <p>6b. City: {{address.city}}</p>
</body>
</html>

Kommentieren wir diesen Code:

  • Zeile 9: [{{!-- ... --}}] ist ein Kommentar ([Handlebars]): Er erscheint nicht auf der erzeugten Seite (anders als ein HTML-Kommentar wie [<!-- -->]);
  • Zeile 10: Eine im Modell fehlende Variable ([nonexistent]) erzeugt einen leeren String, ohne Fehler;
  • Zeilen 12–13: [{{html}}] maskiert die Sonderzeichen in HTML ([<] wird zu [&lt;] ...): Der Text wird unverändert angezeigt. [{{{html}}}] (drei geschweifte Klammern) wird ohne Maskierung eingefügt: Es wird als HTML interpretiert. Dreifache geschweifte Klammern werden nur für HTML verwendet, das von der Anwendung erzeugt wurde, niemals für Benutzereingaben: Ein Benutzer könnte HTML oder sogar [JavaScript] in die Seite einschleusen (ein sogenannter [XSS]-Angriff);
  • Zeilen 15–19: [{{#if}}] / [{{else}}] / [{{/if}}]: ein bedingter Block. Die Bedingung ist ein Wert aus dem Modell, kein Ausdruck: [false], [undefined], [null], [''], [0] und das leere Array gelten als falsch;
  • Zeilen 20–22: [{{#unless}}] ist das Gegenteil von [{{#if}}];
  • Zeilen 26–32: [{{#each}}] wiederholt seinen Inhalt für jedes Element eines Arrays. Innerhalb des Blocks ist der Kontext das aktuelle Element: [{{name}}] ist der Name des aktuellen Produkts. Es stehen spezielle Variablen zur Verfügung: [@index] (Position, bei 0 beginnend), [@first], [@last]. [../currency] verweist auf den übergeordneten Kontext, [@root.name] auf das Wurzelmodell;
  • Zeile 36: Ein [{{else}}] innerhalb eines [{{#each}}] behandelt den Fall eines leeren Arrays;
  • Zeilen 39–41: [{{#with}}] wechselt den Kontext; es kann auch ein relativer Pfad verwendet werden (Zeile 42).

Image

Der erzeugte HTML-Code:

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

Beachten Sie die von den Blöcken hinterlassenen Leerzeilen: Sie haben keinen Einfluss auf die Anzeige.

4.3. Beispiel 15: Layout, Partials, statische Dateien

Die Seiten einer Website teilen sich ein gemeinsames Layout (Kopfbereich, Navigationsleiste, Fußbereich). [hbs] handhabt dies wie folgt: Enthält der Views-Ordner eine Datei namens [layout.hbs], wird jede View in dieses Layout eingefügt. Wiederverwendbare Seitenfragmente heißen Partial Views.

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

Die Datei [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. statische Dateien: public/css/styles.css wird als /css/styles.css ausgeliefert
  app.useStaticAssets(join(ROOT, 'public'));
  // Bootstrap wird direkt aus node_modules ausgeliefert, unter /bootstrap/
  app.useStaticAssets(join(dirname(require.resolve('bootstrap/package.json')), 'dist'), { prefix: '/bootstrap/' });

  // 2. die Views; views/layout.hbs ist das Layout ALLER Seiten
  app.setBaseViewsDir(join(ROOT, 'views'));
  app.setViewEngine('hbs');
  // 3. die Partials: views/partials/xxx.hbs wird mit {{> xxx}} eingefügt
  await new Promise<void>((done) => hbs.registerPartials(join(ROOT, 'views', 'partials'), () => done()));

  // 4. eine Express-Middleware: was sie in res.locals ablegt, wird
  //    dem Modell JEDER View hinzugefügt
  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();

Gehen wir diesen Code im Einzelnen durch:

  • Zeile 14: [useStaticAssets] liefert statische Dateien aus einem Ordner aus: Die Datei [public/css/styles.css] wird unter der URL [/css/styles.css] unverändert ausgeliefert, ohne einen Controller zu durchlaufen;
  • Zeile 16: Das CSS-Framework [Bootstrap] wird direkt aus dem Ordner [node_modules] unter dem Präfix [/bootstrap/] ausgeliefert. [require.resolve] findet den Ordner des Pakets [bootstrap], wo auch immer es installiert ist (hier in [examples/node_modules]);
  • Zeile 22: Die Dateien im Ordner [views/partials] werden zu Partial-Dateien: [partials/navbar.hbs] wird mit [{{> navbar}}] in eine View eingefügt. [registerPartials] liest den Ordner asynchron: Wir warten, bis das Lesen beendet ist (die als zweites Argument übergebene Funktion wird am Ende aufgerufen), bevor wir den Server starten;
  • Zeilen 26–30: eine [Express]-Middleware, die vor jeder Anfrage ausgeführt wird. Was sie in [res.locals] ablegt, wird dem Modell jeder View hinzugefügt. So stellen wir allen Seiten gemeinsame Informationen (hier den angeforderten Pfad und das Jahr) bereit, ohne sie in jeder Action zu wiederholen.

Die Datei [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}}
    {{!-- hier wird die von der Action angeforderte View eingefügt --}}
    {{{body}}}
    <footer class="footer">Page [{{path}}] - © {{year}}</footer>
  </div>
</body>
</html>
  • Zeilen 7–8: die Stylesheets, ausgeliefert von [useStaticAssets];
  • Zeile 12: Einfügen des Partials [navbar];
  • Zeile 14: [{{{body}}}] ist die Stelle, an der [hbs] die von der Action angeforderte View einfügt. Dreifache geschweifte Klammern: Die View stammt aus bereits erzeugtem HTML und darf nicht maskiert werden;
  • Zeile 15: [path] und [year] stammen aus [res.locals] (der Middleware von [main.ts]).

Die Datei [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>

Die Datei [views/partials/card.hbs]:

1
2
3
4
5
6
7
{{!-- eine Bootstrap-"card"; Parameter: name, role --}}
<div class="card">
  <div class="card-body">
    <h5 class="card-title">{{name}}</h5>
    <p class="card-text">{{role}}</p>
  </div>
</div>

Das Partial [card] zeigt einen Namen und eine Berufsbezeichnung an. Es wird auf zwei Arten verwendet:

Die Datei [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"}}

Zeile 4: mit benannten Parametern: Das Partial erhält sie als Kontext;

Die Datei [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">
      {{!-- ohne Parameter erhält das Partial den aktuellen Kontext: das Mitglied --}}
      {{> card}}
    </div>
  {{/each}}
</div>

Zeile 6: keine Parameter: Das Partial erhält den aktuellen Kontext, hier das aktuelle Teammitglied in der Schleife [{{#each}}].

Die Datei [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: die View wird ALLEIN gerendert, ohne das gemeinsame Layout
  @Get('raw')
  @Render('raw')
  raw(): object {
    return { layout: false };
  }
}

Zeilen 25–29: Das Feld [layout: false] im Modell weist [hbs] an, das Layout nicht zu verwenden: Die View [raw.hbs] ist eine vollständige HTML-Seite. Wir könnten auch ein anderes Layout angeben ([layout: 'other']). Die resultierenden Seiten:

Image

Image

Image

Das Layout, die Partial Views und [res.locals] sind genau das, was die Fallstudie verwendet: ein Layout ([layout.hbs]), Partial Views für die Navigationsleiste, Meldungen und Bestätigungsfenster sowie eine Middleware, die die Sprache und die anzuzeigende Meldung vorbereitet.

4.4. Beispiel 16: Helper

Ein Helper ist eine [TypeScript]-Funktion, die aus einer View aufgerufen werden kann. Er gleicht die fehlende Logik in [Handlebars] aus: zwei Werte vergleichen, ein Datum oder einen Preis formatieren, Text übersetzen ... Die Blöcke [{{#if}}] und [{{#each}}] sind selbst vordefinierte Helper.

Die Datei [src/helpers.ts]:

import { HelperOptions } from 'handlebars';

// das Modul 'hbs' hat keine Typdeklarationen: wir beschreiben, was wir davon verwenden
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}}: ein einfacher Helper mit einem Argument
  hbs.registerHelper('uppercase', (text: unknown) => String(text ?? '').toUpperCase());

  // {{#if (eq a b)}}: als Subexpression verwendet, in runden Klammern
  hbs.registerHelper('eq', (a: unknown, b: unknown) => a === b);

  // {{active path '/products'}}: "active", wenn die aktuelle Seite unter diesem Pfad liegt
  hbs.registerHelper('active', (path: unknown, prefix: unknown) =>
    typeof path === 'string' && typeof prefix === 'string' && path.startsWith(prefix) ? 'active' : '',
  );

  // {{money amount currency='USD'}}: das LETZTE Argument eines Helpers ist immer
  // das Handlebars-Objekt [options]; options.hash enthält die benannten
  // Parameter, options.data.root das vollständige Modell der Seite (einschließlich res.locals)
  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}}: ein Datum im Format der Sprache der Seite
  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}}: ein Helper, der HTML erzeugt. SafeString weist
  // Handlebars an, es NICHT zu escapen; der Helper muss dann selbst
  // die Daten escapen, die er darin einfügt (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>`);
  });
}

Kommentieren wir diesen Code:

  • Zeilen 4–7: Das Paket [hbs] hat keine [TypeScript]-Typdeklarationen: Wir beschreiben, welche wir verwenden;
  • Zeile 11: [hbs.registerHelper(name, fn)] definiert einen Helper. In einer View ruft [{{uppercase name}}] die Funktion mit dem Wert von [name] auf;
  • Zeile 14: [eq] gibt einen booleschen Wert zurück. Es wird als Teilausdruck in Klammern innerhalb eines anderen Helpers verwendet: [{{#if (eq path '/')}}];
  • Zeilen 17–19: [active] gibt die CSS-Klasse [active] zurück, wenn der Pfad der Seite mit einem bestimmten Präfix beginnt;
  • Zeilen 24–28: Das letzte Argument eines Helpers ist immer das Objekt [options], das [Handlebars] bereitstellt. [options.hash] enthält die benannten Parameter ([{{money amount currency='USD'}}]), und [options.data.root] enthält das Wurzelmodell der Seite, dem [res.locals] hinzugefügt wurde. Der Helper ermittelt dort die Sprache der Seite, selbst wenn er innerhalb eines [{{#each}}] aufgerufen wird. Die Formatierung übernimmt das Standardobjekt [Intl.NumberFormat];
  • Zeilen 31–34: Dasselbe Prinzip gilt für ein Datum, mit [Intl.DateTimeFormat];
  • Zeilen 39–44: Ein Helper, der HTML erzeugt. Standardmäßig wird die Ausgabe eines Helpers maskiert, genau wie jeder [{{...}}]-Ausdruck. Um dies zu vermeiden, wird sie als [SafeString] zurückgegeben. Der Helper muss dann die Daten, die er in sein HTML einfügt, [escapeExpression] selbst maskieren.

Die Datei [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');
  // die Helper: TypeScript-Funktionen, die aus den Views aufrufbar sind
  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();
  • Zeile 18: Die Helper werden beim Start registriert;
  • Zeile 22: Die Middleware wählt die Formatierungssprache anhand des Parameters [lang] in der URL aus (eine einfache Möglichkeit zum Testen; das nächste Kapitel erklärt es besser).

Die Datei [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">
    {{!-- der Link der aktuellen Seite erhält die Klasse "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>

Zeilen 5–6: Die beiden Möglichkeiten, den Link der aktuellen Seite hervorzuheben: [eq] als Teilausdruck in einem [{{#if}}] oder der Helper [active], der prägnanter ist. Die Fallstudie verwendet [active].

Die Datei [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>

Die resultierenden Seiten, zuerst auf Französisch ([?lang=fr]) und dann auf Englisch ([?lang=en]):

Image

Image

Image

4.5. Beispiel 17: Ein GET-Formular

Ein per GET-Methode gesendetes HTML-Formular legt seine Felder in die URL. Das ist die geeignete Methode für eine Suche: Sie verändert nichts, und die resultierende URL kann als Lesezeichen gespeichert oder geteilt werden. Die Fallstudie verwendet sie, um einen Arzt und ein Datum auszuwählen.

Die Datei [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=...: das Formular UND seine Ergebnisse
  @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 };
  }
}
  • Zeilen 9–15: die Bücher, im Speicher;
  • Zeile 21: ein Array von Pfaden: Die Action bearbeitet [GET /] und [GET /search];
  • Zeile 23: Ein Standardwert, [TypeScript], ersetzt einen fehlenden Parameter (beim ersten Besuch wurde das Formular noch nicht gesendet);
  • Zeilen 24–29: Filterung;
  • Zeile 30: Das Modell enthält die eingegebenen Werte ([keyword], [genre]), damit das Formular sie zusammen mit der Liste der Genres und den Ergebnissen erneut anzeigen kann.

Die Datei [views/search.hbs]:

<h1 class="h3">Book search</h1>
{{!-- method="get": die Felder werden in der URL gesendet (?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}}": das Feld zeigt erneut an, was eingegeben wurde --}}
    <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>
  • Zeile 3: [method="get"] und [action="/search"]: Das Absenden des Formulars ist eine [GET /search?keyword=...&genre=...]-Anfrage. Die Parameternamen sind das Attribut [name] jedes Felds;
  • Zeile 7: Das Attribut [value] zeigt die Eingabe erneut an;
  • Zeilen 13–15: In der Dropdown-Liste erhält die Option, die der ausgewählten Kategorie entspricht, das Attribut [selected]. In der Schleife ist [this] das aktuelle Element (ein String) und [../genre] das Genre des übergeordneten Modells.

Bei der ersten Anzeige und anschließend nach einer Suche:

Image

Image

Die Adressleiste zeigt die gesendeten Parameter an. Akzentuierte Zeichen und Leerzeichen sind dort kodiert ([%C3%A9] ...): Das ist die URL-Kodierung, die [NestJS] dekodiert, bevor es [@Query] befüllt.

4.6. Beispiel 18: Formularfelder

Beispiel 18 enthält alle Arten von HTML-Feldern: Text, Passwort, Datum, Optionsfelder, Kontrollkästchen, Dropdown-Liste, Mehrfachauswahlliste, Textfeld mit mehreren Zeilen und verstecktes Feld. Es zeigt, wie der Server sie empfängt und wie die View sie anzeigt.

Die Datei [src/lists.service.ts]:

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

// die vom Formular angebotenen Listen. In einer echten Anwendung würden sie
// aus einer Datenbank stammen: wir würden sie nur EINMAL beim Start lesen,
// da sie für alle Benutzer gleich sind
@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'];
}

Die vom Formular angebotenen Listen werden von einem Service bereitgestellt. Sie sind für alle Benutzer gleich: Ein Service, der nur einmal instanziiert wird (Anwendungs-Scope; siehe Kapitel 6), ist der natürliche Ort, um sie zu speichern.

Die Datei [src/form.controller.ts]:

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

// was der Benutzer eingegeben hat, in Form gebracht
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: das Formular mit Anfangswerten
  @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: wir erhalten die eingegebenen Werte und zeigen das Formular erneut an
  @Post()
  @HttpCode(200) // ein POST antwortet standardmäßig mit 201; hier geben wir eine Seite zurück
  @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);
  }

  // das Modell der View: die Listen, wobei jede Option je nach Eingabe als
  // checked / selected markiert wird
  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,
    };
  }
}

// ein fehlendes Feld (nicht angekreuzte Checkbox ...) wird gar nicht gesendet
function text(value: unknown): string {
  return typeof value === 'string' ? value : '';
}

// ein angekreuzter Wert: "sport"; zwei: ["sport", "music"]; keiner: undefined
function array(value: unknown): string[] {
  if (value === undefined) return [];
  return Array.isArray(value) ? value : [String(value)];
}

Kommentieren wir diesen Code:

  • Zeilen 5–15: Eingabe und Formatierung: Die Kontrollkästchen und die Dropdown-Liste sind Arrays;
  • Zeile 19: Der Listen-Service wird injiziert;
  • Zeilen 22–30: [GET /form] zeigt das Formular mit Anfangswerten an;
  • Zeile 34: [POST /form] gibt eine Seite zurück, keine erzeugte Ressource: Wir ersetzen den Code 201 durch 200;
  • Zeilen 37–47: Die empfangenen Felder werden neu formatiert. Zwei Fälle erfordern Aufmerksamkeit: ein fehlendes Feld (ein nicht angekreuztes Kontrollkästchen wird gar nicht gesendet, siehe Funktion [text], Zeilen 66–68) und ein Mehrfachwert-Feld, das als String ankommt, wenn es nur einen Wert hat (Funktion [array], Zeilen 71–74, siehe Beispiel 10);
  • Zeilen 53–62: das Modell der View. Für jede Liste berechnet die Action, welche Optionen angekreuzt oder ausgewählt sein sollen: Die View muss dann nur noch einen booleschen Wert auswerten. Das Feld [received] enthält zu Anzeigezwecken, was der Server empfangen hat.

Die Datei [views/form.hbs]:

<h1 class="h3">A complete form</h1>
<form method="post" action="/form" style="max-width: 40rem">
  {{!-- verstecktes Feld: wird mit dem Formular gesendet, ist aber unsichtbar --}}
  <input type="hidden" name="token" value="{{input.token}}">

  <div class="mb-2">
    <span class="form-label me-3">Title</span>
    {{#each titles}}
      {{!-- Radiobuttons: gleicher [name], es wird ein einziger Wert gesendet --}}
      <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>
      {{!-- ein Passwort wird NIEMALS in der Seite zurückgesendet --}}
      <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}}
      {{!-- Checkboxen: gleicher [name], mehrere Werte möglich --}}
      <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>
      {{!-- Mehrfachauswahlliste: mehrere Werte möglich --}}
      <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>
    {{!-- ein mehrzeiliges Textfeld: der Wert steht ZWISCHEN den 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}}

Kommentieren wir diesen Code:

  • Zeile 2: Das Formular wird per POST gesendet; seine Felder stehen im Rumpf der Anfrage;
  • Zeile 4: Ein verstecktes Feld wird mit dem Formular gesendet, aber nicht angezeigt. Es dient dazu, Informationen von einer Seite zur nächsten weiterzureichen (die Fallstudie verwendet es zum Beispiel, um die Version eines Datensatzes zu speichern). Achtung: Der Benutzer kann es ändern;
  • Zeilen 8–15: Optionsfelder teilen sich dasselbe Attribut [name]: Es kann nur eines ausgewählt werden, und nur ein Wert wird gesendet. Das Attribut [checked] wählt die Schaltfläche aus;
  • Zeile 26: Ein Passwort wird niemals in einer Seite zurückgeschickt: Das Feld hat kein Attribut [value];
  • Zeile 30: ein Datumsfeld. Der Browser zeigt das Datum im Format des Benutzers an, sendet aber immer [yyyy-mm-dd];
  • Zeilen 36–43: Kontrollkästchen mit demselben Attribut [name]: Jedes angekreuzte Kästchen sendet seinen Wert; der Parameter wird daher wiederholt;
  • Zeilen 49–53: eine Dropdown-Liste. Die ausgewählte Option hat das Attribut [selected];
  • Zeilen 58–62: Das Attribut [multiple] erlaubt die Auswahl mehrerer Optionen;
  • Zeile 69: Der Wert eines mehrzeiligen Textfelds steht zwischen seinen Tags, nicht in einem Attribut [value];
  • Zeilen 75–78: Was der Server empfangen hat, angezeigt in einem [<pre>]-Tag.

Das anfängliche Formular, dann nach dem Absenden:

Image

Image

Beachten Sie, dass das mehrzeilige Textfeld [Hello <b>everyone</b>] genau wie eingegeben erneut anzeigt: Dank der Maskierung durch [{{...}}] werden die eingegebenen Tags nicht interpretiert. Das Passwort wurde empfangen, wird aber nicht angezeigt. Mit [curl] sehen wir den Unterschied, wenn ein Kontrollkästchen angekreuzt ist:

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

und bei zwei angekreuzten Kästchen:

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

(nur der Abschnitt [What the server received] der Seite wird gezeigt)

4.7. Beispiel 19: Formularvalidierung

Ein ungültiges Formular muss erneut angezeigt werden, mit den eingegebenen Werten und unter jedem fehlerhaften Feld einer Meldung. Beispiel 19 wendet die Technik aus Beispiel 09 (Validierung durch die Action) auf ein Registrierungsformular an.

Die Datei [src/registration.dto.ts]:

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

// entfernt überflüssige Leerzeichen einer Eingabe VOR ihrer Validierung
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;

  // alles, was aus einem Formular kommt, ist ein 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" betrifft ZWEI Felder: das
  // prüft der Controller
  confirmation: string;
}
  • Zeile 5: Eine Bereinigungsfunktion, die von [@Transform] vor der Validierung angewendet wird: Ein aus Leerzeichen bestehender Name wird in einen leeren String umgewandelt, und [@IsNotEmpty] lehnt ihn ab;
  • Zeilen 18–22: Das Alter wird in eine Zahl umgewandelt und dann validiert;
  • Zeilen 27–29: Die Regel „Die Bestätigung stimmt mit dem Passwort überein“ betrifft zwei Felder: Die Dekoratoren sehen sie nicht, aber der Controller wird sie prüfen.

Die Datei [src/validation.ts]:

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

// Fehler pro Feld: { 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. empfangenes Objekt -> Instanz der Klasse (@Transform / @Type werden angewendet)
  const dto = plainToInstance(cls, body);
  // 2. Prüfung aller Constraints
  const violations = await validate(dto);
  // 3. wir behalten die erste Meldung jedes ungültigen Feldes
  const errors: Errors = {};
  for (const v of violations) {
    errors[v.property] = Object.values(v.constraints ?? {})[0];
  }
  return { dto, errors };
}
  • Zeile 5: Fehler sind nach Feldern organisiert: [{ name: 'The name is required.' }], wodurch jede Meldung unter dem zugehörigen Feld angezeigt werden kann;
  • Zeilen 7–10: Die Funktion ist generisch: Sie validiert jede beliebige Formularklasse. Sie gibt die umgewandelte Instanz ([dto]) und die Fehler zurück;
  • Zeilen 17–19: Ein Feld kann mehrere Einschränkungen verletzen; nur die erste Fehlermeldung wird beibehalten.

Die Fallstudie enthält dieselbe Funktion ([web/helpers/form.helper.ts]).

Die Datei [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: wir lassen den Browser das Formular vor dem Senden validieren
  @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);
    // eine Regel, die zwei Felder betrifft
    if (!errors.password && body.confirmation !== body.password) {
      errors.confirmation = 'The confirmation does not match the password.';
    }
    if (Object.keys(errors).length > 0) {
      // wir zeigen das Formular ERNEUT an: eingegebene Werte (außer den Passwörtern)
      // und unter jedem ungültigen Feld eine Meldung
      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 });
  }
}
  • Zeilen 9–13: das leere Formular. Der Parameter [html5] wird später erklärt;
  • Zeile 21: Validierung jedes Felds;
  • Zeilen 23–25: anschließend die Regel, die für zwei Felder gilt;
  • Zeilen 26–36: Gibt es Fehler, wird das Formular erneut angezeigt: die eingegebenen Werte (außer den Passwörtern), Fehler pro Feld und eine allgemeine Meldung;
  • Zeile 37: Andernfalls die Willkommensseite, mit den von [dto] umgewandelten Werten (das Alter ist eine Zahl, der Name wurde bereinigt).

Die Felder werden alle nach demselben Muster aufgebaut: Eine Partial-Datei übernimmt das.

Die Datei [views/partials/field.hbs]:

1
2
3
4
5
6
7
8
{{!-- ein Eingabefeld; Parameter: name, label, type, value, error und
      attributes = die HTML5-Validierungsattribute (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>
  • Zeile 5: Die [Bootstrap] [is-invalid] -Klasse hebt ein ungültiges Feld rot hervor;
  • Zeile 6: Die HTML5-Validierungsattribute werden als Parameter übergeben und ohne Maskierung eingefügt (dreifache geschweifte Klammern): Sie werden vom Entwickler geschrieben, nicht vom Benutzer eingegeben;
  • Zeile 7: die Fehlermeldung unter dem Feld (Klasse [invalid-feedback]).

Die Datei [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: der Browser ignoriert die Attribute required, min... und
      sendet das Formular unverändert; nur der Server validiert --}}
<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>
  • Zeile 9: Das Attribut [novalidate] ist vorhanden, wenn [html5] false ist;
  • Zeilen 10–19: Jedes Feld ist ein Aufruf des Partials mit benannten Parametern. Ein Parameter kann ein Wert aus dem Modell sein ([value=values.name]).

Die Datei [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}}}
    {{!-- die globale Fehlermeldung am Seitenende auf hellrosa Hintergrund --}}
    {{#if globalError}}
      <div class="error-area" role="alert">{{globalError}}</div>
    {{/if}}
  </div>
</body>
</html>

Zeilen 13–15: Die globale Meldung wird am Ende der Seite auf hellrosa Hintergrund angezeigt (Klasse [error-area] in [public/css/styles.css]), wie in der Fallstudie.

Senden wir das Formular mit mehreren Fehlern ab:

Image

dann korrekt ausgefüllt:

Image

4.7.1. Validierung durch den Browser

Die Attribute [required], [maxlength], [min], [max], [type="email"] ... weisen den Browser an, das Formular vor dem Absenden zu validieren: Der Benutzer wird sofort über einen Tooltip benachrichtigt, ohne jegliche Kommunikation mit dem Server. Dieses Verhalten wird durch den Link „aktivieren“ ([/register?html5=1]) ausgelöst, der das Attribut [novalidate] aus dem Formular entfernt.

Diese Validierung ist eine Komfortfunktion, keine Sicherheitsmaßnahme: Man kann sie umgehen, indem man einfach das Attribut [required] mit den Entwicklerwerkzeugen des Browsers entfernt oder die Anfrage mit [curl] sendet. Die serverseitige Validierung bleibt unverzichtbar. Deshalb deaktiviert das Beispiel die Browser-Validierung standardmäßig: um die Funktionsweise des Servers zu demonstrieren. Die Fallstudie behält jedoch beides bei: die HTML5-Attribute für den Komfort und die serverseitige Validierung für die Sicherheit.

4.8. Beispiel 20: Das Post/Redirect/Get-Muster

Wenn ein POST-Formular erfolgreich gesendet wurde, kann die Action direkt eine Seite anzeigen. Das Problem entsteht, wenn der Benutzer diese Seite anschließend aktualisiert (Taste F5): Der Browser sendet das Formular erneut, und die Operation wird ein zweites Mal ausgeführt (eine doppelt aufgegebene Bestellung, ein doppelt vereinbarter Termin ...). Das Muster Post / Redirect / Get (PRG) verhindert dieses Problem: Eine erfolgreiche POST-Action erzeugt keine Seite, sondern leitet auf eine GET-Seite weiter. Das Neuladen dieser Seite sendet nur die GET-Anfrage, die keine Auswirkung hat.

Ein Detail bleibt: Die GET-Seite muss eine Meldung anzeigen („Die Aufgabe wurde hinzugefügt“), obwohl diese Meldung von der POST-Action in einer anderen Anfrage erzeugt wurde. Sie wird in einem kurzlebigen Cookie übertragen, das von der nächsten Anfrage gelesen und gelöscht wird: Das ist eine Flash-Meldung.

Die Datei [src/flash.ts]:

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

const FLASH_COOKIE = 'flash';

// speichert eine Meldung, die von der NÄCHSTEN Seite angezeigt wird, und zwar nur einmal
export function flash(res: Response, message: string): void {
  res.cookie(FLASH_COOKIE, message, { httpOnly: true, sameSite: 'lax', maxAge: 60_000 });
}

// bei jeder Anfrage: die ausstehende Meldung wandert vom Cookie nach res.locals (also
// ins Modell der View), und das Cookie wird gelöscht
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();
}
  • Zeilen 6–8: [res.cookie(name, value, options)] setzt ein Cookie: Der Browser sendet es bei jeder folgenden Anfrage zurück. Optionen: [httpOnly] (das [JavaScript] der Seite kann es nicht lesen), [sameSite: 'lax'] (es wird bei POST-Anfragen von anderen Websites nicht gesendet), [maxAge] (Lebensdauer: eine Minute, mehr als genug, um die Weiterleitung nachzuverfolgen);
  • Zeilen 12–18: Middleware, die vor jeder Anfrage ausgeführt wird: Jede Meldung wird aus dem Cookie nach [res.locals] und damit in das Modell der View übernommen, und das Cookie wird gelöscht ([res.clearCookie]): Die Meldung wird nur einmal angezeigt.

Die Datei [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 füllt req.cookies mit den vom Browser gesendeten Cookies
  app.use(cookieParser());
  // dann liest (und löscht) unsere Middleware die ausstehende Flash-Meldung
  app.use(flashMiddleware);
  await app.listen(3000);
  console.log('Server started on http://localhost:3000');
}

bootstrap();
  • Zeile 17: Die Middleware [cookie-parser] dekodiert den Header [Cookie] der Anfrage und befüllt das Objekt [req.cookies];
  • Zeile 19: Unsere Middleware, die [req.cookies] benötigt, wird danach registriert: Middleware wird in der Reihenfolge ausgeführt, in der sie registriert wird.

Die Datei [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: die Liste und das Formular zum Hinzufügen
  @Get()
  display(@Res() res: Response): void {
    res.render('tasks', { tasks: this.tasks.list() });
  }

  // POST /tasks: das Muster Post / Redirect / Get
  @Post()
  add(@Body('label') label: string | undefined, @Res() res: Response): void {
    const text = (label ?? '').trim();
    if (text === '' || text.length > 40) {
      // ungültige Eingabe: wir zeigen die Seite erneut an, ohne Weiterleitung
      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.`);
    // keine Seite: eine Weiterleitung auf die GET-Seite
    res.redirect('/tasks');
  }

  // POST /tasks/without-prg: das Gegenbeispiel (eine Seite als Antwort auf den 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 });
  }
}
  • Zeilen 11–14: die Listenseite;
  • Zeilen 20–27: eine ungültige Eingabe: Die Seite wird erneut angezeigt (keine Weiterleitung: Die Eingabe und die Fehlermeldung müssen erhalten bleiben);
  • Zeilen 29–32: eine gültige Eingabe: die Operation, die Flash-Meldung, dann eine 302-Weiterleitung auf die GET-Seite;
  • Zeilen 36–40: das Gegenbeispiel zum Vergleich.

Die Datei [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: diese Schaltfläche sendet dasselbe Formular an eine andere Adresse --}}
  <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}}

Zeile 9: Das Attribut [formaction] einer Schaltfläche sendet das Formular an eine Adresse, die sich von der des Attributs [action] des Formulars unterscheidet. Das Formular hat somit zwei Schaltflächen, die zwei verschiedene Actions auslösen. Die Fallstudie verwendet diese Methode auf ihrer Anmeldeseite.

Die Datei [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">
    {{!-- die Flash-Meldung am Seitenanfang --}}
    {{#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>

Die Flash-Meldung wird am Seitenanfang angezeigt (Zeilen 12–14) und die Fehlermeldung am Seitenende (Zeilen 16–18).

Das sieht [curl], wenn das Formular erfolgreich gesendet wird. Die Option [-c file] speichert die empfangenen Cookies, während [-b file] sie zurücksendet:

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

Die Antwort ist eine Weiterleitung mit dem Cookie [flash] (sein Inhalt ist kodiert). Die folgende Anfrage sendet das Cookie; die Antwort löscht es (Ablaufdatum in der Vergangenheit):

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

Im Browser, nach dem Hinzufügen einer Aufgabe:

Image

Die Adressleiste zeigt [/tasks] an: Das ist die GET-Seite. Sie können sie bedenkenlos neu laden; die Meldung verschwindet. Eine leere Eingabe:

Image

Und das Gegenbeispiel:

Image

Hier löst das Neuladen der Seite eine Browserwarnung aus („Formularübermittlung bestätigen“) und fügt die Aufgabe dann ein zweites Mal hinzu. Alle POST-Formulare der Fallstudie folgen dem PRG-Muster.

Eine einfache Regel leitet die Wahl zwischen einem Link und einer Schaltfläche:

  • Ein Link ([<a href>]) erzeugt eine GET-Anfrage. Eine GET-Anfrage darf nichts verändern: Browser, Suchmaschinen und Antivirenprogramme können Links selbstständig aufrufen, um eine Seite vorzubereiten oder zu analysieren;
  • Eine Operation, die Daten verändert (hinzufügen, bearbeiten, löschen, abmelden), ist eine Schaltfläche in einem POST-Formular.

Beispiel 21 verwaltet eine Kontaktliste: Sie sehen einen Kontakt über einen Link an und löschen ihn über eine Schaltfläche, die ein Bestätigungsfenster öffnet.

Die Datei [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) {}

  // ein LINK (<a href>): eine GET-Anfrage, die nichts ändert
  @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) };
  }

  // ein BUTTON in einem POST-Formular: eine Anfrage, die Daten ändert
  @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');
  }

  // gleiches Formular, anderer Button (Attribut formaction): andere 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');
  }
}
  • Zeilen 11–15 und 17–21: die beiden Seiten – die Liste und die Detailseite des Kontakts. [ParseIntPipe] wandelt die ID um; ein nicht vorhandener Kontakt führt zu einem 404-Fehler (siehe den Service);
  • Zeilen 24–29: Speichern eines Datensatzes mit PRG;
  • Zeilen 36–41: Duplizieren, ausgelöst durch eine zweite Schaltfläche im selben Formular (Attribut [formaction]);
  • Zeilen 47–52: Löschen per POST.

Die Datei [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: ein einfacher Link --}}
          <a class="btn btn-sm btn-outline-primary" href="/contacts/{{id}}">View</a>
          {{!-- delete: ein POST-Formular, dessen Absenden bestätigt werden muss --}}
          <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>
  • Zeile 10: ansehen: ein Link, der von [Bootstrap] als Schaltfläche dargestellt wird;
  • Zeilen 12–15: löschen: ein kleines Formular (POST), das auf seine Schaltfläche reduziert ist. Das Attribut [data-confirmation] enthält die Frage, die vor dem Absenden gestellt werden soll. Die Attribute [data-*] sind optional: HTML ignoriert sie, während [JavaScript] auf der Seite sie lesen kann.

Die Datei [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>
  {{!-- zwei Submit-Schaltflächen für dasselbe Formular --}}
  <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>

Zeile 13: zwei Absende-Schaltflächen für dasselbe Formular.

4.9.1. Das Bestätigungsfenster

Das Dialogfeld des Browsers ([window.confirm]) lässt sich weder formatieren noch übersetzen: Seine Schaltflächen bleiben in der Sprache des Browsers. Es wird durch ein [Bootstrap]-Fenster ersetzt, das in die Seite geschrieben und bis zum Bedarf ausgeblendet wird:

Die Datei [views/partials/confirmation.hbs]:

{{!-- ein einziges Fenster für die gesamte Seite, zunächst ausgeblendet (d-none) --}}
<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>
  • Zeile 2: Die Klasse [d-none] blendet das Fenster aus;
  • Zeile 3: der graue Hintergrund;
  • Zeile 11: die Position der Frage;
  • Zeilen 14–15: die beiden Schaltflächen, identifiziert über das Attribut [data-action].

Ein wenig [JavaScript] verbindet die Formulare mit dem Fenster:

Die Datei [public/js/app.js]:

// Bestätigung der Formulare mit dem Attribut data-confirmation="..."
// Ohne JavaScript werden diese Formulare einfach ohne Bestätigung gesendet.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // das Formular, das gesendet wird, wenn der Benutzer bestätigt

  // 1. wir fangen das Absenden der zu bestätigenden Formulare ab
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // das Absenden wird angehalten
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // das Fenster erscheint
    });
  });

  // 2. die beiden Buttons des Fensters
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // Absenden, OHNE das Ereignis 'submit' erneut auszulösen
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • Zeile 3: Der Code ist in eine Funktion eingebettet, die sofort ausgeführt wird, um keine globalen Variablen anzulegen;
  • Zeilen 9–16: Das Absenden jedes Formulars mit dem Attribut [data-confirmation] wird abgefangen. [preventDefault()] setzt das Absenden aus; das Formular wird gespeichert, die Frage wird im Fenster platziert ([textContent], nicht [innerHTML]: Die Frage wird als Text angezeigt und niemals als HTML interpretiert), und das Fenster wird angezeigt;
  • Zeilen 19–27: „Ja“ sendet das zwischengespeicherte Formular ab. Die Methode [submit()] eines Formulars sendet es ab, ohne das Ereignis [submit] auszulösen: Es erscheint also keine erneute Bestätigungsabfrage. „Nein“ blendet das Fenster aus.

Ist [JavaScript] deaktiviert, werden die Formulare einfach ohne Bestätigung abgesendet: Die Anwendung funktioniert weiterhin. Das ist das Prinzip der schrittweisen Verbesserung: [JavaScript] bietet zusätzlichen Komfort, ist aber nicht unverzichtbar. Die Fallstudie folgt diesem Prinzip (ihr Skript [public/js/app.js] ergänzt eine Tastatursteuerung: Esc-Taste, Fokus). Die resultierenden Seiten:

Image

Image

Image

Image

Schließlich prüfen wir, dass sich ein Löschvorgang nicht durch eine GET-Anfrage auslösen lässt:

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