PDF-Vorlagen gehören ins Repository

Eine Vorlage, die Rechnungen rendert, ist Code. Sie hat Verzweigungen, sie hat Randfälle, und wenn sie kaputtgeht, bekommt ein Kunde etwas Falsches auf Papier. Trotzdem stehen Vorlageneditoren meist außerhalb aller Praktiken, die wir auf den restlichen Code anwenden: kein Review, keine Tests, keine Historie, die man bisecten kann.

Formfeed behält den Browser-Editor, denn wer den Text schreibt, sollte keinen Checkout brauchen. Und dieselbe Vorlage darf ein Ordner voller Dateien sein.

Der Ordner

templates/invoice-de/
  template.json     Name, Art, Engine
  template.html     der Body
  style.css
  header.html, footer.html
  settings.json     Papier, Ränder, Sprache, Währung
  schema.json       was die Daten enthalten müssen
  data/
    default.json    Beispieldatensätze
    many-lines.json

formfeed templates pull schreibt ihn, push schickt ihn zurück. Die Dateien entsprechen eins zu eins den Tabs im Web-Editor: Eine Gestalterin kann im Browser arbeiten, während ein Entwickler im Repository arbeitet, und niemand gewinnt aus Versehen. push schickt die Prüfsumme mit, von der es ausging, und die API antwortet mit einem Konflikt, wenn zwischenzeitlich jemand eine neuere Version gespeichert hat, im Editor oder mit einem anderen Push.

Die Schleife

formfeed dev invoice-de     # Hot-Reload-Vorschau lokal, ohne Konto
formfeed validate           # Diagnosen, Exit-Code 1 bei Fehlern
formfeed render invoice-de --data data/many-lines.json --out out.pdf

Die Vorschau nutzt dieselbe Engine wie die Render-Server: Was lokal paginiert, paginiert in der Produktion. Nur das finale Chromium-Rendering passiert in der Cloud, und mit einem Test-Schlüssel ist es kostenlos.

Die Tests

import { loadTemplate } from '@formfeed/testing';

const tpl = await loadTemplate('templates/invoice-de');

test('rendert jeden Datensatz ohne Fehler', async () => {
  await expect(tpl).toRenderWithoutErrors(await tpl.data('many-lines'));
  await expect(tpl).toUseOnlyKnownVariables(await tpl.data('many-lines'));
});

toUseOnlyKnownVariables ist der Matcher, der sich bezahlt macht. Ein umbenanntes Feld in einem Vorsystem wirft keinen Fehler, es rendert eine Lücke dort, wo die Kundennummer stand, und niemand merkt es, bis ein Kunde anruft. Der Matcher lässt stattdessen den Build fehlschlagen.

In der CI

Validierung und Tests laufen offline, Vorschauen mit einem Test-Schlüssel, ein Pull Request kostet also nichts. Die CI-Anleitung zeigt den Workflow, mit oder ohne unsere GitHub Action. Der Veröffentlichungsschritt läuft auf dem Standard-Branch mit einem Live-Schlüssel und einer Notiz, die den Commit trägt. Das Ergebnis ist eine Vorlagenhistorie, in der jede veröffentlichte Version Autor, Diff und Grund hat.

Nichts davon ist Pflicht. Viele Teams werden nur den Editor nutzen, und das ist ein vollständiges Produkt. Aber wenn ein Dokument in einer Prüfung landet, ist es den Ordner wert, zeigen zu können, welche Version es erzeugt hat, wer sie freigegeben hat und was sich geändert hatte.