Skripte in Beispielen¶

Dieser Bereich ist eine Beispielsammlung zum Mitmachen. Zu jedem Thema findest du mindestens 20 kleine Skripte — von ganz einfach bis zu Aufgaben aus dem echten Betrieb. Du musst nichts vorher wissen außer: Ein Skript ist eine kleine Anleitung, die KCForms Schritt für Schritt ausführt.

Die ausführliche Beschreibung jeder Funktion steht im Bereich Scripting. Hier geht es ums Ausprobieren.

Was sind eigentlich diese geschweiften Klammern?

Wenn dir Begriffe wie Variable, Objekt, Liste oder Schleife noch nichts sagen, fang hier an: JavaScript-Grundlagen und JSON und Objekte verstehen. Beide erklären in einfachen Worten, was in fast jedem Beispiel hier vorkommt.

Die Themen¶

Thema	Worum es geht
Erste Schritte	Felder lesen und setzen, rechnen, Texte und Datumswerte, Fehler melden
Datenbank (SQL)	Zählen, suchen, einfügen, ändern — bis zur Transaktion
Datensätze (forms)	Formular-Datensätze per Skript anlegen, lesen, ändern, löschen
Verzeichnis (LDAP)	Benutzer prüfen, suchen, auslesen — bis zum Anlegen und Ändern
CSV-Dateien	Tabellen einlesen und schreiben, z. B. für Excel
Dateien (fs)	Dateien lesen, schreiben, auflisten, verschieben
Internet (HTTP)	Webseiten und Schnittstellen abfragen, Daten senden
XML und WebServices	XML lesen und bauen, SOAP-Dienste aufrufen
E-Mail	Mails schreiben, mit Anhang, als HTML, an viele Empfänger
Dialoge und Meldungen	Fehler am Feld, Hinweise und Fragen im Formular anzeigen
PDF, ZIP und Word	Ausdrucke erzeugen, Dateien packen, Briefe füllen
Zeitgesteuerte Jobs	Aufgaben, die nachts oder stündlich laufen — Import, Aufräumen, Berichte
Workflow	beim Weiterleiten Felder setzen, prüfen, Mails schicken, exportieren, andere Programme benachrichtigen
REST-Services	eigene Schnittstellen für andere Programme

Jede Seite ist gleich aufgebaut:

Einsteiger — ein bis fünf Zeilen, eine Sache auf einmal.
Fortgeschritten — mehrere Schritte, Schleifen, eigene Funktionen.
Profi — so, wie man es im echten Betrieb baut: mit Fehlerbehandlung, Transaktionen und Aufräumen.

Wo probiere ich ein Beispiel aus?¶

Am schnellsten in der Skript-Konsole: System-Administration → Werkzeuge & Diagnose → Skript-Konsole. Beispiel hineinkopieren, Ausführen klicken, unten die Ausgabe lesen. Die Konsole bietet fast alle Werkzeuge; einige Beispiele (Dialoge, PDF des Formulars, Dateianlagen) brauchen dagegen ein Formular — dort steht es dann dabei.

In einem Formular gehört ein Skript in einen Hook: im Formular-Editor den Reiter Skripte öffnen, einen Hook wählen (etwa onLoad beim Öffnen oder eine Schaltfläche) und das Skript einfügen. Was welcher Hook tut, steht unter Hooks und Reihenfolge.

Die Beispiele sind getestet

Jedes Beispiel auf diesen Seiten wird automatisch gegen ein echtes KCForms ausgeführt. Wenn eines bei dir nicht läuft, liegt es meist an Namen, die bei dir anders heißen: Formularfelder (name, betrag …), Tabellen, der LDAP-Konnektor kcads oder Dateipfade. Passe sie an.

Fünf Dinge, die du immer brauchst¶

1. Etwas ausgeben — log.info(...) schreibt eine Zeile ins Protokoll. In der Skript-Konsole siehst du sie sofort unten.

log.info("Hallo KCForms!");

2. Ein Formularfeld lesen und setzen — alle Felder stehen in ctx.form.

log.info("Hallo " + ctx.form.name);
ctx.form.ergebnis = "gelesen";

3. Mit Zahlen rechnen — Felder kommen als Text an. .num am Feld macht daraus eine Zahl. (Für Werte, die nicht aus einem Feld kommen — aus der Datenbank, aus einer CSV-Datei, aus einer Detail-Zeile — heißt dasselbe kc.num(...).)

var summe = $menge.num * $preis.num;
log.info(summe);   // 7.5

4. Eine Entscheidung treffen — mit if.

if ($betrag.num > 1000) {
  log.info("Ein großer Betrag");
} else {
  log.info("Ein kleiner Betrag");
}

5. Einen Fehler abfangen — try … catch verhindert, dass ein Problem das ganze Skript abbricht.

try {
  var zeile = db.queryOne("SELECT * FROM gibt_es_nicht");
} catch (e) {
  log.warn("Das ging schief: " + e.message);
}

Häufige Stolpersteine¶

Problem	Lösung
`"3" + "4"` ergibt `"34"`	Feldwerte mit `.num` in Zahlen umwandeln (`$betrag.num`); sonst `kc.num(...)`
Betrag steht englisch da (`1234.50 €`)	`.toFixed(2)` kennt nur den Punkt. `$betrag.numFormat(null, "€", 0, 2, ",", ".", 3)` liefert `1.234,50 €` — Beschreibung
Groß-/Kleinschreibung	JavaScript unterscheidet `Name` und `name`; Tabellennamen je nach Datenbank auch (`USERS` ≠ `users`)
`JSON.stringify(zeile)` zeigt `{}`	Datenbankzeilen sind Java-Objekte. Werte einzeln lesen (`zeile.name`) oder mit `for (var k in zeile)` durchgehen — Erklärung
Skript bricht nach 6 Sekunden ab	Das Zeitlimit schützt den Server. Große Mengen in kleinen Portionen oder als Job verarbeiten
Tabelle heißt wie ein SQL-Wort (`GROUPS`, `ORDER` …)	Namen in Backticks setzen: SELECT * FROM `GROUPS` (MySQL)
`return` außerhalb einer Funktion	ist erlaubt und beendet das Skript — `return false` bricht in `onBeforeSave` das Speichern ab