JavaScript in Fields
Im <Code>
- Tag können wir JavaScript Code schreiben und haben damit ein sehr mächtiges Instrument, Inhalte in Vorlagen zu dynamisieren.
Alles was die Programmierung innerhalb von Code betrifft, ist hier dokumentiert: https://primesoft-group.atlassian.net/wiki/x/DgC7Fw. Wir empfehlen, zuerst diese Seite zu lesen.
Schnelleinführung in JavaScript
Generell
Um eine in primedocs vordefinierte Funktion aufzurufen, muss zuerst
$.
geschrieben werden. Beispiel:$.myFunction('Profile.User.FirstName')
, siehe Code | FunktionsaufrufeEin primedocs-Feld wird folgendermassen geholt:
$("Profile.User.FirstName")
, siehe Code | Zugriff auf FelderDas was in einem Funktionsaufruf in der Klammer steht, nennt man Parameter (oben ist “Profile.User.Name” der Parameter).
Ein Funktionsaufruf kann auch mehrere Parameter enthalten. Diese werden mit Komma getrennt:
$.myFunction('Profile.User.FirstName', anotherVariable)
Eine Variable, die später in deinem Skript einen anderen Wert annimmt, wird mit
let
definiert. Beispiel:let result = " ";
Eine Variable, die nie mehr einen anderen Wert annimmt (sogenannte Konstante), wird mit
const
definiert. Beispiel:const name = $.getText('Profile.User.FirstName');
Ein “Befehl” wird immer mit einem Semikolon abgeschlossen:
;
.Der Code in einem
Code
-Tag benötigt einen Rückgabewert über einreturn
-Statement. Der Rückgabewert muss entweder implizit oder explizit geschehen. Siehe dazu das nächste Kapitel JavaScript in Fields. Beachte auch Code | Rückgabewert von Field Typen.Einzeilige Kommentare werden mittels
//
gestartet.Für mehrzeilige Kommentare wird der gewünschte Text zwischen
/*
und*/
geschrieben.
JavaScript in Fields
Innerhalb des <Code>
-Tag sind zwei Varianten zum Ausführen von Code möglich: Code | Aufrufe in Code
TIPP
Um den Code übersichtlicher zu gestalten, verwenden wir wenn möglich den abgekürzten Aufruf.
Erst bei komplexeren Konfigurationen kommt der ausformulierte Aufruf zum Einsatz.
Kontrollstrukturen
Eine Kontrollstruktur prüft, ob eine Bedingung erfüllt ist oder nicht und gibt dann den Inhalt aus, der definiert wurde.
if-Statements
if-Statements sind praktisch, wenn man Bedingungen formulieren möchte wie “wenn [Bedingung], dann passiert A, sonst wenn [Bedingung 2], passiert B, […], sonst passiert Z”.
<FormattedText Name="EnclosuresBoxTitle">
<Code>
function main() {
// if-Statement
if($("Forms.Enclosures")) { // wenn das Enclosures-Forms-Feld nicht leer ist...
return $.translations.getFormattedText("FormattedTexts.Enclosures"); // hole den FormattedText
} else if($("Forms.CopyTo")) { // sonst, wenn das CopyTo-Forms-Feld nicht leer ist...
return $.translations.getFormattedText("FormattedTexts.CopyTo"); // hole den FormattedText
} else { // sonst...
return $.translations.getFormattedText("FormattedTexts.InvisibleLine"); // hole den FormattedText
}
}
</Code>
</FormattedText>
switch-case-Statements
Wenn ein Ausdruck mehrere verschiedene Werte haben kann, welche zu verschiedenen Resultaten führen, könnte dies mit vielen if
-statements gelöst werden (if(myVariable === "someContent")
).
Eine bessere Methode sind switch-case
-statements. Im switch
wird ein Ausdruck angegeben, welcher mittels jedem case
auf einen bestimmten Wert überprüft wird.
Beispiel mit direktem Rückgabewert
<Text Name="xHatSatz">
<Code>
function main() {
switch ($('Forms.EmpfaengerTyp')) { // prüfe die Werte vom Empfängertyp
case 'Einzelperson': return $('Forms.Vorname') + " hat "; // für den Fall 'Einzelperson', gib diesen Text zurück.
case 'Ehepaar': return "Die Ehegattin und der Ehegatte haben ";
case 'Familie': return "Die Familie hat ";
default: return " "; // sonst ist der Feldwert ein Leerschlag
// default wird ausgeführt, wenn kein Fall wahr ist.
// Das muss gesetzt werden, falls der Wert auch leer sein kann
// (z.B. der Benutzer in einem Choice-Forms-Feld nichts auswählen kann).
}
}
</Code>
</Text>
Beispiel mit breaks
<Text Name="xHatSatz">
<Code>
function main() {
let sentenceA = "";
switch ($('Forms.EmpfaengerTyp')) { // prüfe die Werte vom Empfängertyp
case 'Einzelperson':
sentenceA = $('Forms.Vorname'); // gib diesen Text zurück.
break;
case 'Ehepaar':
sentenceA = "Das Ehepaar";
break;
case 'Familie':
sentenceA = "Die Familie";
break;
default:
sentenceA = "Die Person"; // sonst ist der Feldwert ein leerer String
break;
}
return $.joinNonEmpty(" ", sentenceA, " hat")
}
}
</Code>
</Text>
Ternary-Operator ?:
Der Ternary-Operator ermöglicht eine Kontrollstruktur auf einer Code-Zeile:
[Wenn eine Bedingung wahr ist] ?
[mach das eine] :
[sonst, mach das andere];
Beispiel
Dieser Code bedeutet:
Wenn das Unit-Profilfeld nicht leer ist,
gib den Text “Mitteilung der “ gefolgt von
Unit
aus,sonst “Mitteilung”.
Beispiel Verschachtelung
Anweisungen können auch verschachtelt werden:
Dieser Code bedeutet:
Wenn das Unit-Profilfeld nicht leer ist, gib “Mitteilung “ aus und prüfe dann, ob das Unit-Profilfeld genau “Einwohnerdienste” enthält;
falls ja, gib “an alle Einwohner” aus,
sonst “ der [Unit-Profilfeld]”.
Wenn das Unit-Profilfeld leer ist, gib “Mitteilung” aus.
Schlaufen (Loops)
Generell
Mit Loops können Befehle wiederholt werden, bis eine Abbruchbedingung erreicht wird. Einer der häufigsten Anwendungsfälle ist das Iterieren über einen Array.
Arrays bzw. Collections haben eine endliche Anzahl Elemente. Dies nennt man “Länge” und sie kann so geholt werden:
myCollection.length
.Vorgehen:
for(Initialisierung; Test; Aktualisierung){/* Anweisungsblock */ }
Initialisierung: Die Laufvariable
i
wird zuerst definiert und ein Startwert gesetzt (praktisch immer 0).Test: Das Ergebnis dieser Expression muss
true
oderfalse
ergeben. Hier wird bei jedem Durchlaufen geprüft, ob die Schleife weiterlaufen muss oder der Endwert erreicht worden ist.Aktualisierung (Update): Die Laufvariable
i
wird nach jedem Durchlaufen der Schleife verändert. In den meisten Fällen wird sie hochgezählt:i++
Klassischer for-Loop
Mit dem klassischen for-Loop iteriert man über ein Array (z.B. eine ObjectCollection) und kann mit jedem Element im Array etwas machen.
Beispiel: for(var i=0; i < myArray.length; i++){/* mach etwas mit i */ }
Mein Array enthält vier Elemente: [0], [1], [2], [3]. Was in diesen Elementen genau ist, ist an dieser Stelle irrelevant.
Initialisierung: Initialisiere die Laufvariable
i
mit 0.Test: “Solange
i
kleiner ist als die Anzahl Elemente in meinem Array”Aktualisierung: zähle
i
nach jedem Durchlauf um + 1 hoch.
Ausführliches Beispiel for-Loop
In diesem Beispiel wird jedes Element im Array direkt ausgegeben als Teil eines Textes:
Alternativen zum klassischen for-Loop
Benötigt mindestens primedocs Version 4.0.20160
Nutze alternativ die folgenden besser verständlichen Varianten von for-Loops:
Loop mit map(), ohne Index
Code
Resultat
Loop mit map(), mit Index
Code
Resultat
forEach mit Listenelement, ohne index
Code
Resultat
forEach mit Listenelement und mit index
Code
Resultat
CDATA-Tag
In jeder Programmier- oder Scripting-Sprache gibt es bestimmte Sonderzeichen. Da wir hier JavaScript (JS) innerhalb von XML einsetzen, könnten Zeichen von JS fälschlicherweise als XML-Sonderzeichen interpretiert werden.
Um dies zu verhindern, kann das gesamte JS mit CDATA umschlossen werden: <![CDATA[Mein Text]]>
. Somit muss man ohne ein CDATA-Tag &
und kann mit einem CDATA-Tag nur &
schreiben.
Siehe Beispiele und mehr Informationen in der technischen Dokumentation: Code | CDATA Tag
Funktionen
In diesem Abschnitt werden ein paar Funktionen genauer erklärt. Dieses Kapitel dient dabei als Grundlage: Code | API Beschreibung
Funktion joinNonEmpty()
Gemäss Definition unter Code | Funktionen im Detail pro API, fügt diese Funktion die items
nacheinander zusammen und trennt sie dabei mit dem separator
.
Wir benutzen diese Funktion überall, wo wir Wörter aneinanderreihen müssen, z.B. in Kopfzeilen für das Aneinanderreihen von Profildaten.
Die wichtigste Eigenschaft dieser Funktion ist, dass dabei leere Parameter ausgelassen werden, sodass auch der separator
nur einmal ausgegeben wird.
Beide Parameter, separator
und items
, sind obligatorisch und müssen in genau dieser Reihenfolge gesetzt werden. D.h. der erste Parameter ist der Separator, alle weiteren Parameter sind die Felder, die zusammengeführt werden sollen.
Simples Beispiel
Die Funktion reiht alle Elemente an einander und trennt sie mit einem |
.
Umfangreicheres Beispiel
Die Funktion reiht alle Elemente an einander und trennt sie mit einem Zeilenumbruch (\n
).
In diesem Beispiel enthält das Feld Profile.Org.Unit
keinen Wert.
Umfangreicheres Beispiel “Empfängerliste“
Beachte, wie oben die einzelnen Zeilen übersichtlich untereinander dargestellt werden. So ist der Code schneller von anderen lesbar!
Wieso joinNonEmpty() nutzen?
Alternativ könnte man oberes Beispiel auch ohne die Funktion joinNonEmpty()
zusammenbauen (siehe Code unten).
Auch in diesem Beispiel ist das Feld Profile.Org.Unit
leer.
Das resultiert aber gerade darin, dass der “Separator” von der Zeile mit Profile.Org.Title
(+ "\n" +
) auch eingefüllt wird, wenn Profile.Org.Unit
keinen Wert enthält.
D.h. es wird so ein Zeilenumbruch eingefügt, obwohl man das in den meisten Fällen nicht möchte, siehe Resultat im Code.
Datumsfunktionen und mit Daten rechnen
Beachte diese Liste: Code | Funktionen im Detail pro API
Beispiel: 60 Tage zu einem Datum addieren
Beispiel: Datum in einem bestimmten Datumsformat ausgeben
Datumsformat aus Text
Datumsformat aus globalen Übersetzungen
ObjectCollections/Objects in Fields verwenden
Ein Element einer ObjectCollection in einem Field anzeigen
In diesem Beispiel haben wir folgende ObjectCollection in Forms und machen daraus via Fields eine kleine Übersicht mit dem ersten Element dieser Collection:
Forms Konfiguration
Resultat Forms
Fields Konfiguration
Resultat Fields
Dies resultiert mit folgenden Objects im Forms in diesem Text im Dokument:
Doch…
Mehrere Elemente einer ObjectCollection anzeigen
Wie können wir nun alle Elemente der ObjectCollection anzeigen?
Hierzu benötigen wir nun noch zwei neue Konzepte um dies umzusetzen:
Einen Loop/Schlaufe; lies dazu zuerst das: https://primesoft-group.atlassian.net/wiki/spaces/DELDEV/pages/175112198/JavaScript+in+primedocs+Fields#Schlaufen-%2F-Loops
Das CDATA-Tag; lies dazu zuerst das: https://primesoft-group.atlassian.net/wiki/spaces/DELDEV/pages/175112198/JavaScript+in+primedocs+Fields#CDATA-Tag
Wieso benötigen wir das im nächsten Beispiel? Im Loop benötigen wir auf Zeile 16 spezielle Zeichen. Der Einsatz dieser Zeichen ohne CDATA-Tag würde zu invalidem Code führen.
Mehrere Elemente einer Collection in einem Field anzeigen - Lösungsansatz 1 mit map()
Mehrere Elemente einer Collection in einem Field anzeigen - Lösungsansatz 2 mit for
Resultat Fields
Dies resultiert mit den Objekten in Forms in den folgenden Texten im Dokument.
Beim Lösungsansatz 2 wird noch ein Zeilenumbruch mehr eingefügt, daher empfehlen wir falls möglich den Lösungsansatz 1.
Field ItemsCollectionMap
Field ItemsCollection
PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland