Version: 4.1 (2026 H2)

Code (JavaScript)

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

Einsatzorte

Die hier beschriebene JavaScript-API steht überall dort zur Verfügung, wo Fields berechnet werden:

Einsatzort	Beschreibung
Fields	`Code`-Element in allen Field-Typen: der Hauptanwendungsfall, inklusive DynamicSnippets.
GlobalCode	Global abgelegte Funktionsbibliotheken zur Verwendung in Fields.
Output Management	`Code` z.B. für dynamische Dateinamen: dieselbe Logik mit vereinfachter API.
Successor Documents	`Code` zur Übergabe von Werten an das Folgedokument.

hinweis

Nicht überall dasselbe $

Der CodeDataProvider (Formulardaten aus JavaScript) und die Initializer der Connect Session Templates verwenden ebenfalls JavaScript-Snippets, stellen aber eine eigene, dort dokumentierte $-API bereit (z.B. $.parameter(…)).

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

Funktionsbibliotheken via "GlobalCode"

Wenn man Funktionen für viele Felder bereitstellen möchte, kann dies über GlobalCode-Konfigurationen zentral gesteuert und verteilt werden.

Weitere Informationen und Beispiele sind in der Globale Konfigurationen-Seite beschrieben.

API-Beschreibung

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

Zugriff auf Felder

Mit $("[Feld]") greift man auf Forms-Felder, Data-Werte aus Connect, Fields, Profilfelder sowie die Dokument- und Vorlagen-Metadaten zu. Folgend ein Beispiel pro Feld-Art:


Forms-Feld	`<Code>$("Forms.Subject")</Code>`
Data-Wert (Data-Schema, per Connect übergeben)	`<Code>$("Data.CaseNumber")</Code>`
Field	`<Code>$("Header")</Code>`
Profil-Feld: Benutzer	`<Code>$("Profile.User.FirstName")</Code>`
Profil-Feld: Organisation	`<Code>$("Profile.Org.Unit")</Code>`
Dokument-Feld	`<Code>$("Document.LanguageLcid")</Code>`
Vorlagen-Metadaten	`<Code>$("Document.Template.VersionLabel")</Code>`

Dokument- und Vorlagen-Metadaten (`Document`)

Analog zu Profile liefert Document die Metadaten der generierten (Root-)Vorlagenversion: z. B. um die Vorlagenversion in der Fusszeile anzudrucken.

Alle Felder sind optional: Nicht ermittelbare Werte bleiben leer und brechen die Generierung nie ab.

Dokumentbezogen

Feld	Inhalt
`Document.LanguageLcid`	LCID der Dokumentsprache (z. B. `2055`).

Vorlagenbezogen (unter Document.Template.*)

Feld	Inhalt
`Document.Template.Id`	GUID der Vorlage.
`Document.Template.LocalizedName`	Anzeigename, lokalisiert für die Dokumentsprache (mit Fallback).
`Document.Template.LocalizedDescription`	Beschreibung, lokalisiert für die Dokumentsprache (mit Fallback).
`Document.Template.Information`	Freitext-Information; nicht sprachabhängig.
`Document.Template.State`	Lifecycle-Status: `Unknown`, `InProgress`, `ReadyForExamination` oder `Released`.
`Document.Template.VersionId`	Interne ID der generierten Version (GUID).
`Document.Template.VersionLabel`	Versions-Label (aus dem Versionierungs-Tab); nicht sprachabhängig.
`Document.Template.VersionPublished`	Ob die generierte Version veröffentlicht ist (`true` / `false`).
`Document.Template.CreatedOnUtc`	Erstellzeitpunkt, ISO 8601 in UTC (z. B. `2026-07-22T08:15:30.0000000Z`).
`Document.Template.CreatedBy`	Login-Name des Erstellers.
`Document.Template.ModifiedOnUtc`	Zeitpunkt der letzten Änderung, ISO 8601 in UTC.
`Document.Template.ModifiedBy`	Login-Name der Person der letzten Änderung.

Beispiel: Vorlagenversion in der Fusszeile andrucken

<FieldsConfiguration>
  <Fields>
    <Text Name="TemplateVersionFooter">
      <Code>$("Document.Template.VersionLabel")</Code>
    </Text>
  </Fields>
</FieldsConfiguration>

Objects und ObjectCollections

Ein Object liefert ein JavaScript-Objekt, dessen Eigenschaften den Feld-Ids im Schema entsprechen; eine ObjectCollection liefert ein Array solcher Objekte. Beide lassen sich mit den üblichen JavaScript-Mitteln verarbeiten.

Auf ein Object zugreifen:

<Text Name="RecipientLine">
  <Code>
    function main() {
      const recipient = $("Forms.Recipient");
      if (recipient === null) {
        return "";
      }
      return `${recipient.FirstName} ${recipient.LastName}, ${recipient.City}`;
    }
  </Code>
</Text>

Durch eine ObjectCollection iterieren:

<Text Name="ParticipantList">
  <Code>
    function main() {
      const participants = $("Forms.Participants");
      const names = [];
      for (const participant of participants) {
        names.push(`${participant.FirstName} ${participant.LastName}`);
      }
      return names.join(", ");
    }
  </Code>
</Text>

Auch Array-Methoden wie filter(), map() oder find() sind möglich; bei Arrow-Functions (=>) den Code in einen CDATA-Tag setzen.

Für die Eigenschaftswerte gilt:

Text → String, YesNo → Boolean, Choice → der gewählte Options-Value als String.
Date → Objekt mit .Value (Datum, z.B. für $.formatDate(…)) und .FormattedValue (formatierter Text).
Verschachtelte Object-/ObjectCollection-Elemente erscheinen als verschachtelte Objekte bzw. Arrays.

Leerzustände: Eine leere ObjectCollection ist ein leeres Array ($("Forms.Participants").length === 0). Ein Object ohne erfasste Werte, ebenso ein nicht ausgewähltes AdditionalProfile, ist null.

Funktionsaufrufe

Weiter leitet $. den Aufruf einer primedocs-eigenen Funktion ein: $.myFunction(). Alle Funktionen sind unter primedocs-eigene Funktionen beschrieben.

Es ist möglich, allgemeine JavaScript-Funktionen zu verwenden (z.B. foreach() auf Arrays (ObjectCollections) oder replace() auf Strings). Mehr Informationen dazu in Mozillas 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`
InlineWordContent	`InlineWordContent`
WordTableRows	`WordTableRows`
Date	`Date`
YesNo	`Boolean`
Picture	Image (z. B. `Profile.Org.Logo`)
Object	JavaScript Objekt, welches dem Schema entspricht.
ObjectCollection	Ein JavaScript Array mit Objekten, welche dem Schema entsprechen.

JavaScript-Fehlermeldungen

Bei der Ausführung eines <Code>-Blocks steht der vollständige Feldpfad im Meldungstext, beispielsweise Error in field "Profile.User.FirstName":. Bei Einträgen einer Collection ergänzt der Pfad den Index in der Form Name[index]. Damit lässt sich das betroffene Feld auch in verschachtelten Objekten zuordnen.

Bei einem falschen Rückgabetyp nennt die Meldung den erwarteten und den tatsächlichen Typ. Für unterstützte Konvertierungen kommt ein Korrekturhinweis hinzu. Weitere Meldungen unterscheiden unter anderem einen fehlenden oder leeren <Code>-Block, einen fehlenden Rückgabewert und einen falschen Funktionsparameter. Die Meldungen sind auch bei deutscher Benutzeroberfläche auf Englisch.

Validieren im Vorlagen-Editor

Die Schaltfläche zum Validieren im Desktop-Vorlagen-Editor prüft über einen anderen Weg als die Ausführung. Dort enthält der Meldungstext noch keinen Feldnamen und kennt den erwarteten Rückgabetyp nicht. Ein Hinweis kann deshalb returns a value statt beispielsweise returns a WordContent nennen. Dieselbe Einschränkung gilt für die Code-Validierung durch Copilot.

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

Template Literals

Zeichenketten lassen sich mit Template Literals (Template Strings) zusammensetzen: Der Text steht in Backticks (`), Ausdrücke werden mit ${…} direkt darin platziert. Das ersetzt die Verkettung mit +.

<Text Name="Anschrift">
  <Code>
    function main() {
      return `${$("Forms.FirstName")} ${$("Forms.LastName")}, ${$("Forms.City")}`;
    }
  </Code>
</Text>

Feldzugriffe innerhalb von ${…} werden von der Abhängigkeitsanalyse erkannt: Das Field wird also korrekt neu berechnet, wenn sich ein referenziertes Feld ändert.
Template Literals sind auch im abgekürzten Aufruf zulässig (<Code>`Hallo ${$("Forms.Name")}`</Code>).
Mehrzeilige Literale sind möglich; die Zeilenumbrüche bleiben im Resultat erhalten.

hinweis

Enthält der Code <, > oder &, muss er in einen CDATA-Tag gesetzt werden: Das gilt unabhängig von Template Literals.

primedocs-eigene Funktionen

Eine Funktion setzt sich immer zusammen aus [API].[Funktion] (z.B. $.translations.getText(…)). Die Funktionen gliedern sich in folgende Gruppen:

Gruppe	Zweck
Getters: `$(…)`, `$.get…(…)`	Felder und deren Werte holen.
Formatieren und Zusammenfügen: `$.formatDate(…)`, `$.formatNumber(…)`, `$.joinNonEmpty(…)`	Werte formatieren und verketten.
translations API: `$.translations.…`	Globale Übersetzungen holen.
snippets API: `$.snippets.…`	Snippets (Textbausteine) holen.
Konvertierungen: `$.formattedText.…`, `$.wordContent.…`, `$.inlineWordContent.…`	Inhalte zwischen den Typen `Text`, `FormattedText`, `WordContent` und `InlineWordContent` konvertieren.
Builder API: `$.….getBuilder()`	Inhalte und Tabellenzeilen baukastenartig zusammensetzen.

Funktionen mit benannten Parametern

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

Getters

Getters holen ein Feld bzw. dessen Wert: implizit über $("…") oder explizit typisiert über $.get…("…") (siehe Zugriff auf Felder).

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 `$("Profile.User.FirstName")` / `$.get("Forms.Date")`
$.getText(String name)	- Holt einen `Text`. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens. Das Feld muss einen String ausgeben. - Rückgabetyp: `String` `$.getText("Forms.Subject")`
$.getDateAsText(String name)	- Holt ein Datumsfeld und konvertiert es in unformatierten Text. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens. Das Feld muss ein Datum ausgeben. - Rückgabetyp: `String` `$.getDateAsText("Forms.Date")`
$.getDate(String name)	- Holt ein `Date`. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens - Rückgabetyp: `Date` `$.getDate("DateWrittenOut")`
$.getFormattedText(String name)	- Holt einen `FormattedText`. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens - Rückgabetyp: `FormattedText` `$.getFormattedText("OtherFormattedText")`
$.getWordContent(String name)	- Holt ein `WordContent`. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens - Rückgabetyp: `WordContent` `$.getWordContent("OtherWordContent")`
$.getInlineWordContent(String name)	- Holt ein `InlineWordContent`. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens - Rückgabetyp: `InlineWordContent` `$.getInlineWordContent("OtherInlineWordContent")`
$.getWordTableRows(String name)	- Holt ein `WordTableRows`. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens - Rückgabetyp: `WordTableRows` `$.getWordTableRows("OtherWordTableRows")`
$.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")`
$.getReference(String name)	- Holt eine `FieldReference`. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens - Rückgabetyp: `FieldReference` > ℹ️ Info > Eine `FieldReference` kann aktuell nur bei SnippetPlaceholdern verwendet werden.
$.getChoiceLabel(String name)	- Holt das `Label` eines `Choice`-Elements. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens - Rückgabetyp: Text `$.getChoiceLabel("Choice")`
$.getChoiceValue(String name)	- Holt das `Value` eines `Choice`-Elements. - Parameter `name`: Parametertyp: `String`, obligatorisch, Angabe des Feldnamens - Rückgabetyp: Text `$.getChoiceValue("Choice")`

Beispiel getText (explizit und implizit)

<Text Name="FirstName2"><!-- explizit -->
  <Code>$.getText('Profile.User.FirstName')</Code>
</Text>

<Text Name="FirstName1"><!-- implizit -->
  <Code>$('Profile.User.FirstName')</Code>
</Text>

Formatieren und Zusammenfügen

Funktion	Zweck
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"`
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")`
formatNumber(String number, String format)	- Wandelt den `String` an zum gewünschten `format`. - Parameter `number`: String, entweder aus Forms-Feld oder über native JavaScript Werte. - Parameter `format`: String. Gibt das Nummernformat an gemäss dieser Liste: Standard numeric format strings. Im Parameter kann auch eine globale Übersetzungen geholt werden. - Rückgabetyp: `String` `$.formatNumber($("Forms.Price"), "N2")`
formatNumber(String number, Object options)	- Formatiert den `String` unter Berücksichtigung benutzerdefinierter Optionen, welche sich an die .NET Implementierung der NumberFormatInfo richtet. Die Standardkultur-Einstellungen werden übersteuert. - Parameter `number`: String, entweder aus Forms-Feld oder über native JavaScript Werte. - Parameter `options`: Object. Es kann `NumberDecimalDigits`, `NumberGroupSeparator` und `NumberDecimalSeparator` angegeben werden. Es kann auch eine globale Übersetzung geholt werden. - Rückgabetyp: `String` - Beispiel unterhalb der Tabelle.
formatNumber(String number, String format, Object options)	- Formatiert den `String` zum gewünschtem `format` unter Berücksichtigung benutzerdefinierter Optionen, welche sich an die .NET Implementierung der NumberFormatInfo richtet. Dies kann genutzt werden z.B. den `NumberGroupSeparator` explizit zu übersteuern, aber trotzdem die Zahl als Währung zu formatieren. - Parameter `number`: String, entweder aus Forms-Feld oder über native JavaScript Werte. - Parameter `format`: String. Gibt das Nummernformat an gemäss dieser Liste: Standard numeric format strings. Im Parameter kann auch eine globale Übersetzungen geholt werden. - Parameter `options`: Object. Es kann `NumberDecimalDigits`, `NumberGroupSeparator` und `NumberDecimalSeparator` angegeben werden. Es kann auch eine globale Übersetzung geholt werden. - Rückgabetyp: `String` - Beispiel unterhalb der Tabelle.

Beispiel formatNumber(number, options)

$.formatNumber(11500.43243, { NumberDecimalDigits: 2, NumberGroupSeparator: $.translations.getText("Separator"), NumberDecimalSeparator: "-" });
// Resultat: 11*500-43, wenn Separator = *

Beispiel formatNumber(number, format, options)

return $.formatNumber(11500.43243, "N2", { NumberDecimalDigits: 2, NumberGroupSeparator: "*", NumberDecimalSeparator: "-" });
// Resultat: 11*500-43

translations API

Holt Einträge aus den Globalen Übersetzungen.

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), siehe benannte Parameter.
- Rückgabetyp: FormattedText

Beispiel ohne parameters:

$.translations.getFormattedText("ContractTitle")

Beispiel mit parameters:

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

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), siehe benannte Parameter. - 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

Holt Snippets (Textbausteine).

Funktion Zweck

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

> ℹ️ Info
> 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 Snippet mit einem bestimmten Schlüssel.
- Parameter key: Parametertyp: String, obligatorisch, Angabe des Snippet-Schlüssels
- Rückgabetyp: FormattedText

$.snippets.getFormattedText("FooterFTSnippet")

Funktion	Zweck
snippets.getWordContent(String key, Object placeholders)	- Holt ein WordContent-Snippet mit einem bestimmten Schlüssel. - Parameter `key`: obligatorisch, Parametertyp: `String`, Angabe des Snippet-Schlüssels - Parameter `placeholders`: Parametertyp: `Object`, es SnippetPlaceholder gibt, zwingend, Liste von Key-Value-Pairs mit `String`-Values - Rückgabetyp: `WordContent` > ℹ️ Info > 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 Snippet mit einem bestimmten Schlüssel. - Parameter `key`: Parametertyp: `String`, obligatorisch, Angabe des Snippet-Schlüssels - Rückgabetyp: `FormattedText` `$.snippets.getFormattedText("FooterFTSnippet")`

formattedText API

Konvertiert Inhalte in einen FormattedText.

Funktion	Zweck
formattedText.from(Object object)	- Konvertiert einen String zu einem `FormattedText`. - Parameter `text`: String oder Feld, das einen String zurückgibt. - Rückgabetyp: `FormattedText` Beispiel mit einem String: `$.formattedText.from("Ein lustiger Satz.")` Beispiel mit Referenz auf ein Feld: `$.formattedText.from($("Forms.Subject"))`
formattedText.fromText(String text)	- Konvertiert einen String zu einem `FormattedText`. - Parameter `text`: String oder Feld, das einen String zurückgibt. - Rückgabetyp: `FormattedText` 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" });`

wordContent API

Konvertiert Inhalte in ein WordContent.

Funktion	Zweck
wordContent.from(Object object)	- Konvertiert ein Object zu einem `WordContent`. - Parameter `object`: Parametertypen: `FormattedText` oder `Text` - Rückgabetyp; `WordContent` Beispiel mit einem String: `$.wordContent.fromText("Ein lustiger Satz.")` Beispiel mit FormattedText aus Snippet: `$.wordContent.fromFormattedText($.snippets.getFormattedText("Introduction"))`
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 Snippet: `$.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"))`

inlineWordContent API

Konvertiert Inhalte in ein InlineWordContent (genau ein Absatz).

fromWordContent und extractParagraphContentFromWordContent sind dieselbe Funktion, ebenso fromFormattedText und extractParagraphContentFromFormattedText. from(…) erkennt den Typ des Arguments selbst; in der Regel genügt darum $.inlineWordContent.from(…).

Funktion	Zweck
inlineWordContent.from(Object object)	- Konvertiert ein Object zu einem `InlineWordContent`. - Parameter `object`: Parametertypen: `Text` , `FormattedText` oder `WordContent` - Rückgabetyp: `InlineWordContent` Beinhaltet der `FormattedText` oder `WordContent` mehr als einen Paragraph, wird ein Fehler geworfen Beispiel mit Text : `$.inlineWordContent.from("Ein lustiger Satz.")` Beispiel mit FormattedText aus Snippet: `$.inlineWordContent.from($.snippets.getFormattedText("Demo"))` Beispiel mit WordContent aus Snippet: `$.inlineWordContent.from($.snippets.getWordContent("Demo"))`
inlineWordContent.fromText(String text)	- Konvertiert einen String zu einem `InlineWordContent`. - Parameter `text`: String oder Feld, das einen String zurückgibt. - Rückgabetyp: `InlineWordContent` Beispiel mit einem String: `$.inlineWordContent.fromText("Ein lustiger Satz.")` Beispiel mit Referenz auf ein Feld: `$.inlineWordContent.fromText($("Forms.Subject"))`
inlineWordContent.fromFormattedText(FormattedText ft)	- Konvertiert einen FormattedText zu einem `InlineWordContent`. - Parameter `ft`: Parametertyp: `FormattedText`, zwingend. - Rückgabetyp: `InlineWordContent` Beispiel mit FormattedText aus Übersetzung: `$.inlineWordContent.fromFormattedText($.translations.getFormattedText("FormattedTexts.CopyTo"))` Beispiel mit Referenz auf Feld: `$.inlineWordContent.fromFormattedText($("IntroductionFT"))`
inlineWordContent.fromWordContent(WordContent wordContent)	- Konvertiert einen WordContent zu einem `InlineWordContent`. - Parameter `wordContent`: Parametertyp: `WordContent`, zwingend. - Rückgabetyp: `InlineWordContent` Beinhaltet der WordContent mehr als einen Paragraph, wird ein Fehler geworfen. Beispiel mit WordContent aus Snippet: `$.inlineWordContent.fromWordContent($.snippets.getWordContent("Demo"))`
inlineWordContent.extractParagraphContentFromWordContent(WordContent wordContent)	- Konvertiert einen WordContent zu einem InlineWordContent. - Parameter `wordContent`: Parametertyp: `WordContent`, zwingend. - Rückgabetyp: `InlineWordContent` Beinhaltet der WordContent mehr als einen Paragraph, wird ein Fehler geworfen. Beispiel mit WordContent aus Snippet: `$.inlineWordContent.extractParagraphContentFromWordContent($.snippets.getWordContent("Demo"))`
inlineWordContent.extractParagraphContentFromFormattedText(FormattedText ft)	- Konvertiert einen FormattedText zu einem InlineWordContent. - Parameter `formattedText`: Parametertyp: `FormattedText`, zwingend. - Rückgabetyp: `InlineWordContent` Beinhaltet der FormattedText mehr als einen Paragraph, wird ein Fehler geworfen. Beispiel mit FormattedText aus Snippet: `$.inlineWordContent.extractParagraphContentFromFormattedText($.snippets.getFormattedText("Demo"))`

Builder API

Die Builder-API kann in einem FormattedText-, WordContent- oder WordTableRows-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. 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 `InlineWordContent`, `WordContent`, `FormattedText` oder `Text` mit der Funktion `append()` anzuhängen. - Parameter: keine - Rückgabetyp: `WordContent`-Builder-Objekt - Aufruf in einem `WordContent`-Field: `$.wordContent.getBuilder()`
wordTableRows.getBuilder()	- Erstellt ein WordTableRows-Builder-Objekt, um damit Tabellenzeilen mit der Funktion `append()` anzuhängen. - Parameter: Wert für die jeweilige Zelle in der Template-Zeile. Werte vom Typ `string`, `int`, `double`, `FormattedText`, `WordContent`, `InlineWordContent` werden unterstützt. Bei jedem Aufruf von `append()` auf demselben Builder-Objekt muss die gleiche Anzahl an Parameter mitgegeben werden. - Rückgabetyp: `WordTableRows`-Builder-Objekt - Aufruf in einem `WordTableRows`-Field: `$.wordTableRows.getBuilder()`
append(InlineWordContent/WordContent/FormattedText/Text content)	- Hängt den Inhalt von Parameter `content` in die Builder-Pipeline. - Parameter `content`: zwingend, Parametertyp `InlineWordContent`, `WordContent`, `FormattedText` oder `Text`, 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"))`
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 Snippet 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. Mehr Informationen dazu unter Globale Konfigurationen.

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>

Einsatzorte​

Aufrufe in Code​

Abgekürzter Aufruf​

Ausformulierter Aufruf​

Funktionsbibliotheken via "GlobalCode"​

API-Beschreibung​

Zugriff auf Felder​

Dokument- und Vorlagen-Metadaten (Document)​

Objects und ObjectCollections​

Funktionsaufrufe​

Rückgabewert von Field-Typen​

JavaScript-Fehlermeldungen​

Native Funktionen​

Template Literals​

primedocs-eigene Funktionen​

Funktionen mit benannten Parametern​

Getters​

Formatieren und Zusammenfügen​

translations API​

snippets API​

formattedText API​

wordContent API​

inlineWordContent API​

Builder API​

Funktionen​

Anwendung​

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

Individuelle Funktionen einsetzen​

CDATA-Tag​