Docs

TEMPLATING

Dokumentation

TEMPLATING

Mit TEMPLATING verwalten Sie Vorlagen (z.B. für Vertrags-PDFs).

Eine Vorlage legt fest:

  • Welcher Text wo steht (Anrede, Klauseln, AGB)
  • Welche Datenfelder eingesetzt werden (Mieter-Name, Vertrags-Nummer, Inventarliste …)
  • Optional: spezielle Inventar-Zeilen / Layout-Bausteine

TEMPLATING unterstützt die System-Dokument-Typen VERTRAG (Seed V34) und RECHNUNG (Seed V62), die plugin-registrierten Typen KASSENZETTEL (Seed V66, aus CAFE-Bestellungen abgeleitet) und ANGEBOT (Seed V67, im Neu-Wizard erstellbar) sowie mandantenindividuelle eigene Dokument-Typen (seit M27-06, V63). Pro Typ wird genau ein Standard-Template gepflegt.


Seit M35-02 sind die Template-Verwaltung und die Rendering-Engine Teil des
DOKUMENTE-Plugins. Die Admin-UI liegt jetzt unter
Admin → Dokumente → Dokument-Templates
(/settings/admin/dokumente/templates) und wird über den DOKUMENTE-Key
geschaltet.

Weiterleitung der alten URLs (HTTP 307, Temporary Redirect):
Alle alten Pfade /settings/admin/templating/** (GET und POST, inkl.
Sub-Pfade und Query-String) leiten automatisch auf den zugehörigen neuen Pfad
weiter – Methode und Formular-Body bleiben erhalten:

alt (Legacy) neu (M35-02)
GET /settings/admin/templating GET /settings/admin/dokumente/templates
GET /settings/admin/templating/new GET /settings/admin/dokumente/templates/new
GET /settings/admin/templating/{id}/edit GET /settings/admin/dokumente/templates/{id}/edit
POST /settings/admin/templating POST /settings/admin/dokumente/templates
POST /settings/admin/templating/{id} POST /settings/admin/dokumente/templates/{id}
POST /settings/admin/templating/{id}/delete POST /settings/admin/dokumente/templates/{id}/delete
POST /settings/admin/templating/{id}/default POST /settings/admin/dokumente/templates/{id}/default
POST /settings/admin/templating/preview POST /settings/admin/dokumente/templates/preview
POST /settings/admin/templating/document-types POST /settings/admin/dokumente/templates/document-types
POST /settings/admin/templating/document-types/{id} POST /settings/admin/dokumente/templates/document-types/{id}
POST /settings/admin/templating/document-types/{id}/delete POST /settings/admin/dokumente/templates/document-types/{id}/delete

Alias-Strategie (bestehende Mandanten ohne Reaktivierung):
Der Plugin-Key TEMPLATING lebt weiter als „Ghost“-Plugin (ohne
Navigations-Beitrag, mit den bekannten templating.template.*-Rechten).
Die Tenant-Resolution erweitert die Key-Menge: TEMPLATING → DOKUMENTE.
Mandanten, die (nur) TEMPLATING aktiviert haben, erreichen damit die neuen
DOKUMENTE-Endpunkte ohne Reaktivierung. Neues Feature-Gating läuft exklusiv
über DOKUMENTE.


  • Eine Vorlage anlegen (Typ VERTRAG, RECHNUNG, KASSENZETTEL, ANGEBOT oder eigener registrierter Dokument-Typ)
  • Eigene Dokument-Typen anlegen, umbenennen oder löschen (M27-06)
  • Vorlage als Standard pro Dokument-Typ markieren
  • Template-Liste nach Typ filtern
  • Vorlage in der Vorschau (pro Typ) ansehen
  • Mehrere Varianten verwalten (z.B. „Vertrag deutsch“ vs. „Vertrag englisch“, Rechnungsvorlagen)

1) Vorlagen-Liste öffnen

  • Admin → Dokumente → Dokument-Templates (/settings/admin/dokumente/templates).
  • Optional per Query-Parameter nach Typ filtern: ?type=VERTRAG bzw. ?type=RECHNUNG (ohne Parameter: alle Typen).

2) Neue Vorlage anlegen

  1. „Neu" (/settings/admin/dokumente/templates/new) — am besten aus der nach dem gewünschten Typ gefilterten Liste heraus: Der Typ wird beim Anlegen aus dem aktiven Typ-Filter übernommen (Default VERTRAG) und ist im Formular als Select sichtbar und änderbar.
  2. Felder ausfüllen:
    • Name
    • Body / HTML mit Platzhaltern
  3. Speichern (POST /settings/admin/dokumente/templates).

> Verfügbare Platzhalter hängen vom Typ ab. Beispiel für Vertrag: {{vertrag.id}}, {{mieter.name}}, {{inventar}}. Wenn Sie unsicher sind: Vorschau benutzen.
> Eigene Dokument-Typen nutzen das generische Variablenmodell (Union aus VERTRAG und RECHNUNG).

3) Vorlage bearbeiten

  • Eintrag öffnen (/settings/admin/dokumente/templates/{id}/edit) → Speichern (POST /settings/admin/dokumente/templates/{id}).

4) Vorlage als Standard markieren

  • Pro Typ kann genau eine Vorlage als Standard markiert werden.
  • POST /settings/admin/dokumente/templates/{id}/default.
  • Diese wird beim PDF-Generieren benutzt, wenn keine andere ausgewählt ist.

5) Vorlage löschen

  • POST /settings/admin/dokumente/templates/{id}/delete.
  • Standard-Vorlagen können nicht gelöscht werden, ohne vorher eine andere als Standard zu wählen.

6) Vorschau

  • POST /settings/admin/dokumente/templates/preview (M27-08: Parameter dataSource = sample-vertrag / sample-rechnung / UUID eines existierenden Vertrags, content, optional type = registrierter Dokument-Typ und lang = de/en) – zeigt, wie das fertige Dokument mit der Vorlage aussehen würde, ohne ein echtes PDF zu erzeugen. Beispieldaten (sample-vertrag/sample-rechnung) nutzen feste Musterdaten ohne Mandanten-Daten; bei einer Vertrag-UUID wird der live Vertrag gerendert. Der Typ-Parameter wirkt nur im UUID-Fall; bei Beispieldaten ist er durch die Quelle fixiert.

7) Eigene Dokument-Typen verwalten (M27-06)

  • Die Template-Liste enthält einen eigenen Block „Dokument-Typen“ (/settings/admin/dokumente/templates).
  • Typ anlegen: Schlüssel (nur Großbuchstaben, Ziffern, _, max. 32 Zeichen, z. B. GUTSCHEIN) + Anzeigename → POST /settings/admin/dokumente/templates/document-types.
  • Typ umbenennen: „Bearbeiten"-Button in der Typ-Tabelle (links neben „Löschen"); öffnet das Inline-Formular (Speichern/Abbrechen). Nur die Anzeigebeschriftung ändert sich, der Schlüssel bleibt stabil → POST /settings/admin/dokumente/templates/document-types/{id}.
  • Typ löschen: nur möglich, solange keine Vorlagen dieses Typs existieren → POST /settings/admin/dokumente/templates/document-types/{id}/delete.
  • Die System-Typen VERTRAG und RECHNUNG sind gesperrt (kein Umbenennen/Löschen).
  • Vorlagen dürfen nur Typen zuweisen, die in der Registry existieren; eigene Typen nutzen das generische Variablenmodell (Union aus VERTRAG und RECHNUNG).
  • Beispielvorlagen für eigene Typen (Copy & Paste): How-To/Templates/ im Repository-Root — 17 kopierfertige Templates (u. a. Gutschein, Angebot, Kündigung, Rückgabe, Abholung, Kaution, Mängelprotokoll, Verlängerung, Zahlungserinnerung, Mahnung, Gutschrift, Storno, Zahlungseingang, Anfrage-/Buchungsbestätigung, Lieferschein, Inventarliste), inkl. README mit Schritt-für-Schritt-Anleitung.

„Mein Platzhalter wird nicht ersetzt“

  • Schreibweise prüfen (Klammern, Punkte, Klein-/Großschreibung).
  • Wert ist evtl. leer (z.B. Mieter ohne Telefon).

„PDF sieht zerschossen aus“

  • HTML-/CSS-Fehler in der Vorlage. Vorschau benutzen.
  • Bilder: müssen zugängliche URLs / eingebettete Daten sein.

„Welche Vorlage wird im Vertrag verwendet?“

  • Seit M27-07 bestimmt der im Vertrag gespeicherte Dokument-Typ (Feld
    „Dokument-Typ" im Vertrag-Formular, Default VERTRAG, V64): „PDF
    generieren" rendert die Standard-Vorlage dieses Typs. Bei VERTRAG gilt
    zusätzlich der Legacy-Flow (gespeichertes geschütztes PDF).
  • Eine explizite Template-Auswahl pro Vertrag wurde entfernt; ad hoc geht es
    über die Query-Parameter type/template von /pdf und /generate.

Admin (/settings/admin/dokumente/templates, M35-02):

  • GET /settings/admin/dokumente/templates – Liste (optional: ?type=<Dokument-Typ>)
  • GET /settings/admin/dokumente/templates/new – Neu
  • POST /settings/admin/dokumente/templates – Anlegen
  • GET /settings/admin/dokumente/templates/{id}/edit – Bearbeiten
  • POST /settings/admin/dokumente/templates/{id} – Speichern
  • POST /settings/admin/dokumente/templates/{id}/delete – Löschen
  • POST /settings/admin/dokumente/templates/{id}/default – als Standard pro Typ markieren
  • POST /settings/admin/dokumente/templates/preview – Vorschau (M27-08: dataSource = sample-vertrag/sample-rechnung/Vertrags-UUID, content, optional type=<Dokument-Typ>, lang=de|en)
  • POST /settings/admin/dokumente/templates/document-types – Dokument-Typ anlegen (typeKey, label)
  • POST /settings/admin/dokumente/templates/document-types/{id} – Dokument-Typ umbenennen (label)
  • POST /settings/admin/dokumente/templates/document-types/{id}/delete – Dokument-Typ löschen

Legacy (/settings/admin/templating/**): leitet seit M35-02 per 307 auf die
zugehörigen neuen Pfade weiter (Mapping-Tabelle oben).

  • TEMPLATING ist eng mit VERTRAG (Dokument-Generierung: Vertrag & Rechnung) verbunden.
  • Verfügbare Dokument-Typen: System-Typen VERTRAG und RECHNUNG (Standard-Templates via Flyway: V34 / V62), plugin-registrierte Typen über die DokumentRegistry (M35-01/02) - derzeit KASSENZETTEL (Seed V66, CAFE) und ANGEBOT (Seed V67, DOKUMENTE) - sowie mandantenindividuell registrierte eigene Typen (M27-06, Tabelle templating_document_type, V63).
  • Vorlagen dürfen nur registrierte Typen verwenden; eigene Typen erhalten das generische Variablenmodell (Union aus VERTRAG und RECHNUNG).
  • Seit M27-07 (V64) trägt jeder Vertrag einen Dokument-Typ (vertrag.document_type); „PDF generieren" im Vertrag rendert den Default-Template dieses Typs (nur VERTRAG nutzt den Legacy-Pfad mit gespeichertem PDF).
  • Halten Sie Vorlagen sauber und übersichtlich – „eine Standardvorlage pro Typ + ein paar Varianten" ist meist besser als zehn fast identische Dateien.