Word: Eintauchen in Fields

Owned by Dinah Bolli (Unlicensed)
Last updated: Sep 13, 2024Version comment
18 min read

Diese Seite führt in die Dokumentfunktion Felder (Fields) ein.

Fields bieten die Möglichkeit, abhängig vom gewählten Profil, dessen Organisationsdaten, von Forms-Feldern und mehr, eine Vorlage dynamisch zu machen.

Der Einfachheit halber und um Missverständnisse vorzubeugen, wird immer von Fields gesprochen.

HINWEIS
Diese Seite gilt als Ergänzung der technischen Dokumentation. Sie erklärt, wie man etwas macht und bietet detailliertere und erklärte Beispiele als die technische Dokumentation.
Im Gegenteil dazu erklärt die technische Dokumentation, wie etwas ist.

Zum besseren Verständnis empfehlen wir daher, weiterführenden Links zu folgen und die entsprechenden Abschnitte zu lesen.

Fields-Dokumentfunktion in Vorlageneditor anhängen

Die Fields bzw. Felder-Dokumentfunktion wird im Vorlageneditor hinzugefügt mittels Klick auf Dokumentfunktionen → Verwalten → + Hinzufügen beim Eintrag Felder.

Die Standardkonfiguration zeigt ein paar Beispiel-Fields:

<FieldsConfiguration> <Fields> <Text Name="Field01" Value="Content of Field01" /> <Text Name="Field02" Value="Content of Field02" /> <Text Name="Field03"> <Code> "[" + $("Field01") + "] [" + $("Field02") + "]" </Code> </Text> </Fields> </FieldsConfiguration>

Diese Text-Fields sollten zum Anfangen gelöscht werden:

Einfaches Field konfigurieren und in Vorlage einfügen

Wir möchten ein Field Greeting, das den Text “Lorem Ipsum” ausgibt, in der Word-Vorlage einfügen:

<FieldsConfiguration> <Fields> <!-- ein Text Field --> <Text Name="Greeting" Value="Lorem Ipsum" /> </Fields> </FieldsConfiguration>

Klicke in der Menüleiste auf den Button Editor oder verwende die Tastenkombination Ctrl+E, um die Vorlage im Word zu öffnen.

In der geöffneten Word-Vorlage, öffne den primedocs Ribbon und klicke anschliessend auf den Button Feld binden.

Dabei öffnet sich das Dialogfenster “Feld auswählen”.

Wähle Greeting aus dem Dropdown aus (in diesem Fall ist Greeting schon vorausgewählt, da es das einzige verfügbare Feld ist).

Klicke auf Einfügen.

Das Feld ist nun eingefügt.

Die Inhaltssteuerelemente von Fields sind blau.

Speichere die Word-Vorlage.

Seit Version 4.0.20093 muss man den Editor nicht mehr schliessen und wieder öffnen, damit man ein neu erstelltes Field binden kann! Das neu erstellte Field muss lediglich im Editor gespeichert werden, damit es im “Feld auswählen”-Dialog erscheint.

Kehren Sie zum Vorlageneditor zurück und klicken Sie auf “Dokument testen“ oder nutzen Sie Ctrl+T. Füllen Sie nun alle Parameter aus, als ob Sie ein Benutzer wären. Das Dokument wird anschliessend im Test-Modus generiert.

(https://primesoft-group.atlassian.net/wiki/spaces/PD/pages/36929537/Word+Vorlagenbearbeitung+-+Grundlagen#Dokument-testen)

Angezeigt wird nun, was wir im Field als Wert hinterlegt haben, der Text “Lorem Ipsum”:

Informationen zu allen Field-Typen

Bevor wir weiter auf die verschiedenen Field-Typen eingehen, empfehlen wir, folgende Seiten der Technischen Dokumentation aufmerksam durchzulesen. Sie bilden die Basis für die Anwendungsbeispiele, die in diesem Kapitel pro Field-Typ folgen:

Besonders hervorheben möchten wir die Wichtigkeit der folgenden Kapitel:

Die folgenden Informationen sind zur Ergänzung:

Typ Text

  • Das Text-Field gibt unformatierten Text aus.

  • Eine JS-Funktion im Text-Field muss den Rückgabewert String haben.

  • Die Formatierung muss man in der Word-Vorlage mittels Styles anwenden - diese wird jedoch für den gesamten Inhalt im Inhaltssteuerelement übernommen.

  • Müssen in einem Field-Inhaltssteuerelement im Word mehrere Styles angezeigt werden, greife auf den Word: Eintauchen in Fields | Typ FormattedTextzu.

  • Siehe die Liste aller primedocs-eigenen Funktionen: Code | primedocs eigene Funktionen.

In Anwendung

JS-Code

<Text Name="Footer"> <Code> function main() { // Felder let profileData = $('Profile.User.FirstName'); // Hole Profildaten (implizit, wie getText()) let field = $.getText('Forms.TextField'); // Hole Forms-Feld (ein Text-Field, explizit mit getText()) let formsField = $.getDateAsString('Forms.Date'); // Hole Forms-Feld (ein Date-Feld) let otherField = $.getText('Page'); // Hole ein anderes Feld (muss in der gleichen Konfig vorhanden sein!) // Translations let translation = $.translations.getText('Texts.Enclosures'); // hole unformatierter Text return $.joinNonEmpty("\n", profileData, field, formsField, otherField, " ", translation); } </Code> </Text> <Text Name="Page" translate-Value="Texts.Page" />

Ergebnis in Word

Typ FormattedText

FormattedTexts als Globale Übersetzung

Der Vorteil von FormattedTexts in den Globalen Übersetzungen ist, dass man keinen Textbaustein erstellen muss sondern den Text mit HTML programmatisch erstellen kann (siehe Beispiele unten).

Beispiel “Footer“

Der FormattedText ist als globale Übersetzung vom Typ “FormattedText” angelegt.

Die Id unseres Beispiels lautet FormattedTexts.FooterBold.

<p></p>: ein Absatz (Paragraph)

<b></b>: fett (bold)

Code

Der Zugriff auf die globale Übersetzung Textbaustein funktioniert so:

Definierter Word-Style

Mit dem Attribut data-word-style-id gibt man an, welchen Style ein Absatz (Paragraph) haben soll. So ist es möglich, mehrere unterschiedlich formatierte Absätze in einem Field auszugeben. Das Attribut kann auch in <span> verwendet werden.

Kontrollstruktur (if)

Eine Kontrollstruktur prüft, ob eine Bedingung erfüllt ist und gibt den Inhalt aus.

Schleife (each)

Eine Schleife geht durch eine Liste und wiederholt den Inhalt für jedes Element in der Liste.

Beispiele

Field “Footer” mit benannten Parametern

Im Übersetzungseintrag kann man Platzhalter bzw. Parameter in Absätzen (<p></p>) erstellen, um diese dann mit Daten zu befüllen. Welche Daten schlussendlich in diesen Platzhaltern angezeigt werden, wird im Field über benannte Parameter mit demselben Namen definiert.

Definition in den Globalen Übersetzungen

Globale Übersetzung mit Id: FormattedTexts.FooterBoldWithParams, mit benannten Parametern

JS-Code

Holt die Übersetzung vom Typ FormattedText. Parameter sind: Snippet-Key und eine Liste von benannten Parametern

Field “ReferenzNr“

Deckt folgende Inhalte ab:

  • Benannte Parameter

  • Definierter Word-Style

  • Kontrollstruktur

Globale Übersetzung mit Id: FormattedTexts.Paragraphs.BoldNormalHeader

Field “ReferenzNr”, das die Übersetzung holt:

Ergebnis in Word

Field “EnclosuresBox”

Deckt folgende Inhalte ab:

  • Definierter Word-Style

  • Kontrollstruktur

  • Schleife

Globale Übersetzung mit Id: FormattedTexts.EnclosuresBox

Field “EnclosuresBox”, das die Übersetzung holt:

Ergebnis in Word

FormattedText als Textbaustein

Wie erwähnt, können Textbausteine vom Typ Formatierter Text keine Tabellen, Bilder oder sonst komplexe Word-Inhalte abspeichern. Daher wird ein FormattedText nur als Textbaustein erstellt und in ein Field geholt, wenn es sich um Absätze mit Text handelt, die einen oder mehrere Styles aufweisen.

Der FormattedText ist als Textbaustein vom Typ “Formatierter Text” abgelegt und hat einen Schlüssel (Key).

Der Key unseres Beispiels lautet FooterFTSnippet.

Code

Der Zugriff auf den Textbaustein funktioniert so:

Typ WordContent

Beispiele

WordContent-Field Introduction

WordContent-Field ContractTitles mit benannten Parametern

Im Textbaustein man Textbausteinplatzhalter bzw. Parameter. Welche Daten schlussendlich in diesen Platzhaltern angezeigt werden, wird im Field über benannte Parameter mit demselben Namen definiert:

WordContent-Textbaustein erstellen

Bevor man ein WordContent-Field erstellen kann, benötigt man einen WordContent-Textbaustein: einen Textbaustein vom Typ Word Inhalt. Die drei wichtigsten Punkte:

  • Um dynamischen Inhalt (Fields, Forms, Profil-Daten) zu hinterlegen, werden Inhaltssteuerelemente, sogenannte Textbausteinplatzhalter, im entsprechenden Absatz eingefügt.

  • WordContent-Textbausteine werden wie alle anderen Textbausteine mittels Drag’n’Drop in die gewünschte Kategorie in der Textbaustein-Leiste abgespeichert.

  • Zur Verwendung in Fields benötigst du einen Schlüssel (Key).

Textbausteinplatzhalter einfügen

Damit in ein WordContent-Textbaustein dynamischer Text (von Fields, Forms-Feldern oder Profil-Daten) eingefügt werden kann, benötigen wir Inhaltssteuerelemente, sogenannte Textbausteinplatzhalter.

Ein Textbausteinplatzhalter kann im Word-Editor einer Vorlage in einen Textabschnitt eingefügt werden, der anschliessend als WordContent-Textbaustein abgespeichert wird.

Vorgehen

  1. Den Cursor im Textabschnitt an die gewünschte Stelle setzen.

  2. Im primedocs Ribbon auf den Button Textbausteinplatzhalter einfügen klicken.

  3. Den Namen des Platzhalters eingeben und mit Klick auf den Button Einfügen bestätigen.

  4. Dann wird ein gelbes Inhaltssteuerelement eingefügt.

WordContent-Textbaustein abspeichern

WordContent-Textbausteine werden wie alle anderen Textbausteine mittels Drag’n’Drop abgespeichert.
Sehe dir die Demo an oder lese die Anleitung mit allen Erklärungen:

Demo

Vorgehen

Öffne die Textbaustein-Leiste mittels Klick auf Textbausteine im primedocs Ribbon.

Markiere den Textabschnitt und ziehe diesen mit gedrückter Maustaste (mittels Drag’n’Drop) in den Ordner Vorlagen-Textbausteine in eine beliebige Kategorie.

Passe nun die Eigenschaften des zu erstellenden Textbausteins an:

  • Der Name wird automatisch generiert. Passe ihn gegebenenfalls an.

  • Wähle den Typ “Word Inhalt” (WordContent).

  • Hinterlege einen Schlüssel (Key).

Bestätige anschliessend mit OK.

Anwendungsbeispiel: Einladung

Eine Abteilung hat mehrere Vorlagen für eine Einladung. Der Einladungstext ist zwar immer gleich, zwei Werte sind jedoch je nach Vorlage unterschiedlich. Daher wird der Text als WordContent-Textbaustein mit Textbausteinplatzhaltern für mehr Flexibilität abgespeichert.

Im erstellten Dokument soll am Schluss der folgende Text angezeigt werden:
Einladung zum Event «[Event]» am [Datum].

Dabei sind Event und Datum dynamische Inhalte, die wir über Forms beim Benutzer abfragen möchten und dann im Text ausgegeben werden sollen.

Für dieses Anwendungsbeispiel benötigen wir:

  1. einen Textbaustein mit den Textbausteinplatzhaltern und mit Schlüssel

  2. Forms-Felder, die später im Textbaustein sein sollen

  3. ein WordContent-Field, das den Textbaustein holt, die Parameter mit den Forms-Feldern befüllt und später in die Vorlage kommt

Vorgehen

  1. Textbaustein vom Typ WordContent erstellen:

    1. Einen Textbausteinplatzhalter einfügen mit Name EventName.

    2. Einen zweiten Textbaustenplatzhalter einfügen mit Name EventDate.

       

    3. in Word:

    4. Textabschnitt markieren und in der gewünschten Kategorie abspeichern:

      1. als Typ “Word Inhalt”

      2. als Schlüssel setzen wir “Invitation”.

  2. Forms-Felder erstellen in Forms, siehe Dokumentation Formulare (Forms)

    1. ein Text-Feld für EventName

    2. ein Date-Feld für EventDate

  3. WordContent-Field erstellen und in der Vorlage platzieren:

    1. Der folgende Code zeigt ein WordContent-Field InvitationSnippet.

    2. Über die Funktion getWordContent() der Snippet API wird der Textbaustein mit Schlüssel Invitation geholt.

    3. Um die Textbausteinplatzhalter mit Inhalt zu füllen, werden die Daten über die Parameter EventName und EventDate mitgegeben. Diese können mit allen Arten von Text gefüllt werden (Fixtext, Forms-Felder, Fields, Benutzerdaten etc.).

    4. Füge die vorhin erstellten Forms-Felder in die Parameter ein:

      1. Dem Textbausteinplatzhalter EventName wird das Forms-Feld Forms.EventName übergeben.

      2. Dem Textbausteinplatzhalter EventDate wird das Forms-Feld Forms.EventDate übergeben. Wir nutzen die Funktion getDateAsString(), da es sich um ein Datumsfeld handelt, das ein Date zurückgibt - wir aber einen String benötigen. Hier mehr Informationen dazu: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/398131214/Code#%C3%9Cbersicht-%C3%BCber-alle-primedocs-eigenen-Funktionen

  4. Das Field InvitationSnippet wird dann in der Word-Vorlage über die Schaltfläche Feld binden im Dokument eingefügt und die Vorlage gespeichert.

  5. Das ist das Ergebnis in Word, wenn man das Dokument testet:

Builder (Advanced)

Der Builder ermöglicht das Zusammensetzen von Texts, FormattedTexts und WordContents im Sinne eines Baukastensystems, wobei die einzelnen Elemente dem Typ des Builder entsprechen müssen. Ein Text kann dazu in FormattedText oder WordContent sowie ein FormattedText in WordContent konvertiert werden.

Die Builder API kann in Fields vom Typ WordContent und FormattedText verwendet werden: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/398131214/Code#Builder-API

FormattedText-Field Footer mit Builder

Ergebnis in Word

FormattedText-Field KopfzeileContact mit Builder

JS-Code

Ergebnis in Word

WordContent-Field KopfzeileContact mit Builder

JS-Code

Ergebnis in Word

Typ Date

Siehe technische Dokumentation: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/56918029/Felder+Fields#Date

Das Datum erscheint in dem Format, das in Forms definiert wurde.

Hier gibt es mehr Informationen: https://primesoft-group.atlassian.net/wiki/spaces/PD/pages/395444225/JavaScript+in+Fields#Datumsfunktionen-und-mit-Daten-rechnen

Typ YesNo

Siehe technische Dokumentation: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/56918029/Felder+Fields#YesNo

Ein Field vom Typ YesNo wird momentan eingesetzt, um eine Logik in mehreren Fields zu verwenden und so den Code übersichtlicher zu gestalten.

Beispiele

Simples Beispiel

In diesem Beispiel wird die folgende Bedingung geprüft: Wenn das Forms-Feld nicht null ist (wenn es also existiert), wird true ausgegeben, sonst false.

Umfangreicheres Beispiel

In diesem Beispiel werden mehrere Bedingungen geprüft:

  • Mit $("HasSignerMain") wird zuerst geprüft, ob es einen Hauptunterzeichnenden gibt; das Feld HasSignerMain gibt hier true oder false zurück.

  • Gibt $("HasSignerMain") true zurück, wird geprüft, ob im Benutzerfeld User.Function der gleiche Wert steht, wie in der globalen Übersetzung Staff.RRFunction. Ist das der Fall, wird true ausgegeben.

  • In allen anderen Fällen, wird false ausgegeben.

Das heisst, SignerIsRegierungsrat gibt true zurück, wenn es sich beim Benutzer, der das Dokument erstellt und der Hauptunterzeichnender ist, um einen Regierungsrat handelt.

Typ Picture

Siehe technische Dokumentation: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/edit-v2/56918029#Picture

Mit Fields vom Typ Picture kann man Bilder in ein Field holen. Dabei gelingt dies auf zwei Arten:

  • über eine Referenz auf Profil- oder Organisationsdaten

  • Über eine Adresse auf eine Datei (Asset)

Beispiele

Unterschriftenbild eines Unterzeichnenden holen

Logo einer Organisation holen

Bild aus den Dateien (Asset) holen

Fields modifizieren

GlobalFields, die man in einer Vorlage oder einem globalen Eintrag referenziert hat, können modifiziert werden. Wir empfehlen, so oft wie nötig und so wenig wie möglich zu modifizieren.

Die technische Dokumentation führt in das Thema ein: https://primesoft-group.atlassian.net/wiki/spaces/PDT/pages/edit-v2/56918029#Fields-modifizieren

Beispiel

Globaler Eintrag Fields.Contract

Die Konfiguration des GlobalField mit Id Fields.Contract enthält mehrere Fields sowie eine Referenz auf ein anderes GlobalField:

Field-Konfiguration in Vorlage

Der globale Eintrag ist in der Inhaltsvorlage in der Fields-Konfiguration referenziert:

Zu diesem Zeitpunkt werden die Felder folgendermassen angezeigt:

Modifizierung

Nun möchte man in dieser spezifischen Vorlage die Felder anders definieren. Dazu werden sie so modifiziert:

Ergebnis

Wird nun erneut ein Dokument erstellt inkludiert primedocs die neuen Definitionen und nicht die ursprünglich referenzierten.

Somit werden in einem erstellten Dokument in den gleichen Fields die neuen Werte angezeigt:

 

PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland