Code


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() 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

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.

primedocs-eigene Funktionen

Es folgt eine sortierbare Tabelle mit allen primedocs-eigenen Funktionen: welcher API sie angehören und dem jeweiligen Rückgabetyp. Eine Funktion setzt sich dann immer zusammen aus [API].[Funktion].

API

Funktion

Rückgabetyp

API

Funktion

Rückgabetyp

$

getDateAsText()

String

$

joinNonEmpty()

String

$

formatDate()

String

$

getDate()

Date

$.formattedText

fromText()

FormattedText

$.formattedText

parse()

FormattedText

$.wordContent

fromFormattedText()

WordContent

$.wordContent

fromText()

WordContent

$.translations

getText()

String

$.translations

getFormattedText()

FormattedText

$.snippets

getFormattedText()

FormattedText

$.snippets

getWordContent()

WordContent

$.formattedText

getBuilder()

FormattedText-Builder

$.wordContent

getBuilder()

WordContent-Builder

Getters

API

Funktion

Rückgabetyp

API

Funktion

Rückgabetyp

 

$()

Feldtyp (je nach Id)

$

get()

Feldtyp (je nach Id)

$

getText()

String

$

getDate()

Date

$

getFormattedText()

FormattedText

$

getWordContent()

WordContent

$

getYesNo()

YesNo

$

getObject()

Object

$

getObjectCollection()

ObjectCollection

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:

  1. Aufruf von Profildaten / Forms-Felder / Fields, siehe unten Key name

  2. Fixtext, siehe unten Key info

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

Funktionen im Detail pro API

Im Folgenden wird jede Funktion detailliert beschrieben:

Funktion

Zweck

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

getDateAsText(String id)

  • Holt ein Datumsfeld mittels id und konvertiert es in unformatierten Text.

  • Parameter id: Feld-Id. Das Feld hinter Id muss ein Datum ausgeben.

  • Rückgabetyp: String

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: JavaScript in Fields | 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")

formattedText API

Funktion

Zweck

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

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

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

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: $.getDateAsText("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

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

Getters

Funktion

Zweck

Funktion

Zweck

$(String name) / $.get(String name)

  • Holt ein Feld gemäss Argument.

  • Parameter name: Parametertyp: String, obligatorisch, Angabe des Feldnamens

  • Rückgabetyp: dem geholten Feld entsprechend

  • siehe auch Code | Zugriff auf Felder

$("Profile.User.FirstName") / $.get("Forms.Date")

$.getText(String name)

  • Holt einen Text.

  • Parameter name: Parametertyp: String, obligatorisch, Angabe des Feldnamens

  • Rückgabetyp: Text

$.getText("Forms.Subject")

$.getDate(String name)

  • Holt ein Date.

  • Parameter name: Parametertyp: String, obligatorisch, Angabe des Feldnamens

  • Rückgabetyp: Text

$.getDate("DateWrittenOut")

$.getFormattedText(String name)

  • Holt einen FormattedText.

  • Parameter name: Parametertyp: String, obligatorisch, Angabe des Feldnamens

  • Rückgabetyp: FormattedText

$.getFormattedText("Forms.Subject")

$.getWordContent(String name)

  • Holt ein WordContent.

  • Parameter name: Parametertyp: String, obligatorisch, Angabe des Feldnamens

  • Rückgabetyp: WordContent

$.getWordContentText("Forms.Subject")

$.getYesNo(String name)

  • Holt ein YesNo.

  • Parameter name: Parametertyp: String, obligatorisch, Angabe des Feldnamens

  • Rückgabetyp: YesNo

$.getYesNo("Confidentiality")

$.getObject(String name)

  • Holt ein Object.

  • Parameter name: Parametertyp: String, obligatorisch, Angabe des Namens eines Feldes

  • Rückgabetyp: Object

$.getObject("SingleRecipient")

$.getObjectCollection(String name)

  • Holt eine ObjectCollection.

  • Parameter name: Parametertyp: String, obligatorisch, Angabe des Feldnamens

  • Rückgabetyp: ObjectCollection

$.getObjectCollection("Participants")


Individuelle Funktionen einsetzen

Mit GlobalCode können auch eigens definierte Funktionen in einer Code-Definition verwendet werden. Für mehr Informationen, lesen Sie hier: 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: &amp;. 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 &amp;

PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland