Feld-Validatoren (`kc:validator`)¶

Ein Feld-Validator prüft eine Eingabe mit einer JavaScript-Funktion aus einer Skript-Bibliothek — z. B. eine IBAN-, BIC- oder USt-IdNr.-Prüfung. Der Formular-Autor wählt den Validator pro Feld aus einer systemweiten Auswahlliste; programmieren muss er dafür nichts.

Diese Seite beschreibt die feldweise JS-Prüfung. Die Schema-Ebene (Type/Required/Pattern/Format) und der onValidate-Hook stehen daneben auf Validierung & Formate.

Validatoren laufen doppelt:

live im Browser — Sofort-Feedback beim Ausfüllen (sobald der Wert steht),
serverseitig beim Prüfen und beim Speichern — autoritativ, in der GraalVM-Sandbox.

Einen Validator bereitstellen (Bibliothek freigeben)¶

Validatoren sind normale Funktionen in einer Skript-Bibliothek unter script-libs/…. Damit eine Funktion als Validator auswählbar wird, gibt die Bibliothek sie im JSDoc-Header per @validators frei:

/**
 * @title IBAN-Prüfung
 * @category Validierung
 * @validators validateIban
 * @description Prüft Format + ISO-7064 Mod-97-Prüfsumme.
 */
function validateIban(value) {
  var s = String(value || '').replace(/\s+/g, '').toUpperCase();
  if (s === '') return true;                 // leer = gültig (kc:required separat)
  // … Prüfung …
  return ok ? true : 'IBAN-Prüfsumme ungültig';
}

Unter System-Administration → Formular-Bausteine → Datei-Bibliotheken gibt es dafür das Feld „Als Validatoren freigeben" — dort trägt man die Funktionsnamen komma-getrennt ein (validateIban, validateBic). Das schreibt genau die @validators-Zeile.

Auch DB-Bibliotheken (`kc_tools`)¶

Dasselbe geht mit den DB-basierten Skript-Bibliotheken (System-Administration → Formular-Bausteine → Skript-Bibliotheken): auch dort gibt es das Feld „Als Validatoren freigeben" (komma-getrennte Funktionsnamen). Die Freigabe steckt hier in einer Spalte statt im @validators-Header. Wichtig in beiden Fällen: freigegeben werden Top-Level-Funktionen (function validateIban(v){…}) — Methoden auf einem Objekt (Validators.iban) sind nicht als Validator adressierbar.

Vertrag der Validator-Funktion¶

fn(value, values) — bekommt den Feldwert und (optional) alle Formularwerte:

Rückgabe	Bedeutung
`true` / `undefined` / `null`	gültig
`false`	ungültig → `kc:validatorMessage` oder Standardtext
nicht-leerer String	ungültig → der String ist die Fehlermeldung

Leere Werte sollten als gültig behandelt werden — die Pflichtprüfung macht kc:required separat.

Einem Feld einen Validator zuweisen (im Formular-Editor)¶

Feldeigenschaften öffnen → Reiter „Format" → Abschnitt „Validierung":

Validator aus dem Dropdown wählen (Liste aller freigegebenen Funktionen).
Optional eine eigene Fehlermeldung angeben (überschreibt den Standard-/ false-Text; ein von der Funktion zurückgegebener String gewinnt aber immer).

Die Bibliothek muss dem Formular nicht extra zugewiesen werden — beim Prüfen lädt der Server die benötigte Validator-Bibliothek automatisch.

Schema (`kc:validator`)¶

"empfaenger_iban": {
  "type": "string",
  "title": "IBAN Zahlungsempfänger",
  "kc:validator": "validators/iban.js#validateIban",
  "kc:validatorMessage": "Bitte eine gültige IBAN eingeben"
}

kc:validator — eindeutige Kennung Bibliothek#Funktion:
- Datei-Bibliothek: "<Pfad>#<Funktion>" (z. B. validators/iban.js#validateIban).
- DB-Bibliothek: "kctool:<Titel>#<Funktion>" (z. B. kctool:kc_tools_validators#email) — bewusst über den Titel (nicht die DB-ID), damit Feld-Referenzen Neuinstallation/Transport überleben.
kc:validatorMessage (optional) — eigener Fehlertext.

Sicherheit¶

Der Live-Teil führt den Validator-Code im Browser aus (per new Function) — dieselbe Vertrauensgrenze wie bei kc:visibleIf/kc:calc: der Autor der Bibliothek ist vertrauenswürdig. Serverseitig läuft derselbe Code autoritativ in der GraalVM-Sandbox mit Timeout.

Beispiel¶

Die Datei-Bibliothek script-libs/validators/iban.js (validateIban) ist mitgeliefert und im Showcase-Formular „Kalkulation (Berechnungsfelder)" am Feld IBAN Zahlungsempfänger verdrahtet.

Für die DB-Bibliothek gibt es das Showcase-Formular „Validierung-Demo (Feld-Validatoren)" (Beispiele-Katalog Showcase): Felder für E-Mail, PLZ, Telefon, IBAN und BIC, jeweils gegen die freigegebenen Funktionen der Bibliothek kc_tools_validators geprüft. Ungültige Eingaben melden sofort einen Fehler.

Feld-Validatoren (kc:validator)¶