Im <Code>- Tag können wir JavaScript Code schreiben und haben damit ein sehr mächtiges Instrument, Inhalte in Vorlagen zu dynamisieren.

Alle 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 https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/398131214/Code#Funktionsaufrufe

• Ein primedocs-Feld wird folgendermassen geholt: $("Profile.User.FirstName"), siehe https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/398131214/Code#Zugriff-auf-Felder

• Das 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 ein return-Statement. Der Rückgabewert muss entweder implizit oder explizit geschehen. Siehe dazu das nächste Kapitel JavaScript in Fields. Beachte auch https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/398131214/Code#R%C3%BCckgabewert-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: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/398131214/Code#Aufrufe-in-Code

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 “

<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.

<Text Name="xHatSatz">
  <Code>
      function main() {
        switch ($('Forms.EmpfaengerTyp')) { // prüfe die Werte vom Empfängertyp
          case 'Einzelperson': // für den Fall 'Einzelperson'...
            return $('Forms.Vorname') + " hat "; // gib diesen Text zurück.
          case 'Ehepaar':
            return "Das Ehepaar hat ";
          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>

Elvis-Operator

Der Elvis-Operator ermöglicht eine Kontrollstruktur auf einer Code-Zeile:

[Wenn eine Bedingung wahr ist] ? [mach das eine] : [sonst, mach das andere];

Beispiel

<Text Name="MitteilungTitel">
  <!-- Wenn das Profilfeld nicht leer ist, 
                             gib den einen Text aus,                     sonst den anderen -->
  <Code>$("Profile.Org.Unit") ? "Mitteilung der " + $("Profile.Org.Unit") : "Mitteilung"</Code>
</Text>

Dieser Code bedeutet:

1. Wenn das Unit-Profilfeld nicht leer ist,

   1. gib den Text “Mitteilung der “ aus,

   2. sonst “Mitteilung”.

Beispiel Verschachtelung

Anweisungen können auch verschachtelt werden:

<Text Name="MitteilungTitel">
  <Code>$("Profile.Org.Unit") ? 
          "Mitteilung " + ($("Profile.Org.Unit") === "Einwohnerdienste" ? "an alle Einwohner" : " der" + $("Profile.Org.Unit"))
          : "Mitteilung"</Code>
</Text>

Dieser Code bedeutet:

1. Wenn das Unit-Profilfeld nicht leer ist, gib “Mitteilung “ aus und prüfe dann, ob das Unit-Profilfeld genau “Einwohnerdienste” enthält;

   1. falls ja, gib “an alle Einwohner” aus,

   2. sonst “ der [Unit-Profilfeld]”.

2. Wenn das Unit-Profilfeld leer ist, gib “Mitteilung” aus.

Fun Fact: der Elvis-Operator heisst so, weil die beiden Operanden ?: gedreht wie ein Elvis-Smiley aussehen.

Schlaufen (Loops)

Generell

• Mit Loops können wir über ein Array iterieren und für jedes Element in einer Liste etwas ausgeben.

• 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 oder false 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:

const fruits = [apple], [grape], [strawberry], [lemon];

for(var i=0; i < fruits.length; i++){
  const fruit = fruits[i]; // hole das Element an Position i
  return "Fruit: " + fruit + " at position: " + i + "\n";
}

Alternativen zum klassischen for-Loop

Nutze alternativ die folgenden besser verständlichen Varianten von for-Loops:

forEach mit Listenelement und mit index

const fruits = [apple], [grape], [strawberry], [lemon];

// Der Parameter 'fruit' ist der zurückgegebene Wert an der Position 'i'
myArray.forEach((fruit, i) => { 
  return "Fruit: " + fruit + " at position: " + i + "\n";
});

forEach mit Listenelement, ohne index

const fruits = [apple], [grape], [strawberry], [lemon];

// Der Parameter 'fruit' ist der zurückgegebene Wert
forEach(fruit of fruits){ 
  return "Fruit: " + fruit + " at position: " + fruit.indexOf() + "\n";
};

CDATA-Tag

Das CDATA-Tag (<![CDATA[Mein Text]]>) stellt sicher, dass alles zwischen Start- und Endtag nicht durch den Parser geht. Das nennt man “escapen”.

Somit muss man ohne ein CDATA-Tag & und kann mit einem CDATA-Tag nur & schreiben.

Funktionen

In diesem Abschnitt werden ein paar Funktionen genauer erklärt. Diese Seite dient dabei als Grundlage: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/398131214/Code#Funktionen

Funktion joinNonEmpty()

Gemäss Definition unter https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/398131214/Code#Erkl%C3%A4rung-aller-Funktionen-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 |.

<Text Name="Example1">
  <Code>$.joinNonEmpty(" | ", 'Profile.Org.Title', 'Profile.Org.Unit'); 
  // Resultat: "Beispielfirma | Beispielabteilung"</Code>
</Text>  

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.

<Text Name="Example2">
  <Code>$.joinNonEmpty("\n", // schwacher Zeilenumbruch
                   $('Profile.Org.Title'),
                   $('Profile.Org.Unit'),
                   $('Profile.Org.Postal.Street'),
                   $('Profile.Org.Postal.Zip') + " " + $('Profile.Org.Postal.City'));
    /* Resultat:
     Another Company
     Hardstrasse 201
     8005 Zürich
    */
  </Code>
</Text>  

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.

<Text Name="Example2">
  <Code>$('Profile.Org.Title') + "\n" +
        $('Profile.Org.Unit') + "\n" +
        $('Profile.Org.Postal.Street') + "\n" +
        $('Profile.Org.Postal.Zip') + " " + $('Profile.Org.Postal.City');
        
    /* Resultat:
     Another Company
  
     Hardstrasse 201
     8005 Zürich
    */
  </Code>
</Text>  

Datumsfunktionen und mit Daten rechnen

Beachte diese Liste: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/edit-v2/398131214#Erkl%C3%A4rung-aller-Funktionen-pro-API

Beispiel: 60 Tage zu einem Datum addieren

<Date Name="DatePlus60">
  <Code>
    function main(){
      let result = $("Forms.Date").Value; // auf den Wert zugreifen: result ist dann vom Typ Date
      result.setDate(result.getDate() + 60); // Berechnung
      return result;
    }
  </Code>
</Date>

Beispiel: Datum in einem bestimmten Datumsformat ausgeben

Datumsformat aus Text

<Text Name="DatePlus60">
  <!-- 1. Parameter date, 2. Parameter: format, Resultat: 2024-07-23 -->
  <Code>$.formatDate($("Forms.Date").Value, "yyyy-MM-dd")</Code>
</Text>

Datumsformat aus globalen Übersetzungen

<Text Name="DatePlus60">
  <!-- 1. Parameter date, 2. Parameter: format, Resultat: Dienstag, 23. Juli 2024 -->
  <Code>$.formatDate($("Forms.Date").Value,
                     $.translations.getText("Configuration.Date.WrittenOutWithDay"))</Code>
</Text>

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

<FormsConfiguration>
  <Elements>
    <ObjectCollection Id="Essen" Label="Essen">
      <Schema>
        <Text Id="Name" Label="Name" />
        <YesNo Id="IsGesund" Label="Ist gesund?" />
        <Date Id="GegessenAm" Format="dd.MM.yyyy" RelativeDate="Today" Label="Gegessen am" />
        <Choice Id="ImKuehlschrank" Label="Ist im Kühlschrank?" SelectedValue="ja">
          <Option Value="ja" Label="Ja" />
          <Option Value="nein" Label="Nein" />
        </Choice>
      </Schema>
    </ObjectCollection>
  </Elements>
</FormsConfiguration>

Fields Konfiguration

<FieldsConfiguration>
  <Fields>
    
    <Text Name="ObjectCollectionField">
      <Code>
        function main() {
          const firstElement = $('Forms.Essen')[0]; // nehme nur das erste Element
          if(firstElement !== null){
            const gesund = firstElement.IsGesund ? " ist gesund." : " ist nicht gesund." // Elvis-Operator: ?: = wenn IsGesund = true, mach (?) das eine, sonst (:) das andere.
            return $.joinNonEmpty("\n", // schwacher Zeilenumbruch
                         "Name: " + firstElement.Name + gesund,
                         "Zuletzt gegessen am: " + firstElement.GegessenAm,
                         "Ist im Kühlschrank: " + firstElement.ImKuehlschrank);                  
          } else { 
            return "In dieser Liste hat es keine Einträge.";
          }
        }
      </Code>
    </Text>
    
  </Fields>
</FieldsConfiguration>

Resultat

Das obere Beispiel zeigt nur das erste Element.

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:

1. Einen Loop/Schlaufe; lies dazu zuerst das: https://primesoft-group.atlassian.net/wiki/spaces/DELDEV/pages/175112198/JavaScript+in+primedocs+Fields#Schlaufen-%2F-Loops

2. 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? In der for-Schlaufe benötigen wir spezielle Zeichen. Der Einsatz dieser Zeichen ohne CDATA-Tag würde zu invalidem Code führen.

Mehrere Elemente einer Collection in einem Field anzeigen

<Text Name="ObjectCollectionField">
    <Code><![CDATA[ // escape =>
      function main() {
        const collection = $('Forms.Essen');
        let result = "";
        if(collection !== null){
          collection.forEach(collectionEntry => {
            const gesund = collectionEntry.IsGesund ? " ist gesund." : " ist nicht gesund." // Elvis-Operator: ?: = wenn IsGesund = true, mach (?) das eine, sonst (:) das andere.
            
            result += $.joinNonEmpty("\n", // schwacher Zeilenumbruch
                          "Name: " + collectionEntry.Name + gesund,
                          "Zuletzt gegessen am: " + collectionEntry.GegessenAm,
                          "Ist im Kühlschrank: " + collectionEntry.ImKuehlschrank,
                          " ") + "\n";
          
          }); 
          return result;
        } else { 
          return "In dieser Liste hat es keine Einträge.";
        }
      }
    ]]>
  </Code>
</Text>