Präsentations-Elemente¶

Neben den Eingabefeldern gibt es im Schema eine zweite Sorte Einträge: Präsentations-Elemente. Sie speichern keinen Wert, sondern gliedern, erklären oder lösen Aktionen aus.

Zusammenklicken reicht — das JSON ist zum Nachschauen da

Überschriften, Leittexte, Leerzellen und Schaltflächen liegen fertig im Baukasten: aufziehen, ablegen, Text anpassen — mehr ist nicht nötig. Bilder, Grafiken und Links legst du über + Neu an (Feldart Bild, SVG oder Link) und stellst sie im Eigenschaften-Panel ein. Die eingeklappten Kästen „Hinter den Kulissen" auf dieser Seite zeigen, was dabei in das Formular geschrieben wird. Aufklappen lohnt sich, wenn du verstehen willst, warum etwas so funktioniert — zum Arbeiten brauchst du es nicht.

Was sie gemeinsam haben¶

Sie stehen wie Felder im properties-Block.
Ein eigener kc:*-Schlüssel kennzeichnet die Art.
Sie erzeugen keine Datenbank-Spalte.
Die Prüfung beim Speichern ignoriert sie.
In der Trefferliste erscheinen sie nicht.

Konvention: Namen von Präsentations-Elementen beginnen mit einem Unterstrich (_hinweis, _btnDrucken) — so ist sofort klar, dass kein Datenwert dahintersteht.

Schlüssel	Element
`kc:text`	Leittext: Überschrift, Absatz, Hinweis — auch mit Symbol, aufklappbar oder als HTML
`kc:link`	Link
`kc:image`	Bild (PNG/JPEG)
`kc:svg`	Vektorgrafik
`kc:button`	Schaltfläche
`kc:section`	Abschnittsüberschrift
`kc:spacer`	leere Rasterzelle

Im Absolut- und Hybrid-Layout kommen kc:line und kc:box dazu — siehe Absolute Druckpositionen.

`kc:text` — Leittext¶

Ein Leittext ist erklärender Text mitten im Formular — ein Hinweis, eine Zwischenüberschrift, ein Absatz. Du ziehst ihn aus dem Baukasten-Ordner Leittext ins Formular und schreibst deinen Text hinein.

Hinter den Kulissen: Ein Hinweistext als Absatz

"_hinweis": {
  "type": "string",
  "kc:text": {
    "content": "Bitte alle Felder ausfüllen. Pflichtfelder sind mit * markiert.",
    "level": "p"
  }
}

type: "string" steht nur da, weil jeder Eintrag im properties-Block einen Typ braucht — gespeichert wird nichts. Die eigentliche Aussage steckt in kc:text.

Über die Attribute des Leittexts steuerst du Inhalt und Aussehen:

Attribut	Bedeutung
`content`	der Text; mehrzeilig erlaubt, Makros wie `${user:firstName}` werden aufgelöst
`level`	`h1`, `h2`, `h3` oder `p` (Standard)
`icon`	Symbol davor, z. B. `info`
`iconPlacement`	`inline` (Standard) oder `right`
`style`	`error` stellt den Text als Fehler-Hinweis dar
`collapsible`	`true`: der Text wird zur aufklappbaren Zeile; der Detailtext steht in der `description` des Eintrags
`html`	`true`: `content` darf einfaches HTML enthalten (fett, Links, Farben)

HTML-Leittexte

Im HTML-Modus entfernt KCForms alles Gefährliche (Skripte, Ereignis-Attribute) — erlaubt sind Formatierung, Links und einfache Stile. Beispiel: "content": "<b>Wichtig:</b> Bitte die <a href=\"https://intranet/anleitung\" target=\"_blank\">Anleitung</a> lesen."

Im Baukasten gibt es im Ordner Leittext fertige Varianten für alle Fälle. Im PDF erscheinen Leittexte als Absatz im Stil ihres Levels.

`kc:link` — Link¶

Ein Link führt aus dem Formular heraus, etwa zu einer Datenschutzerklärung oder einer Anleitung im Intranet. Du legst ihn über + Neu als Feldart Link an und trägst Adresse und Linktext in den Eigenschaften ein.

Hinter den Kulissen: Ein Link auf die Datenschutzerklärung

"_datenschutz": {
  "type": "string",
  "kc:link": {
    "url": "https://www.kehrmann-consulting.com/datenschutz",
    "text": "Datenschutzerklärung",
    "newTab": true
  }
}

Zeigt ein Link ins Leere, steht in url die Adresse, die geprüft werden muss — unabhängig davon, was als Text angezeigt wird.

Attribut	Bedeutung
`url`	Ziel
`text`	Linktext (Standard: die Adresse)
`newTab`	`true` (Standard): in neuem Tab öffnen

Links erscheinen nicht im PDF. Soll eine Adresse im Ausdruck stehen, nimm einen HTML-Leittext.

`kc:image` und `kc:svg` — Bilder und Grafiken¶

Beide beziehen ihre Datei aus dem Asset-Ordner des Servers (assets/img/ bzw. assets/svg/). Im Eigenschaften-Panel wählst du die Datei aus einer Liste der vorhandenen Assets aus und gibst die Größe an — typisch ein Logo im Briefkopf oder ein Statussymbol, das nur unter einer Bedingung erscheint.

Hinter den Kulissen: Ein Logo und ein bedingt sichtbares Symbol

"_logo": {
  "type": "string",
  "kc:image": { "src": "kehrmann-logo.png", "alt": "Kehrmann Consulting", "width": 240, "height": 60 }
},
"_okIcon": {
  "type": "string",
  "kc:svg": { "src": "check-circle.svg", "width": 32, "height": 32 },
  "kc:visibleIf": "betrag > 0"
}

Am Symbol hängt zusätzlich eine Bedingung (kc:visibleIf) — Anzeige-Elemente dürfen dieselben Regeln nutzen wie Eingabefelder.

Attribut	Bedeutung
`src`	Dateiname in `assets/img/` bzw. `assets/svg/`
`alt`	Alternativtext — wichtig für Screenreader
`width`, `height`	Größe in Pixeln (Web und PDF)

Im PDF bettet KCForms Bilder direkt ein; SVGs werden in ein hoch aufgelöstes Bild umgerechnet. Fehlt die Datei oder ist das SVG fehlerhaft, erscheint ein dezenter Platzhalter statt eines Abbruchs. kc:align (left/center/right) und kc:visibleIf wirken wie bei Feldern.

`kc:button` — Schaltfläche¶

Eine Schaltfläche löst beim Klick etwas aus: ein Skript des Formulars oder eine der Standard-Aktionen wie Speichern oder Drucken. Fertige Knöpfe liegen im Baukasten in den Ordnern Schaltflächen und Standardaktionen; Beschriftung, Aktion und Farbe stellst du danach in den Eigenschaften ein.

Hinter den Kulissen: Eine Schaltfläche, die ein eigenes Skript startet

"_btnDrucken": {
  "type": "string",
  "kc:button": { "label": "Beleg erzeugen", "scriptHook": "beleg", "variant": "primary" }
}

scriptHook ist der Name des Skripts, das beim Klick läuft. Tut ein Knopf nichts, steht hier entweder nichts — oder ein Name, den es im Reiter Skripte nicht (mehr) gibt.

Attribut	Bedeutung
`label`	Beschriftung, auch mit Makros
`scriptHook`	Name eines Skripts des Formulars — oder eine Standard-Aktion (siehe unten)
`clientScript`	JavaScript, das im Browser läuft statt eines Server-Skripts; bekommt `form` (Werte) und `field` (Name)
`variant`	`primary` (Standard), `secondary` oder `danger`

Ein Tooltip kommt über kc:tooltip, Sichtbarkeit über kc:visibleIf.

Standard-Aktionen — diese Namen in scriptHook lösen dieselbe Aktion aus wie die Werkzeugleiste, ganz ohne Skript:

`scriptHook`	Aktion
`saveForm`	Speichern
`printForm`	Drucken / PDF
`validateForm`	Validieren
`closeForm`	Formular schließen
`newRecord`	neuer, leerer Datensatz
`prevPage`, `nextPage`	vorige / nächste Formularseite

Ein eigenes Skript (im Reiter Skripte) bekommt beim Klick denselben ctx und dieselben Host-Objekte wie onSubmit — typisch pdf.render(), mail.send(...) oder eine Rückmeldung über view:

// Skript „berechne"
ctx.form.summe = kc.num(ctx.form.wert1) + kc.num(ctx.form.wert2);
view.add(new view.Message('Neue Summe: ' + ctx.form.summe.toFixed(2), 'Berechnet'));

Der Baukasten bietet im Ordner Schaltflächen und Standardaktionen fertige Knöpfe.

`kc:section` — Abschnittsüberschrift¶

Ein Abschnitt gliedert das Formular: eine Überschrift, wahlweise mit Trennlinie, ab der die folgenden Felder zusammengehören. Der Baukasten hält dafür die Ordner mit den Überschriften in drei Größen bereit — jeweils auch in der Variante mit Sprungmarke.

Hinter den Kulissen: Eine Zwischenüberschrift mit Trennlinie

"_personalDaten": {
  "type": "string",
  "title": "Personaldaten",
  "kc:section": true,
  "kc:sectionStyle": "line",
  "kc:sectionLevel": 2
}

Anders als bei Leittext oder Link steht der sichtbare Text hier im gewohnten title — kc:section schaltet den Eintrag lediglich von „Eingabefeld" auf „Überschrift" um.

Attribut	Bedeutung
`kc:section`	`true` — macht den Eintrag zum Abschnitt; die Überschrift ist der `title`
`kc:sectionStyle`	`line` (Überschrift mit Linie, Standard) oder `spacing` (nur Abstand)
`kc:sectionLevel`	Größe der Überschrift: `1`, `2` oder `3`
`kc:sectionLayout`	anderes Raster ab diesem Abschnitt: `vertical`, `horizontal-2`, `horizontal-3`

Ein Abschnitt gilt bis zum nächsten Abschnitt. Überschriften können in der Seitenleiste bzw. im Inhaltsverzeichnis als Sprungmarke erscheinen; Abschnitte können zusätzlich eine Feldgruppe eröffnen.

Jeder Abschnitt darf außerdem sein eigenes Raster mitbringen. So stehen etwa die Kopfdaten zweispaltig, während der Nachrichten-Teil darunter einspaltig läuft:

Hinter den Kulissen: Zwei Abschnitte mit unterschiedlichem Raster

"_kopf":  { "type": "string", "title": "Kopfdaten", "kc:section": true, "kc:sectionLayout": "horizontal-2" },
"name":   { "type": "string", "title": "Name" },
"email":  { "type": "string", "title": "E-Mail" },

"_text":  { "type": "string", "title": "Nachricht", "kc:section": true, "kc:sectionLayout": "vertical" },
"betreff":   { "type": "string", "title": "Betreff" },
"nachricht": { "type": "string", "title": "Nachricht", "kc:widget": "textarea" }

Das Raster wechselt genau an der Überschrift und gilt bis zur nächsten — die Felder dazwischen tragen selbst keine Layout-Angabe.

`kc:spacer` — leere Zelle¶

Füllt eine Rasterzelle ohne Inhalt:

"_pad1": { "type": "string", "kc:spacer": true }

Beispiel: In einem 3-Spalten-Raster soll ein Feld in der Mitte stehen — dafür setzt du links und rechts davon je eine Leerzelle aus dem Baukasten.

Hinter den Kulissen: Ein Feld mittig im 3-Spalten-Raster

"kc:layout": "horizontal-3",
"properties": {
  "_pad1":  { "type": "string", "kc:spacer": true },
  "betrag": { "type": "number", "title": "Betrag" },
  "_pad2":  { "type": "string", "kc:spacer": true }
}

Die beiden Leerzellen belegen je eine Rasterspalte — deshalb rutscht das Betragsfeld in die Mitte. Verschiebt sich die Anordnung später, lohnt der Blick auf diese unscheinbaren Einträge.

Was erscheint wo?¶

Element	PDF	Trefferliste	Export (XML/CSV)
`kc:text`	ja (Absatz)	nein	nein
`kc:link`	nein	nein	nein
`kc:image`, `kc:svg`	ja	nein	nein
`kc:button`	nein	nein	nein
`kc:section`	ja	nein	nein
`kc:spacer`	Leerzelle	nein	nein

kc:printable: false (im Formular-Editor: Im PDF erscheinen aus) nimmt ein Element zusätzlich aus dem Ausdruck.

Stolperfallen¶

Name ohne Unterstrich — funktional egal, aber in Skripten stehen solche Namen dann zwischen den echten Daten.
kc:button ohne scriptHook und clientScript — der Knopf erscheint, tut aber nichts.
kc:image mit falschem src — die Datei muss im Asset-Ordner des Servers liegen, sonst bleibt das Bild leer.
Leittext als Text statt Objekt ("kc:text": "Hallo") — ältere Schreibweise; immer die Objekt-Form mit content verwenden.

Präsentations-Elemente¶

Was sie gemeinsam haben¶

kc:text — Leittext¶

kc:link — Link¶

kc:image und kc:svg — Bilder und Grafiken¶

kc:button — Schaltfläche¶

kc:section — Abschnittsüberschrift¶

kc:spacer — leere Zelle¶