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

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().
Das return Statement ist explizit.

<Text Name="Footer">
  <Code>
    function main() { 
      let firstName = $.getString('Profile.User.FirstName');
      if (firstName == 'Foo') {
        firstName += 'Bar';
      }
      return firstName;
    }
  </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>`

Zugriff auf Funktionen

Weiter leitet $. die Verwendung einer primedocs-eigenen Funktionen ein: $.myFunction()

Selbstverständlich ist es auch 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.

Field-Rückgabewert

TODO: Gehört hier rein?

Der Rückgabewert 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	Datentyp des Rückgabewerts
Text	`String`
FormattedText	`FormattedText`
WordContent	`WordContent`
Date	`Date`
YesNo	`Boolean`
Picture	Image (z. B. `Profile.Org.Logo`)

Funktionen

Die Verwendung von Funktionen funktioniert gemäss JavaScript-Standards:

die meisten Funktionen erfodern ein oder mehrere Argumente, die mittels Parameter angegeben werden. Die Parameter haben einen Parametertypen.
Jede Funktion hat einen expliziten Rückgabetyp.

Übersicht

Es folgt eine Übersicht in einer sortierbaren Tabelle über alle primedocs-eigenen Funktionen, welcher API sie angehören, dem Ziel-Fieldtyp; in welchem Field-Typ sie zurückgegeben (returned) werden dürfen und dem jeweiligen Rückgabetyp.

API	Funktion	Ziel-Fieldtyp	Rückgabetyp
none	getText()	Text	String
none	getDateAsString()	Text	String
none	joinNonEmpty()	Text	String
formattedText	formattedText.fromText()	FormattedText	FormattedText
wordContent	wordContent.fromFormattedText()	WordContent	WordContent
wordContent	wordContent.fromText()	WordContent	WordContent
translations	translations.getText()	Text	String
translations	translations.getFormattedText()	FormattedText	FormattedText
snippets	snippets.getFormattedText()	FormattedText	FormattedText
snippets	snippets.getWordContent()	WordContent	WordContent
formattedText	formattedText.getBuilder()	FormattedText	FormattedText
wordContent	wordContent.getBuilder()	WordContent	WordContent
builder	append()	Text, FormattedText, WordContent	-
builder	build()	Text, FormattedText, WordContent	-

Funktionen mit benannten Parametern

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

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

Direkter Zugriff auf Profildaten / Forms-Felder / andere Fields (Zugriff mit $("Id")), siehe Key name
Fixtext ("Mein lustiger Text"), siehe Key info
Referenzen auf Variabeln (zuvor definiert mit: let myVariable = "My funny text"), siehe Key function

Im folgenden Beispiel enhält das die Liste 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: XXX

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.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 Stand heute nur Strings erhalten.

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

Der Builder ermöglicht das Zusammensetzen von Texts, FormattedTexts und WordContents im Sinne eines Baukastensystems, indem jeder Text, unabhängig vom Typ, aneinander gereiht wird.

Die Builder-API kann in einem FormattedText-Field oder einem WordContent-Field verwendet werden.

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

Ein Formatted-Field kann nur FormattedText und Text ausgeben.
Ein WordContent kann WordContent, FormattedText und Text ausgeben (also alles).

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: keiner Aufruf auf dem Builder-Objekt: `builder.build();`

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

<FieldsConfiguration>
  <Fields>
  
    <WordContent Name="WCSnippetBuilder">
      <Code>$.wordContent.getBuilder()
            .append($.snippets.getWordContent("Introduction"))
            .append($.wordContent.fromFormattedText($.translations.getFormattedText("FormattedTexts.CopyTo")))
            .append($.wordContent.fromText(" - mit Builder"))
            .build()</Code>
    </WordContent>
    
    <FormattedText Name="FTSnippetBuilder">
      <Code>$.formattedText.getBuilder()
            .append($.snippets.getFormattedText("IntroductionFT"))
            .append($.translations.getFormattedText("FormattedTexts.CopyTo"))
            .append($.formattedText.fromText(" - mit Builder"))
            .build()</Code>
    </FormattedText>
        
  </Fields>
</FieldsConfiguration>

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 & schreiben, kann aber mit einem CDATA-Tag nur & schreiben.

Beispiel mit CDATA-Tag und & anstatt &

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