Zum Inhalt

Datei-Bibliotheken

KCForms kennt zwei Quellen für wiederverwendbare Skript-Bibliotheken, die einem Formular zugewiesen und vor dessen Skripten geladen werden:

Quelle Pflege Liegt in Transport Geeignet für
Skript-Bibliotheken System-Administration → Formular-Bausteine → Skript-Bibliotheken Datenbank (kc_tools) reisen samt Zuordnung mit schnelle Pflege im Browser
Datei-Bibliotheken System-Administration → Formular-Bausteine → Datei-Bibliotheken oder direkt im Dateisystem .js-Dateien im Bibliotheks-Verzeichnis reisen samt Zuordnung mit Pflege per Editor und Git, größere Code-Basen

Beide lassen sich je Formular zuweisen und kombinieren. Geladen werden erst die Skript-Bibliotheken, dann die Datei-Bibliotheken (jeweils in der zugewiesenen Reihenfolge), dann die Hilfsfunktionen des Formulars — spätere können Funktionen der früheren nutzen (siehe Ladereihenfolge).

Transport ersetzt die Datei am Ziel

Ein Transport nimmt die zugewiesenen Datei-Bibliotheken samt Zuordnung mit, dazu die, die ein Validator verwendet. Am Zielsystem wird die Datei unter demselben Pfad geschrieben — eine dort vorhandene Datei gleichen Namens wird ersetzt. Nutzen mehrere Formulare dieselbe Datei, gilt nach dem Transport der Stand des sendenden Systems für alle.

Verzeichnis

Das Verzeichnis bestimmt die Einstellung kcforms.scripting.libs-dir; ohne Angabe ist es script-libs im KCForms-Datenverzeichnis (KCFORMS_HOME). Im Docker-Setup ist der Ordner script-libs des KCForms-Verzeichnisses als /app/script-libs eingehängt — Änderungen dort wirken sofort, ohne Neustart.

Drei zusammengehörige Namen sind im Spiel — sie beschreiben dieselbe Bibliotheks-Ablage aus verschiedenen Blickwinkeln:

Name Rolle
kcforms.scripting.libs-dir Einstellung — der Pfad, den das Backend liest (im Docker-Setup /app/script-libs).
KCFORMS_SCRIPT_LIBS_DIR Umgebungsvariable, die diese Einstellung setzt.
KCFORMS_SCRIPT_LIBS_HOST Nur Docker: welcher Ordner auf dem Host eingehängt wird.

Anderen Pfad für das Backend setzen:

# Linux/macOS
export KCFORMS_SCRIPT_LIBS_DIR=/opt/kcforms/lib-skripte

Anderen Host-Ordner einhängen (Docker; ändert nicht den Pfad im Container):

# Windows-PowerShell, im Ordner docker\
$Env:KCFORMS_SCRIPT_LIBS_HOST = "C:/Daten/KCForms/script-libs"
docker compose up -d

Dateistruktur

Jede .js-Datei ist eine Bibliothek; andere Dateien (z. B. README.md) werden ignoriert. Der Unterordner gibt die Kategorie vor:

Datei Kategorie
script-libs/validators/email-strikt.js validators
script-libs/validators/iban.js validators
script-libs/helpers/datum-utilities.js helpers
script-libs/allgemein.js (root)

Mitgeliefert ist helpers/ldap-tools.js (Suche, Gruppen, Mitgliedschaft — siehe LDAP).

JSDoc-Header

Optional — ein Kommentar-Kopf am Anfang legt Titel, Kategorie und Beschreibung fest:

/**
 * @title IBAN-Validator (DACH)
 * @category Validierung
 * @description Prüft IBAN-Prüfsumme nach DIN, gültig für DE/AT/CH.
 */

function validateIban(iban) { /* ... */ }

Ohne Header werden Fallbacks genutzt:

  • Titel ← Dateiname ohne .js
  • Kategorie ← Name des Unterordners (oder „(root)" bei Top-Level)
  • Beschreibung ← leer

Pflege

Im Browser

System-Administration → Formular-Bausteine → Datei-Bibliotheken:

  • Liste aller .js-Dateien, gruppiert nach Kategorie
  • Inhalt lesen, bearbeiten und speichern (auch mit Strg+S); Kategorie und Beschreibung lassen sich dort ebenfalls setzen
  • neue Datei anlegen (Pfad + leeres Gerüst)
  • Datei löschen

Auf dem Server

Lege .js-Dateien direkt im Bibliotheks-Verzeichnis an oder bearbeite sie mit deinem gewohnten Editor. Vorteile:

  • Versionierung mit Git — wer hat wann was geändert
  • volle Editor-Unterstützung (Prüfung, Umbenennen, Tests)
  • Zweige möglich — Änderung, Review, Zusammenführen

Der Browser-Editor zeigt externe Änderungen nach dem Neuladen der Seite.

Im Formular nutzen

  1. Im Formular-Editor das gewünschte Formular öffnen.
  2. Formular-Eigenschaften → Abschnitt Datei-Bibliotheken (Filesystem) aufklappen.
  3. Unter Verfügbar eine Datei mit + zuweisen.
  4. Reihenfolge mit ↑/↓ anpassen.
  5. Speichern (gilt nur für die Zuordnung, unabhängig vom Formular).

Ab dem nächsten Skript-Lauf (onLoad, onSubmit, onFieldChange …) wird der Inhalt der Dateien vor dem Skript geladen — alle Funktionen, die sie auf oberster Ebene anlegen, sind dann verfügbar:

// In den Datei-Libs definiert:
//   function isValidEmail(v) { ... }
//   function heuteIso() { ... }

// onSubmit nutzt sie ohne require/import:
if (!isValidEmail(ctx.form.email)) {
    ctx.addError('email', 'Bitte gültige E-Mail eingeben');
}
ctx.form.erfasstAm = heuteIso();

Verwaiste Zuweisungen

Wird eine Datei umbenannt oder gelöscht, die einem Formular zugewiesen ist, fällt sie:

  • aus der Liste Verfügbar im Formular-Editor heraus,
  • erscheint in der Zuweisungsliste rot mit „(Datei fehlt)",
  • wird beim Skript-Lauf still übersprungen — kein Abbruch, nur ein Debug-Eintrag im Protokoll. Funktionen daraus fehlen dann; der Aufruf scheitert erst an der Stelle, die sie benutzt.

Sicherheit

  • Alle Pfade werden geprüft — ../, das aus dem Verzeichnis hinausführt, wird abgewiesen.
  • Die Verwaltung (/api/admin/script-libs/…) ist Administratoren vorbehalten.
  • Wird das Verzeichnis schreibgeschützt eingehängt (:ro im Docker-Mount), sind Änderungen über den Browser gesperrt — sinnvoll auf Produktivsystemen, deren Bibliotheken ausschließlich über Git ausgerollt werden.

Siehe auch