Word: Eintauchen in Fields
- 1 Fields-Dokumentfunktion in Vorlageneditor anhängen
- 2 Einfaches Field konfigurieren und in Vorlage einfügen
- 3 Informationen zu allen Field-Typen
- 4 Typ Text
- 4.1 In Anwendung
- 5 Typ FormattedText
- 6 Typ WordContent
- 7 Builder (Advanced)
- 8 Typ Date
- 9 Typ YesNo
- 9.1 Beispiele
- 10 Typ Picture
- 10.1 Beispiele
- 11 Fields modifizieren
- 11.1 Beispiel
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.
(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:
Beschreibung der Dokumentfunktion: https://primesoft-group.atlassian.net/wiki/x/DYBkAw
Beschreibung zum Erzielen von dynamischen Inhalt mittels JavaScript: https://primesoft-group.atlassian.net/wiki/x/DgC7Fw
Beschreibung des Konzepts https://primesoft-group.atlassian.net/wiki/x/FAC_Fw
Besonders hervorheben möchten wir die Wichtigkeit der folgenden Kapitel:
Beschreibung aller Field-Typen: Felder (Fields) | Elemente
Welcher Field-Typ in welcher Office-Anwendung (Word, Outlook (web), PowerPoint und Excel) eingesetzt werden kann: Felder (Fields) | Übersicht Field Typ pro Office Anwendung
Welcher Field-Typ, welchen Rückgabetyp erfordert: Code | Rückgabewert von Field Typen
Alle primedocs-eigenen Funktionen, die in JS genutzt werden können: Code | primedocs eigene Funktionen
Wie man in JS, auf welche Felder-Art zugreift: Code | Zugriff auf Felder
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
Das Field vom Typ FormattedText erlaubt das Einfügen von formatiertem Text in den folgenden Bereichen:
Globale Übersetzung vom Typ Formatierter Text
Textbaustein vom Typ Formatierter Text
FormattedText kann keine Tabellen, Inhaltsverzeichnisse, Bilder oder andere komplexe Word-Inhalte enthalten. Dazu stehen uns WordContent-Fields zur Verfügung.
Ein FormattedText-Field kann nur einen
FormattedText
zurückgeben.Die Formatierung wird in einer globalen Übersetzung mittels HTML mitgegeben bzw. in einem FormattedText-Textbaustein gespeichert. Somit eignet sich FormattedText, um komplexere Logik mit verschiedenen Word-Styles abzubilden (kommt oft zur Anwendung in Briefköpfen oder für Beilagenlisten).
Die wichtigsten JavaScript-Funktionen:
FormattedText-Fields können ausserdem die Builder API verwenden. Mehr dazu weiter unten: Builder (Advanced).
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
Das Field vom Typ WordContent erlaubt das dynamische Einfügen von mehreren Absätzen in eine Vorlage. Zusammen mit der Dokumentfunktion Forms können so komplexere Vorlagen umgesetzt sowie mehrere Vorlagen in eine konsolidiert werden.
Die Absätze werden entweder in einem Textbaustein vom Typ WordContent gespeichert (siehe Kapitel WordContent Textbaustein abspeichern) oder programmatisch ausgegeben (siehe Builder).
Ein WordContent-Field kann nur
WordContent
zurückgeben.Die Formatierung ist direkt in WordContent-Textbausteinen gespeichert.
Die wichtigsten JavaScript-Funktionen:
WordContent-Fields können ausserdem die Builder API verwenden. Mehr dazu weiter unten: Builder (Advanced).
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
Den Cursor im Textabschnitt an die gewünschte Stelle setzen.
Im primedocs Ribbon auf den Button Textbausteinplatzhalter einfügen klicken.
Den Namen des Platzhalters eingeben und mit Klick auf den Button Einfügen bestätigen.
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:
einen Textbaustein mit den Textbausteinplatzhaltern und mit Schlüssel
Forms-Felder, die später im Textbaustein sein sollen
ein WordContent-Field, das den Textbaustein holt, die Parameter mit den Forms-Feldern befüllt und später in die Vorlage kommt
Vorgehen
Textbaustein vom Typ WordContent erstellen:
Einen Textbausteinplatzhalter einfügen mit Name EventName.
Einen zweiten Textbaustenplatzhalter einfügen mit Name EventDate.
in Word:
Textabschnitt markieren und in der gewünschten Kategorie abspeichern:
als Typ “Word Inhalt”
als Schlüssel setzen wir “Invitation”.
Forms-Felder erstellen in Forms, siehe Dokumentation Formulare (Forms)
ein Text-Feld für
EventName
ein Date-Feld für
EventDate
WordContent-Field erstellen und in der Vorlage platzieren:
Der folgende Code zeigt ein WordContent-Field
InvitationSnippet
.Über die Funktion
getWordContent()
der Snippet API wird der Textbaustein mit SchlüsselInvitation
geholt.Um die Textbausteinplatzhalter mit Inhalt zu füllen, werden die Daten über die Parameter
EventName
undEventDate
mitgegeben. Diese können mit allen Arten von Text gefüllt werden (Fixtext, Forms-Felder, Fields, Benutzerdaten etc.).Füge die vorhin erstellten Forms-Felder in die Parameter ein:
Dem Textbausteinplatzhalter EventName wird das Forms-Feld
Forms.EventName
übergeben.Dem Textbausteinplatzhalter EventDate wird das Forms-Feld
Forms.EventDate
übergeben. Wir nutzen die FunktiongetDateAsString()
, da es sich um ein Datumsfeld handelt, das einDate
zurückgibt - wir aber einenString
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
Das Field
InvitationSnippet
wird dann in der Word-Vorlage über die Schaltfläche Feld binden im Dokument eingefügt und die Vorlage gespeichert.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 FeldHasSignerMain
gibt hiertrue
oderfalse
zurück.Gibt
$("HasSignerMain")
true
zurück, wird geprüft, ob im BenutzerfeldUser.Function
der gleiche Wert steht, wie in der globalen ÜbersetzungStaff.RRFunction
. Ist das der Fall, wirdtrue
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
GlobalField
s, 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