Das Code-Tag ist verfügbar in jedem Field-Typen und bietet die Möglichkeit, die Ausgabe eines Field mittels JavaScript beliebig zu implementieren.

Mehr Beispiele zu Fields oder eine Einführung zu JavaScript finden Sie im Layouter-Handbuch.

Aufrufe in Code

Innerhalb des <Code>-Elements sind zwei Varianten möglich, wie man Code ausführen kann.

Abgekürzter Aufruf

Besteht der Code aus nur einer Anweisung, kann er direkt in den Block geschrieben werden.
Das return Statement ist implizit.

<Text Name="Footer">
  <Code>$.getText('Profile.User.FirstName')</Code>
</Text>

Ausformulierter Aufruf

Besteht der Code aus mehreren Anweisungen und/oder enthält Variabeln, muss er innerhalb der function main() geschrieben werden.
Innerhalb desselben Code-Blocks können auch andere Funktionen zur Werwendung in main definiert werden.
Das return Statement in main muss explizit gesetzt werden.

<Text Name="Footer">
  <Code>
    function main() { 
      let firstName = $.getString('Profile.User.FirstName');
      if (firstName == 'Foo') {
        firstName = appendBar(firstName);
      }
      return firstName;
    }
    
    function appendBar(str) {
      return str + 'Bar';
    }
  </Code>
</Text>

API-Beschreibung

In einem Code-Element leitet $ jeweils die Nutzung der primedocs-API ein.

Zugriff auf Felder

Mit $("[Feld]") greift man auf Forms-Felder, Fields sowie Profilfelder zu. Folgend ein Beispiel pro Feld-Art:

Forms-Feld	`<Code>$("Forms.Subject")</Code>`
Field	`<Code>$("Header")</Code>`
Profil-Feld: Benutzer	`<Code>$("Profile.User.FirstName")</Code>`
Profil-Feld: Organisation	`<Code>$("Profile.Org.Unit")</Code>`

Funktionsaufrufe

Weiter leitet $. den Aufruf einer primedocs-eigenen Funktionen ein: $.myFunction()

Es ist möglich, allgemeine JavaScript-Funktionen zu verwenden (z.B. foreach() auf Arrays (ObjectCollections) oder replace() auf Strings). Konsultieren Sie für mehr Informationen Mozilla’s JavaScript Dokumentation.

Rückgabewert von Field-Typen

Der Rückgabewert von main() in Code muss vom Datentyp her immer dem Field entsprechen. Beispielsweise ist es nicht möglich, ein Date-Forms-Feld in einem Text-Field auszugeben. Umgekehrt kann ein Date-Field keinen String/Text ausgeben sondern nur Date-Forms-Felder oder Date-Fields.

Hier eine Übersicht:

Field-Typ	Rückgabetyp
Text	`String`
FormattedText	`FormattedText`
WordContent	`WordContent`
Date	`Date`
YesNo	`Boolean`
Picture	Image (z. B. `Profile.Org.Logo`)

Native Funktionen

In der offiziellen Dokumentation von Mozilla können alle nativen Funktionen eingesehen und über einen Playground ausprobiert werden. Diese können gemäss dieser Liste auch in primedocs Code verwenden werden.

Übersicht über alle primedocs-eigenen Funktionen

Es folgt eine sortierbare Tabelle mit allen primedocs-eigenen Funktionen: welcher API sie angehören und dem jeweiligen Rückgabetyp.

API	Funktion	Rückgabetyp
$	getText()	String
$	getDateAsString()	String
$	joinNonEmpty()	String
$	formatDate()	String
$	getDate()	Date
$	setDate()	void
$.formattedText	fromText()	FormattedText
$.formattedText	parse()	FormattedText
$.wordContent	fromFormattedText()	WordContent
$.wordContent	fromText()	WordContent
$.translations	getText()	String
$.translations	getFormattedText()	FormattedText
$.snippets	getFormattedText()	FormattedText
$.snippets	snippets.getWordContent()	WordContent
$.formattedText	getBuilder()	FormattedText-Builder
$.wordContent	getBuilder()	WordContent-Builder

Funktionen mit benannten Parameter

Manche Funktionen enthalten als zweiten Parameter ein Objekt mit einer kommagetrennten Liste von Key-Value-Pairs. Die Key-Value-Pairs nennen wir “benannte Parameter”.

Die Values der Key-Value-Pairs können jede Art von Strings sein. Dies beinhaltet:

Aufruf von Profildaten / Forms-Felder / Fields, siehe unten Key name
Fixtext, siehe unten Key info
Referenzen auf Variabeln, siehe unten Key function

Im folgenden Beispiel wird in einem Field Header eine globale Übersetzung vom Typ FormattedText zurückgegeben. Der Funktionsaufruf von getFormattedText erfodert die Id der globalen Übersetzung und als zweiten Parameter eine Liste von drei Key-Value-Pairs mit den Keys name, info und function.

<FormattedText Name="Header">
  <Code>
    function main(){
      let myVariable = $("Forms.SignerMain.User.Function");
      return $.translations.getFormattedText("FormattedTexts.FooterBoldWithParams", {
        name: $("Forms.SignerMain.User.FirstName") + " " + $("SignerMainLastName"),
        info: "Fixtext ist auch möglich",
        function: myVariable 
      });
    }
  </Code>
</FormattedText>

Erklärung aller Funktionen pro API

Im Folgenden wird jede Funktion detailliert beschrieben:

Funktion	Zweck
getText(String id)	Holt unformatierten Text via `id` explizit. Alternativ kann auch ein impliziter Aufruf getätigt werden (siehe Beispiel). Parameter `id`: Feld-Id. Das Feld hinter `Id` muss ein String ausgeben. Rückgabetyp: `String` <Text Name="FirstName2"><!-- explizit --> <Code>$.getText('Profile.User.FirstName')</Code> </Text> <Text Name="FirstName1"><!-- implizit --> <Code>$('Profile.User.FirstName')</Code> </Text>
getDateAsString(String id)	Holt ein Datumsfeld mittels `id` und konvertiert es in einen String (= unformatierten Text). Parameter `id`: Feld-Id. Das Feld hinter `Id` muss ein Datum ausgeben. Rückgabetyp: `String` <Text Name="Date"> <Code>$.getDateAsString("Forms.Date")</Code> </Text>
joinNonEmpty(String separator, String item1, String item2, […])	Fügt die in der Liste aufgeführten `items` vom Typ `String` zusammen und trennt sie anschliessend mit dem `separator`. Parameter `separator`: String. Zeichen, das als Separator zwischen allen Listenelementen agiert. Parameter `item1`, `item2` und ff.: alle Parameter nach `separator` bilden eine Liste von Strings, die hinter einander ausgegeben werden. Rückgabetyp: `String` `$.joinNonEmpty(" / ", $('Profile.Org.Title'), $('Profile.Org.Unit')) Resultat: "Beispielfirma / Beispielabteilung"` Mehr Informationen hier: https://primesoft-group.atlassian.net/wiki/spaces/PD/pages/edit-v2/395444225#Funktion-joinNonEmpty()
formatDate(Date date, String format)	Passt das Format eines Datumsobjekts `date` an zum gewünschten `format`. Parameter `date`: Datumsobjekt, entweder aus Datums-Forms-Feld, Datums-Field oder aus `new Date()`. Parameter `format`: String. Gibt das Datumsformat an gemäss dieser Liste: Custom date and time format strings - Microsoft Learn. Im Parameter kann auch eine globale Übersetzungen geholt werden. Rückgabetyp: `String` `$.formatDate($("Forms.Date").Value, "yyyy-MM-dd")`
getDate()	Holt ein Datumsobjekt, damit man damit rechnen kann. Rückgabetyp: `Date` Siehe unten für mehr Informationen. Holt ein Datumsobjekt, das in einer Variable gespeichert ist für die Funktion `setDate()`. Rückgabetyp: `Date` Siehe Beispiel: https://primesoft-group.atlassian.net/wiki/spaces/PD/pages/edit-v2/395444225#Beispiel%3A-60-Tage-hinzuf%C3%BCgen

formattedText API

Funktion

Zweck

formattedText.fromText(String text)

Konvertiert einen String zu einem FormattedText.
Parameter text: String oder Feld, das einen String zurückgibt.
Rückgabetyp: String

Beispiel mit einem String:
$.formattedText.fromText("Ein lustiger Satz.")

Beispiel mit Referenz auf ein Feld:
$.formattedText.fromText($("Forms.Subject"))

formattedText.parse(String html, Object parameters)

Baut aus den Argumenten einen FormattedText.
Parameter html: String, der die HTML-Definition des FormattedText und ggf. Platzhalter im Format {{placeholderName}} enthält.
Parameter parameters: Beschreibung aller Parameter, die als Platzhalter in html vorkommen.
Platzhalternamen innerhalb eines FormattedText müssen eindeutig.
Rückgabetyp: FormattedText

Beispiel ohne benannte Parameter:
$.formattedText.parse("<p data-word-style-id="Quote">Absatz in built-in 'Quote' Style</p>");

Beispiel mit benannten Parametern:
$.formattedText.parse("<p data-word-style-id="Quote">{{something}}</p>", { something: "Absatz in built-in 'Quote' Style" });

formattedText.getBuilder()

Siehe Kapitel Builder

Erstellt ein Builder-Objekt, um darauf aufbauend FormattedText oder Text mit der Funktion append() anzuhängen.

$.formattedText.getBuilder()

wordContent API

Funktion

Zweck

wordContent.fromFormattedText(FormattedText ft)

Konvertiert einen FormattedText zu einem WordContent.
Parameter ft: Parametertyp: FormattedText, zwingend.
Rückgabetyp: WordContent

Beispiel mit FormattedText aus Übersetzung:

$.wordContent.fromFormattedText($.translations.getFormattedText("FormattedTexts.CopyTo"))

Beispiel mit FormattedText aus Textbaustein:

$.wordContent.fromFormattedText($.snippets.getFormattedText("Introduction"))

Beispiel mit Referenz auf Feld:

$.wordContent.fromFormattedText($("IntroductionFT"))

wordContent.fromText(String text)

Konvertiert einen Text zu einem WordContent.
Parameter text: Parametertyp: String, zwingend.
Rückgabetyp: WordContent

Beispiel mit einem String:

$.wordContent.fromText("Ein lustiger Satz.")

Beispiel mit Referenz auf ein Feld:

$.wordContent.fromText($("Forms.Subject"))

wordContent.getBuilder()

Siehe Kapitel Builder

Erstellt ein Builder-Objekt, um darauf aufbauend WordContent, FormattedText oder Text mit der Funktion append() anzuhängen.

$.wordContent.getBuilder()

translations API

In der Gruppe translations gibt es folgende Funktionen:

Funktion

Zweck

translations.getText(String id)

Holt eine unformatierte Übersetzung aus den globalen Übersetzungen.
Parameter id: Parametertyp: String, zwingend, Angabe der Id des Übersetzungseintrags in den Globalen Übersetzungen
Rückgabetyp: String

$.translations.getText("Texts.Subject")

translations.getFormattedText(String id, Object parameters)

Holt eine formatierte Übersetzung aus den globalen Übersetzungen.

Parameter id: Parametertyp: String, zwingend, Angabe der Id des Übersetzungseintrags in den Globalen Übersetzungen
Parameter parameters: Parametertyp: Object, falls die Übersetzung über Parameter verfügt, zwingend:
Liste von Key-Value-Pairs mit Values gemäss Übersetzung (Typen in Handlebars: Strings, Arrays oder Booleans).
Rückgabetyp: FormattedText

Beispiel ohne parameters:

$.translations.getFormattedText("ContractTitle")

Beispiel mit parameters:

$.translations.getFormattedText("FormattedTexts.Paragraphs.BoldNormal", { bold: $("Forms.Subject"), normal: "Untertitel-Text" } )

snippets API

In der Gruppe snippets gibt es folgende Funktionen:

Funktion

Zweck

snippets.getWordContent(String key, Object placeholders)

Holt ein WordContent-Textbaustein mit einem bestimmten Schüssel.
Parameter key: obligatorisch, Parametertyp: String, Angabe des Textbaustein-Schlüssels
Parameter placeholders: Parametertyp: Object, es SnippetPlaceholder gibt, zwingend,
Liste von Key-Value-Pairs mit String-Values
Rückgabetyp: WordContent

SnippetPlaceholder können nur mit Strings gefüllt werden.

Beispiel ohne placeholders:

$.snippets.getWordContent("Introduction")

Beispiel mit placeholders:

$.snippets.getWordContent("Introduction", { dateToday: $.getDateAsString("Forms.Date"), guests: $("Guests") } )

snippets.getFormattedText(String key)

Holt einen formatierten Text als Textbaustein mit einem bestimmten Schüssel.
Parameter key: Parametertyp: String, obligatorisch, Angabe des Textbaustein-Schlüssels
Rückgabetyp: FormattedText

$.snippets.getFormattedText("FooterFTSnippet")

Builder API

Die Builder-API kann in einem FormattedText-Field oder einem WordContent-Field verwendet werden und ermöglicht das Zusammensetzen von Texts, FormattedTexts und WordContents im Sinne eines Baukastensystems, indem jeder Text, unabhängig vom Typ, aneinander gereiht wird.

Einsatz

Der Einsatz des Builder macht nur Sinn, wenn mehrere Text-Absätze ggf. konditional aneinander gereiht werden müssen.

Funktionen

Funktion	Zweck
formattedText.getBuilder()	Erstellt ein FormattedText-Builder-Objekt, um damit `FormattedText` oder `Text` mit der Funktion `append()` anzuhängen. Parameter: keine Rückgabetyp: `FormattedText`-Builder-Objekt Aufruf in einem `FormattedText`-Field: `$.formattedText.getBuilder()`
wordContent.getBuilder()	Erstellt ein WordContent-Builder-Objekt, um damit `WordContent`, `FormattedText` oder `Text` mit der Funktion `append()` anzuhängen. Parameter: keine Rückgabetyp: `WordContent`-Builder-Objekt Aufruf in einem `WordContent`-Field: `$.wordContent.getBuilder()`
append(WordContent/FormattedText content)	Hängt den Inhalt von Parameter `content` in die Builder-Pipeline. Parameter `content`: zwingend, Parametertyp `WordContent` oder `FormattedText`, je nach dem in was für einem Field-Typen man sicht befindet. Rückgabetyp: `WordContent` oder `FormattedText` Aufruf auf dem Builder-Objekt bspw. in einem `WordContent`-Field: `builder` `.append($.snippets.getWordContent("Introduction"))` `.append($.wordContent.fromText(" - mit Builder"))` Siehe ausführliches Beispiel weiter unten.
build()	Letzter zwingender Funktionsaufruf in einer Reihe von Builder-Funktionen. Löst die Build-Pipeline aus und baut sich dann alle “appended” Teile von links nach rechts zusammen. Parameter: keine Rückgabetyp: FormattedText/WordContent Aufruf auf dem Builder-Objekt: `builder.build()`

Anwendung

Massgebend für die Anwendung des Builder sind folgende Regeln:

Ein FormattedText-Field kann nur FormattedText und Text ausgeben.
Ein WordContent-Field kann WordContent, FormattedText und Text ausgeben.

Die Field-Typ-fremden Objekte müssen dabei zuerst in den Ziel-Field-Typ konvertiert werden. So muss z. B. in einem WordContent-Field der Aufruf eines FormattedText aus der Konvertierungsfunktion fromFormattedText() passieren:

.append($.wordContent.fromFormattedText($.translations.getFormattedText("FormattedTexts.CopyTo")))

Dasselbe bei WordContent-Fields oder FormattedText-Fields und die Ausgabe von Text:

.append($.formattedText.fromText(" - mit Builder"))

Beispiel: Builder für WordContent-Field und FormattedText-Field

<FieldsConfiguration>
  <Fields>

    <WordContent Name="WCSnippetBuilder">
      <Code>$.wordContent.getBuilder() // Builder-Objekt erstellen
            .append($.snippets.getWordContent("Introduction")) // WordContent anhängen
            .append($.wordContent.fromFormattedText($.translations.getFormattedText("FormattedTexts.CopyTo"))) // FormattedText als gl. Übersetzung anhängen
            .append($.wordContent.fromText(" - mit Builder")) // Text anhängen
            .build() // Alles zusammenbauen
      </Code>
    </WordContent>
    
    <FormattedText Name="FTSnippetBuilder">
      <Code>$.formattedText.getBuilder() // Builder-Objekt erstellen
            .append($.snippets.getFormattedText("IntroductionFT")) // FormattedText als Textbaustein anhängen
            .append($.translations.getFormattedText("FormattedTexts.CopyTo")) // FormattedText als gl. Übersetzung anhängen
            .append($.formattedText.fromText(" - mit Builder")) // Text anhängen
            .build() // Alles zusammenbauen
      </Code>
    </FormattedText>
        
  </Fields>
</FieldsConfiguration>

Individuelle Funktionen einsetzen

Mit GlobalCode können auch eigens definierte Funktionen in einer Code-Definition verwendet werden. Für mehr Informationen, lesen Sie hier: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/31457334/Globale+Konfigurationen#GlobalCode.

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

Ohne ein CDATA-Tag muss zum Beispiel der logische UND-Operator als HTML-Entity ausgegeben werden: &. Mit Verwendung des CDATA-Tag kann man lediglich & verwenden, was zu besser lesbarem Code führt.

Wir empfehlen den Einsatz von CDATA-Tags, wenn der Code im Field folgendes enthält:

logische UND-Operatoren &
Vergleichs-Operatoren (<, <=, >, >=), z. B. in Schlaufen
Arrow-Expressions (=>)

Beispiel mit CDATA-Tag und & anstatt &

<FieldsConfiguration>
  <Fields>
  
    <YesNo Name="IsPresident">
      <Code><![CDATA[$("Profile.User.Function") === "President" && !$("Profile.Org.Unit")]]></Code>
    </YesNo>
    
    <YesNo Name="IsPresidentNoCDATA">
      <Code>$("Profile.User.Function") === "President" &amp;&amp; !$("Profile.Org.Unit")</Code>
    </YesNo>
    
  </Fields>
</FieldsConfiguration>