Zum Inhalt

Hilfsfunktionen (formulareigen)

Der Funktions-Container eines Formulars ist der Platz für Code, den mehrere Hooks desselben Formulars brauchen — aber sonst niemand. Hier definierte Funktionen und Konstanten stehen in jedem Skript dieses Formulars zur Verfügung, ohne Import und ohne Zuweisung.

Wann welche Wiederverwendung?

KCForms kennt drei Wege, Skript-Code mehrfach zu nutzen. Die Wahl hängt davon ab, wer den Code braucht:

Weg Gehört Gepflegt in Zuweisung nötig?
Skript-Bibliotheken vielen Formularen System-Administration → Formular-Bausteine → Skript-Bibliotheken ja, je Formular
Datei-Bibliotheken vielen Formularen Dateisystem (mit Git versionierbar) ja, je Formular
Hilfsfunktionen einem Formular im Formular selbst nein

Faustregel: Sobald ein zweites Formular denselben Code braucht, gehört er in eine Bibliothek. Solange er nur zu diesem Formular gehört, gehört er in die Hilfsfunktionen — dort bleibt er beim Formular, statt die zentrale Bibliotheksliste mit Einzelfällen zu füllen.

Anlegen

Im Formular-Editor im Reiter Skripte. Der Eintrag Hilfsfunktionen steht immer ganz oben über der Hook-Liste — auch bei Formularen, die noch gar keine Skripte haben. Ein Klick legt ihn an und öffnet den Editor; gespeichert wird er wie jeder Hook mit dem Formular.

Beispiel

Im Container:

// Netto → Brutto, an mehreren Stellen dieses Formulars gebraucht.
function brutto(netto, satz) {
  return Math.round(netto * (1 + satz / 100) * 100) / 100;
}

var MWST_SATZ = 19;

In einem beliebigen Hook desselben Formulars — ohne weiteres Zutun:

// onFieldChange
ctx.form.bruttobetrag = brutto(ctx.form.nettobetrag, MWST_SATZ);

Reihenfolge im Skript-Kontext

Der Container wird vor dem Hook ausgeführt und nach den zugewiesenen Bibliotheken:

  1. KCForms-Vorspann (Date.format, $feld-Aliase …)
  2. Skript-Bibliotheken (zugewiesen, zentral gepflegt)
  3. Datei-Bibliotheken (zugewiesen, aus dem Dateisystem)
  4. Hilfsfunktionen — dieses Formular
  5. der Hook selbst (onLoad, onSubmit …)

Daraus folgt zweierlei:

  • Die Hilfsfunktionen dürfen Bibliotheks-Funktionen benutzen.
  • Trägt eine Funktion hier denselben Namen wie eine Bibliotheks-Funktion, gewinnt die Hilfsfunktion — die speziellere Definition setzt sich durch. Das ist der vorgesehene Weg, um für ein einzelnes Formular von einer zentralen Bibliothek abzuweichen.

Überschreiben nur mit function und var

Das Überschreiben klappt für Namen, die mit function oder var angelegt sind. Legen Bibliothek und Hilfsfunktionen denselben Namen mit const oder let an, scheitert jedes Skript des Formulars mit „Variable … has already been declared" — ohne Hinweis, wo die doppelte Definition steht. Für Konstanten, die überschreibbar sein sollen, deshalb var verwenden.

Reichweite

Der Container gilt für alle Skript-Läufe dieses Formulars:

  • Lebenszyklus-Hooks (onLoad, onFieldChange, onValidate, …)
  • die gesamte Speicher- und Lösch-Pipeline
  • Custom-Hooks hinter Schaltflächen (kc:button.scriptHook)
  • die Workflow-Skripte (onWorkflowCheck…, onWorkflowStep…, onWorkflowEnter…) und canEdit

Was er nicht ist

Kein Hook. Der Container wird nie aufgerufen, sondern immer nur vorangestellt. Eine Schaltfläche kann ihn deshalb auch nicht als scriptHook verwenden — der Versuch wird mit einem Hinweis abgewiesen. Würde er zusätzlich als Hook laufen, wertete er seine Definitionen ein zweites Mal aus, und das Verhalten wäre kaum noch erklärbar.

Praktisch heißt das: Schreib hier Definitionen (Funktionen, Konstanten), keine Anweisungen, die etwas tun. Code auf oberster Ebene läuft bei jedem Hook-Aufruf mit.

Transport und Versionierung

Der Container liegt beim Formular und reist mit ihm:

  • Formular-Export/-Import (ZIP, Ordner-Sammelexport) nimmt ihn mit
  • Transport zwischen Systemen (DEV → QS → PROD) ebenfalls
  • Versions-Snapshots speichern ihn mit ab

Das ist der praktische Unterschied zu den Bibliotheken: Wer ein Formular auf ein anderes System schiebt, muss dort keine Bibliothek nachziehen, damit es läuft.

Zur Laufzeit gilt immer der aktuelle Container

Anders als beim canEdit-Hook greift die Laufzeit nicht auf die im Snapshot eingefrorene Fassung zurück: Auch ein Altsatz einer früheren Formularversion läuft mit dem heutigen Container. Wer eine Hilfsfunktion ändert, ändert sie damit rückwirkend für alle Datensätze.

Wenn ein Verhalten versionsfest sein muss, gehört es in den Hook selbst — dessen Snapshot wird ausgewertet.

Fehlerverhalten

Ein kaputter Container legt ALLE Skripte des Formulars lahm

Das ist die Kehrseite von „gilt für alle Hooks": Ist der Container syntaktisch fehlerhaft, scheitert jeder Hook dieses Formulars — auch die, die gar nichts daraus benutzen. Die Fehlermeldung nennt dabei die Quelle mit Zeile und Spalte, z. B. SyntaxError: kc-tool:Hilfsfunktionen:1:14 ….

Nach einer Änderung am Container also einmal einen Hook auslösen und prüfen, ob er noch läuft.

Nicht gefährlich ist dagegen ein fehlender Container: Formulare ohne Hilfsfunktionen verhalten sich exakt wie zuvor.