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.
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 inmain
definiert werden.Das
return
Statement inmain
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 |
|
Field |
|
Profil-Feld: Benutzer |
|
Profil-Feld: Organisation |
|
Funktionsaufrufe
Weiter leitet $.
den Aufruf einer primedocs-eigenen Funktionen ein: $.myFunction()
Es ist möglich, allgemeine JavaScript-Funktionen zu verwenden (z.B. foreach()
auf Array
s (ObjectCollections) oder replace()
auf String
s). 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 |
|
FormattedText |
|
WordContent |
|
Date |
|
YesNo |
|
Picture | Image (z. B. |
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 |
---|---|---|
$ | 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 |
---|---|---|
| $() | 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:
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>
Funktionen im Detail pro API
Im Folgenden wird jede Funktion detailliert beschrieben:
Funktion | Zweck |
---|---|
getText(String id) |
|
getDateAsText(String id) |
|
joinNonEmpty(String separator, String item1, String item2, […]) |
Mehr Informationen hier: JavaScript in Fields | Funktion joinNonEmpty() |
formatDate(Date date, String format) |
|
formattedText API
Funktion | Zweck |
---|---|
formattedText.fromText(String text) |
Beispiel mit einem String: Beispiel mit Referenz auf ein Feld: |
formattedText.parse(String html, Object parameters) |
Beispiel ohne benannte Parameter: Beispiel mit benannten Parametern: |
formattedText.getBuilder() Siehe Kapitel Builder | Erstellt ein Builder-Objekt, um darauf aufbauend FormattedText oder Text mit der Funktion
|
wordContent API
Funktion | Zweck |
---|---|
wordContent.fromFormattedText(FormattedText ft) |
Beispiel mit FormattedText aus Übersetzung:
Beispiel mit FormattedText aus Textbaustein:
Beispiel mit Referenz auf Feld:
|
wordContent.fromText(String text) |
Beispiel mit einem String:
Beispiel mit Referenz auf ein Feld:
|
wordContent.getBuilder() Siehe Kapitel Builder | Erstellt ein Builder-Objekt, um darauf aufbauend WordContent, FormattedText oder Text mit der Funktion
|
translations API
In der Gruppe translations
gibt es folgende Funktionen:
Funktion | Zweck |
---|---|
translations.getText(String id) |
|
translations.getFormattedText(String id, Object parameters) | Holt eine formatierte Übersetzung aus den globalen Übersetzungen.
Beispiel ohne
Beispiel mit
|
snippets API
In der Gruppe snippets
gibt es folgende Funktionen:
Funktion | Zweck |
---|---|
snippets.getWordContent(String key, Object placeholders) |
SnippetPlaceholder können nur mit Strings gefüllt werden. Beispiel ohne
Beispiel mit
|
snippets.getFormattedText(String key) |
|
Builder API
Die Builder-API kann in einem FormattedText
-Field oder einem WordContent
-Field verwendet werden und ermöglicht das Zusammensetzen von Text
s, FormattedText
s und WordContent
s 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() |
|
wordContent.getBuilder() |
|
append(WordContent/FormattedText content) |
Siehe ausführliches Beispiel weiter unten. |
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 |
---|---|
$(String name) / $.get(String name) |
|
$.getText(String name) |
|
$.getDate(String name) |
|
$.getFormattedText(String name) |
|
$.getWordContent(String name) |
|
$.getYesNo(String name) |
|
$.getObject(String name) |
|
$.getObjectCollection(String name) |
|
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: &
. 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 SchlaufenArrow-Expressions (
=>
)
Beispiel mit CDATA-Tag und &
anstatt &
PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland