Skript-Bibliotheken (`kc_tools`)¶

Skript-Bibliotheken sind wiederverwendbare JavaScript-Sammlungen. Statt denselben Prüfcode in zehn Formularen zu kopieren, schreibst du ihn einmal als Bibliothek und weist sie den Formularen zu, die sie brauchen. Bei jedem Skript-Lauf werden die zugewiesenen Bibliotheken vor dem eigentlichen Skript geladen.

Sie liegen in der Datenbank und werden in der Oberfläche gepflegt. Den zweiten Weg — Bibliotheken als .js-Dateien, gepflegt per Editor und Git — beschreibt Datei-Bibliotheken.

Ladereihenfolge¶

flowchart TB
    A["1 · KCForms-Vorspann<br/>(Date.format, $feld-Aliase …)"]
      --> B["2 · Bibliothek 1<br/>(z. B. Validators)"]
    B --> C["3 · Bibliothek 2<br/>(z. B. SAP-Adapter)"]
    C --> F["4 · Datei-Bibliotheken"]
    F --> D["5 · Hilfsfunktionen<br/>des Formulars"]
    D --> E["6 · Hook-Skript<br/>(onValidate, onSubmit …)"]

Zuerst die Skript-Bibliotheken in der zugewiesenen Reihenfolge, danach die Datei-Bibliotheken, dann die Hilfsfunktionen aus dem Reiter Skripte — so kann jede Stufe die vorherigen nutzen.

Alles läuft im selben Skript-Kontext: Was eine Bibliothek auf oberster Ebene anlegt, ist im Hook unter seinem Namen verfügbar.

Konzept¶

Eine Bibliothek ist ein JavaScript-Block mit eindeutigem Titel. Variablen, Funktionen und Objekte, die sie auf oberster Ebene anlegt, landen im selben Namensraum wie das nachfolgende Skript — und sind dort einfach unter ihrem Namen ansprechbar.

Beispiel — eine Bibliothek kc_tools_validators enthält:

var Validators = (function() {
  function iban(value) { /* … */ return true; }
  function bic(value)  { /* … */ return true; }
  return { iban: iban, bic: bic };
})();

Im Form-Skript des zugewiesenen Formulars:

// onValidate
if (!Validators.iban(ctx.form.iban)) {
  ctx.addError('iban', 'Bitte gültige IBAN eintragen.');
}

Das war's. Kein Import-Statement, kein require, keine Konfiguration im Skript selbst — die Bibliothek ist da, weil sie im Formular-Editor zugewiesen wurde.

Bibliothek anlegen¶

System-Administration → Formular-Bausteine → Skript-Bibliotheken

Feld	Bedeutung
Titel	Eindeutiger Name (z. B. `validators_finanz`); erscheint auch in Fehlermeldungen.
Beschreibung	Was tut die Bibliothek? Hilft Formular-Autoren bei der Auswahl.
Code	JavaScript. Empfohlen ist das Modul-Pattern (`var Foo = (function(){…})();`).
Aktiviert	Schalter zum vorübergehenden Stilllegen ohne Löschen.

Beim ersten Start legt KCForms die Beispiel-Bibliothek kc_tools_validators an — IBAN, BIC, E-Mail, PLZ, Telefon. Du kannst sie als Vorlage anpassen oder löschen.

Einem Formular zuweisen¶

Im Formular-Editor in den Formular-Eigenschaften, Abschnitt Skript-Bibliotheken (kc_tools) (unterhalb der Standard-Schaltflächen):

Unter Verfügbar stehen alle aktiven Bibliotheken — zuweisen hängt sie an das Formular.
Die zugewiesenen Bibliotheken lassen sich mit ↑/↓ sortieren und mit entfernen wieder lösen; ✏️ öffnet die Bibliothek zum Bearbeiten. Die Reihenfolge ist die Ladereihenfolge.
Zuordnung speichern sichert die Liste — unabhängig vom Speichern des Formulars.

Reihenfolge wann?

Wenn Bibliothek B Funktionen aus A nutzt, muss A oben stehen. Beispiel: A = generische Utils, B = Validators, die Utils.trim(...) aufruft.

In der Skript-Konsole nutzen¶

Zahnrad → Skript-Konsole

Über dem Editor steht der Bereich Skript-Bibliotheken einbinden. Wähle dort die Bibliotheken aus, die für den nächsten Lauf dazugeladen werden sollen. Die Auswahl gilt nur für die Konsole und wird nicht gespeichert.

Damit kannst du Service-/Diagnose-Skripte schreiben, die dieselben Validatoren nutzen wie ein produktives Formular:

// in der Skript-Konsole, mit kc_tools_validators ausgewählt
var rows = db.query("SELECT iban FROM kunden WHERE iban IS NOT NULL");
var ungueltige = rows.filter(r => !Validators.iban(r.iban));
log.info('Ungültige IBANs in kunden: ' + ungueltige.length);

Stack-Traces und Debugging¶

Tritt beim Laden einer Bibliothek ein Fehler auf — Syntaxfehler, Tippfehler —, bricht der gesamte Skript-Lauf ab. Die Fehlermeldung nennt den Titel der Bibliothek als Quelle:

SyntaxError at kc-tool:kc_tools_validators (line 42, col 8)

So siehst du sofort, welche Bibliothek den Fehler hat.

log.debug(...) aus der Bibliothek landet wie alle Skript-Protokolle in logs/script.log (einsehbar unter System-Administration → Betrieb & Überwachung → System-Logs). Die Beispiel-Bibliothek schreibt am Ende einen log.debug-Eintrag („geladen, X Funktionen") als Lebenszeichen.

Best Practices¶

Modul-Pattern verwenden statt freier Top-Level-Funktionen. Verhindert Namens-Kollisionen, wenn mehrere Bibliotheken ähnliche Helper haben.
Eindeutige Titel mit Präfix (kc_tools_finanz, kc_tools_personal) machen Suche und Verwaltung einfacher.
Version im Titel oder in der Beschreibung, wenn sich das Verhalten inkompatibel ändert (Validators v2).
Klein halten: eine Bibliothek = eine fachliche Funktionsklasse. Lieber drei kleine als eine 1000-Zeilen-Sammlung.
Erst in der Skript-Konsole entwickeln und sofort testen, dann den fertigen Code in die Bibliothek übernehmen.

Was `kc_tools` nicht sind¶

Keine Hooks — Bibliotheks-Code wird immer gleich beim Laden ausgeführt. Wenn du Logik nur in bestimmten Phasen wollen würdest, packe sie in eine Funktion und rufe die im Form-Hook auf.
Kein import/export — keine ECMAScript-Module. Alles läuft im selben Namensraum.
Keine User-Konfiguration — eine Bibliothek hat keine Parameter beim Laden. Wenn unterschiedliche Formulare anders agieren sollen, lies aus ctx.user, ctx.system.id oder Form-Feldern.
Keine Persistenz zwischen Hook-Läufen — jeder Hook bekommt einen frischen Kontext. Variablen, die du in einer Bibliothek setzt, sind nach dem Hook-Lauf weg.

DB-Layout¶

Tabelle	Inhalt
`kc_tools`	id, title (unique), description, code, enabled, timestamps
`form_tool`	form_id, tool_id, sort_order — n:m mit `ON DELETE CASCADE` auf tool-Seite

Wird eine Bibliothek gelöscht, verschwinden ihre Zuordnungen automatisch. Wird ein Formular gelöscht, bleiben seine Zeilen in form_tool stehen (die Formular-ID ist kein Fremdschlüssel). Sie stören nicht, lassen sich aber mit DELETE FROM form_tool WHERE form_id = ? entfernen.

Siehe auch¶

Datei-Bibliotheken — der zweite Wiederverwendungsweg: Bibliotheken als .js-Dateien im Filesystem, per IDE und git gepflegt.

Skript-Bibliotheken (kc_tools)¶