Docs

TEMPLATING

Documentation

TEMPLATING

With TEMPLATING you manage templates (e.g., for contract PDFs).

A template defines:

  • Which text appears where (salutation, clauses, terms and conditions)
  • Which data fields are inserted (tenant name, contract number, inventory list, etc.)
  • Optionally: special inventory rows / layout building blocks

TEMPLATING supports the system document types VERTRAG (seed V34) and RECHNUNG (seed V62), the plugin-registered types KASSENZETTEL (seed V66, derived from CAFE orders) and ANGEBOT (seed V67, creatable via the "New" wizard) as well as tenant-specific custom document types (since M27-06, V63). One default template is maintained per type.


Since M35-02, template administration and the rendering engine are part of
the DOKUMENTE plugin. The admin UI now lives under
Admin → Documents → Document Templates
(/settings/admin/dokumente/templates) and is gated by the DOKUMENTE key.

Redirect of the old URLs (HTTP 307, Temporary Redirect):
All former paths /settings/admin/templating/** (GET and POST, including
sub-paths and the query string) automatically redirect to the corresponding
new path — method and form body are preserved:

old (legacy) new (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 strategy (existing tenants without re-activation):
The plugin key TEMPLATING remains registered as a ghost plugin (no
navigation contribution, keeping the known templating.template.*
permissions). Tenant resolution extends the key set: TEMPLATING →
DOKUMENTE. Tenants that have (only) TEMPLATING enabled therefore reach
the new DOKUMENTE endpoints without re-activation. All new feature gating
runs exclusively through DOKUMENTE.


  • Create a template (type VERTRAG, RECHNUNG, KASSENZETTEL, ANGEBOT or a registered custom document type)
  • Create, rename or delete custom document types (M27-06)
  • Mark a template as default per document type
  • Filter the template list by type
  • Preview a template (per type)
  • Manage multiple variants (e.g., "Contract German" vs. "Contract English", invoice templates)

1) Open the template list

  • Admin → Documents → Document Templates (/settings/admin/dokumente/templates).
  • Optionally filter by type via query parameter: ?type=VERTRAG or ?type=RECHNUNG (no parameter: all types).

2) Create a new template

  1. "New" (/settings/admin/dokumente/templates/new) — preferably from the list filtered by the desired type: the type is taken from the active type filter when creating (default VERTRAG) and is visible and changeable as a select in the form.
  2. Fill in the fields:
    • Name
    • Type (system type VERTRAG/RECHNUNG or a registered custom type; default when creating: VERTRAG)
    • Body / HTML with placeholders
  3. Save (POST /settings/admin/dokumente/templates).

> Available placeholders depend on the type. Example for contract: {{vertrag.id}}, {{mieter.name}}, {{inventar}}. If you are unsure, use the preview.
> Custom document types use the generic variable model (union of VERTRAG and RECHNUNG).

3) Edit a template

  • Open the entry (/settings/admin/dokumente/templates/{id}/edit) → save (POST /settings/admin/dokumente/templates/{id}).

4) Mark a template as default

  • For each type, exactly one template can be marked as default.
  • POST /settings/admin/dokumente/templates/{id}/default.
  • This template is used when generating a PDF if no other one is selected.

5) Delete a template

  • POST /settings/admin/dokumente/templates/{id}/delete.
  • Default templates cannot be deleted without first choosing a different one as default.

6) Preview

  • POST /settings/admin/dokumente/templates/preview (M27-08: parameter dataSource = sample-vertrag / sample-rechnung / UUID of an existing contract, content, optional type = registered document type and lang = de/en) — shows how the finished document would look with the template, without producing an actual PDF. The sample data (sample-vertrag/sample-rechnung) uses fixed sample data without tenant data; with a contract UUID the live contract is rendered. The type parameter only applies in the UUID case; for sample data it is fixed by the source.

7) Manage custom document types (M27-06)

  • The template list contains a separate "Document Types" block (/settings/admin/dokumente/templates).
  • Create type: key (uppercase letters, digits, _, max. 32 characters, e.g. GUTSCHEIN) + display label → POST /settings/admin/dokumente/templates/document-types.
  • Rename type: "Bearbeiten" button in the type table (left of "Löschen"); opens the inline form (Speichern/Abbrechen). Only the display label changes, the key stays stable → POST /settings/admin/dokumente/templates/document-types/{id}.
  • Delete type: only possible while no templates of that type exist → POST /settings/admin/dokumente/templates/document-types/{id}/delete.
  • The system types VERTRAG and RECHNUNG are locked (no renaming or deletion).
  • Templates may only reference types that exist in the registry; custom types use the generic variable model (union of VERTRAG and RECHNUNG).
  • Sample templates for custom types (copy & paste): How-To/Templates/ at the repository root — 17 ready-to-copy templates (e.g. voucher, quote, termination, return/pickup confirmation, deposit receipt, damage report, extension, payment reminder, dunning, credit note, cancellation, payment confirmation, inquiry/booking confirmation, delivery note, item list), with a README step-by-step guide.

"My placeholder is not replaced"

  • Check the spelling (brackets, dots, casing).
  • The value may be empty (e.g., a tenant without a phone number).

"The PDF looks broken"

  • HTML/CSS errors in the template. Use the preview.
  • Images: must be reachable URLs / embedded data.

"Which template is used in the contract?"

  • Since M27-07, the document type stored on the contract (field "Document
    type" in the contract form, default VERTRAG, V64) determines the template:
    "Generate PDF" renders the default template of that type. For VERTRAG the
    legacy flow (stored protected PDF) additionally applies.
  • The per-contract template selection was removed; ad-hoc rendering is still
    possible via the type/template query parameters of /pdf and /generate.

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

  • GET /settings/admin/dokumente/templates — list (optional: ?type=<document type>)
  • GET /settings/admin/dokumente/templates/new — new
  • POST /settings/admin/dokumente/templates — create
  • GET /settings/admin/dokumente/templates/{id}/edit — edit
  • POST /settings/admin/dokumente/templates/{id} — save
  • POST /settings/admin/dokumente/templates/{id}/delete — delete
  • POST /settings/admin/dokumente/templates/{id}/default — mark as default per type
  • POST /settings/admin/dokumente/templates/preview — preview (M27-08: dataSource = sample-vertrag/sample-rechnung/contract-UUID, content, optional type=<document type>, lang=de|en)
  • POST /settings/admin/dokumente/templates/document-types — create document type (typeKey, label)
  • POST /settings/admin/dokumente/templates/document-types/{id} — rename document type (label)
  • POST /settings/admin/dokumente/templates/document-types/{id}/delete — delete document type

Legacy (/settings/admin/templating/**): since M35-02 all of these redirect
per 307 to the corresponding new paths (mapping table above).

  • TEMPLATING is closely tied to VERTRAG (document generation: contract & invoice).
  • Available document types: system types VERTRAG and RECHNUNG (default templates via Flyway: V34 / V62), plugin-registered types via the DokumentRegistry (M35-01/02) - currently KASSENZETTEL (seed V66, CAFE) and ANGEBOT (seed V67, DOKUMENTE) - plus tenant-specific registered custom types (M27-06, table templating_document_type, V63).
  • Templates may only reference registered types; custom types get the generic variable model (union of VERTRAG and RECHNUNG).
  • Since M27-07 (V64), each contract carries a document type (vertrag.document_type); "Generate PDF" on the contract renders the default template of that type (only VERTRAG uses the legacy path with the stored PDF).
  • Keep templates clean and tidy — "one default template per type plus a few variants" is usually better than ten almost-identical files.