1 Zweck und Einsatz
2 Grundaufbau
3 Elemente
- - 3.1.1 Attributwerte aus globalen Übersetzungen
- 3.2 Text
  - 3.2.1 Attribute für Text
- 3.3 FormattedText
  - 3.3.1 Attribute für FormattedText
- 3.4 WordContent
  - 3.4.1 Attribute für WordContent
- 3.5 InlineWordContent
  - 3.5.1 Attribute für InlineWordContent
- 3.6 WordTableRows
  - 3.6.1 Attribute für WordTableRows
  - 3.6.2 Binding
- 3.7 Date
  - 3.7.1 Attribute für Date
- 3.8 YesNo
  - 3.8.1 Attribute für YesNo
- 3.9 Picture
  - 3.9.1 Attribute für Picture
- 3.10 Objects und ObjectCollections
  - 3.10.1 Inhalte für Object bzw. ObjectCollection
- 3.11 GlobalFields
  - 3.11.1 Attribute für GlobalFields
  - 3.11.2 Fields modifizieren
    - 3.11.2.1 Beispiel
4 Beispiele

Zweck und Einsatz

Über diese Dokumentfunktion können Inhalte verknüpft werden, um diese im Dokument zu integrieren.

Angenommen Sie nutzen die Formulare (Forms) Funktion, um ein Datum und einen Titel vom Benutzer abzufragen und möchten diese Daten gemeinsam in einer Fusszeile platzieren.
Dann können Sie über diese Dokumentfunktion das Datumsfeld und das Textfeld in einem Field zusammen ausgeben. So können Sie auch handhaben, was geschieht, wenn nicht beide Forms-Felder vom Benutzer ausgefüllt werden.

Grundaufbau

<FieldsConfiguration>
  <Fields>
    <!-- Formularelemente und Gruppen hier einfügen -->
  </Fields>
</FieldsConfiguration>

Elemente

Attribute, die bei allen Elementen erforderlich sind:

Attributname	Beschreibung

Attributname	Beschreibung
`Name` (erforderlich)	Wird zur Identifikation benötigt. Darf keine Leerzeichen enthalten und muss eindeutig sein.

Attributwerte aus globalen Übersetzungen

Einige Attribute können anstelle eines fixen Wertes mit dem Wert einer globalen Übersetzung befüllt werden. Diesen Attributen ist jeweils ein translate- vorangestellt. Die beiden Attribute schliessen sich gegenseitig aus, es darf also nur ein fixer Wert oder ein übersetzter Wert eingesetzt werden.

Text

<FieldsConfiguration>
  <Fields>
    <Text Name="Page" translate-Value="Content.Page" />
  </Fields>
</FieldsConfiguration>

Attribute für `Text`

Attributname	Beschreibung

Attributname	Beschreibung
`Value` `translate-Value` (optional)	Vordefinierter Text bzw. dynamischer Text aus den Globalen Übersetzungen, den der Benutzer bearbeiten kann. Hinweis: Nur eines der Attribute darf gesetzt werden.

FormattedText

FormattedText erlaubt das Einfügen von formatiertem Text. FormattedText ist sowohl ein Typ von Globalen Übersetzungen als auch eine Art Textbausteine.

Beim Einfügen mittels Globale Übersetzungen ist es möglich, abhängig von Profildaten oder selektierten Daten in Forms, unterschiedlich formatierte Textpassagen in einem Inhaltssteuerelement im Dokument auszugeben. Oft genutzt wird das beispielsweise in Kopf- und Fusszeilen, weil dort oft fette und nicht-fette Styles in einem Inhaltssteuerelement zum Zuge kommen.

Attribute für `FormattedText`

Attributname	Beschreibung

Attributname

Beschreibung

word-UpdateBehavior
(optional)

Mit diesem Attribut kann gesteuert werden, ob ein Feld bei der Aktualisierung (z.B. über ein Sprach-, Profil- oder Eigenschaftswechsel) im Word mit den konfigurieren bzw. berechneten Werten aus primedocs überschrieben werden soll oder nicht.
Standard: Enabled, zur Deaktivierung Disable konfigurieren.

Diese Funktion sollte nur konfiguriert werden, wenn die initial generierten Felder direkt vom Benutzer editiert werden sollen (z.B. bei einem Lückentext).
Eine fehlerhafte Konfiguration kann dann vorliegen, wenn die initiale Dokumentgenerierung zu einem anderen Ergebnis für als eine Aktualisierung in Word.

Die Dynamisierung von Inhalt und Daten wird im Code-Element mit JavaScript und software-eigenen Funktionen ermöglicht. Code | formattedText API

<FieldsConfiguration>
  <Fields>
  
    <!-- FormattedText als globale Übersetzung holen -->
    <FormattedText Name="EnclosuresTitle">
      <Code>$.translations.getFormattedText("FormattedTexts.EnclosuresTitle")</Code>
    </FormattedText>
    
    <!-- FormattedText als Textbaustein holen -->
    <FormattedText Name="SimpleSnippet">
      <Code>$.snippets.getFormattedText("FormattedTexts.SimpleSnippet")</Code>
    </FormattedText>
    
  </Fields>
</FieldsConfiguration>

WordContent

Das Field vom Typ WordContent erlaubt das dynamische Einfügen von mehreren Textabschnitten in eine Vorlage. Zusammen mit der Dokumentfunktion Forms können so komplexere Vorlagen umgesetzt oder mehrere Vorlagen in eine konsolidiert werden.

<FieldsConfiguration>
  <Fields>
    <WordContent Name="Introduction">
      <Code>$.snippets.getWordContent("Introduction")</Code>
    </WordContent>
  </Fields>
</FieldsConfiguration>

Ein WordContent enthält immer ein oder mehrere Paragraphen und muss daher in der Vorlage immer auf einem eigenen Paragraphen als Platzhalter hinterlegt werden. Um dynamisch formatierte Ausgaben innerhalb einer Zeile zu konfigurieren, kann auf den InlineWordContent Typ zurückgegriffen werden.

Attribute für `WordContent`

Attributname	Beschreibung

Attributname

Beschreibung

word-UpdateBehavior
(optional)

Mit diesem Attribut kann gesteuert werden, ob ein Feld bei der Aktualisierung (z.B. über ein Sprach-, Profil- oder Eigenschaftswechsel) im Word mit den konfigurieren bzw. berechneten Werten aus primedocs überschrieben werden soll oder nicht.
Standard: Enabled, zur Deaktivierung Disable konfigurieren.

Diese Funktion sollte nur konfiguriert werden, wenn die initial generierten Felder direkt vom Benutzer editiert werden sollen (z.B. bei einem Lückentext).
Eine fehlerhafte Konfiguration kann dann vorliegen, wenn die initiale Dokumentgenerierung zu einem anderen Ergebnis für als eine Aktualisierung in Word.

Das Einfügen von WordContent wird im Code-Element mit JavaScript und software-eigenen Funktionen ermöglicht. Code | wordContent API

InlineWordContent

Das Field vom Typ InlineWordContent erlaubt das dynamische Einfügen von formatierten Textabschnitten innerhalb eines Paragraphen in einer Vorlage.

Ein InlineWordContent besteht technisch nur aus einem Paragraphen und den Textinhalten (mit oder ohne Formatierung). Über diesen Typen ist es möglich sowohl Fix-Texte als auch formatierte Texte in einem Paragraph abzubilden.

Dieser Typ kann aktuell nur über das Konvertieren von WordContent oder FormattedText erzeugt werden, wobei hierbei sichergestellt sein muss, dass nur die Quelle nur einen Paragraph beinhaltet.

<FieldsConfiguration>
  <Fields>
    <InlineWordContent Name="Note">
      <Code>$.inlineWordContent.extractParagraphContentFromWordContent($.snippets.getWordContent("Note"))</Code>
    </InlineWordContent>
  </Fields>
</FieldsConfiguration>

Attribute für `InlineWordContent`

Attributname	Beschreibung

Attributname

Beschreibung

word-UpdateBehavior
(optional)

Mit diesem Attribut kann gesteuert werden, ob ein Feld bei der Aktualisierung (z.B. über ein Sprach-, Profil- oder Eigenschaftswechsel) im Word mit den konfigurieren bzw. berechneten Werten aus primedocs überschrieben werden soll oder nicht.
Standard: Enabled, zur Deaktivierung Disable konfigurieren.

Diese Funktion sollte nur konfiguriert werden, wenn die initial generierten Felder direkt vom Benutzer editiert werden sollen (z.B. bei einem Lückentext).
Eine fehlerhafte Konfiguration kann dann vorliegen, wenn die initiale Dokumentgenerierung zu einem anderen Ergebnis für als eine Aktualisierung in Word.

Das Einfügen von InlineWordContent wird im Code-Element mit JavaScript und software-eigenen Funktionen ermöglicht. Code | inlineWordContent API

WordTableRows

Das Field vom Typ WordTableRows ermöglicht das dynamische Generieren von ganzen Tabellenzeilen innerhalb einer bestehenden Tabelle. Fields vom Typ WordTableRows können nur in Word Dokumenten verwendet werden. Jeder Eintrag beim Builder muss genau gleich viele Spalten haben. Der Builder kann Werte vom Typ string, int, double, FormattedText, WordContent, InlineWordContent entgegen nehmen.

Gibt der Javascript-Code im Field keine Tabellenzeile zurück, wird die Template‑Zeile ausgeblendet. Beim Drucken oder PDF‑Export sind diese nicht sichtbar.

<FieldsConfiguration>
  <Fields>
    <WordTableRows Name="TableRow">
      <Code><![CDATA[
        function main() {
          const builder = $.wordTableRows.getBuilder();
          const participants = $("Forms.Participants");
          
          for (const participant of participants) {
            builder.append(
              participant.FirstName,
              participant.LastName              
            );
          }
          
          return builder.build();
        }
      ]]></Code>
    </WordTableRows>
  </Fields>
</FieldsConfiguration>

Attribute für WordTableRows

Attributname	Beschreibung

Attributname

Beschreibung

word-UpdateBehavior
(optional)

Mit diesem Attribut kann gesteuert werden, ob ein Feld bei der Aktualisierung (z.B. über ein Sprach-, Profil- oder Eigenschaftswechsel) im Word mit den konfigurieren bzw. berechneten Werten aus primedocs überschrieben werden soll oder nicht.
Standard: Enabled, zur Deaktivierung Disable konfigurieren.

Diese Funktion sollte nur konfiguriert werden, wenn die initial generierten Felder direkt vom Benutzer editiert werden sollen (z.B. bei einem Lückentext).
Eine fehlerhafte Konfiguration kann dann vorliegen, wenn die initiale Dokumentgenerierung zu einem anderen Ergebnis für als eine Aktualisierung in Word.

Binding

Um ein WordTableRows Field zu binden, muss im Editor genau eine ganze Tabellenzeile markiert werden. Diese Zeile dient als Template‑Zeile für alle generierten Einträge.

Date

<FieldsConfiguration>
  <Fields>
    <Date Name="CreateDate" Format="yyyy-MM-dd">
      <Code>$("Forms.Date").Value</Code>
    </Date>
  </Fields>
</FieldsConfiguration>

Attribute für `Date`

Attributname	Beschreibung

Attributname	Beschreibung
`Format` `translate-Format` (optional)	Datumsformat für die Anzeige im Dokument. Der Tooltip zu `Format` zeigt eine Liste von möglichen Platzhalter für die Zeiteinheiten. Über `translate-Format` kann auf eine Formatierung aus den Globalen Übersetzungen zugegriffen werden. Hinweis: Nur eines der Attribute darf gesetzt werden.

YesNo

<FieldsConfiguration>
  <Fields>
    <YesNo Name="InsertPartnerLogo" Value="true" />
  </Fields>
</FieldsConfiguration>

Attribute für `YesNo`

Attributname	Beschreibung

Attributname	Beschreibung
`Value` (optional)	Vordefinierter Wert des Eintrags, den der Benutzer bearbeiten kann.

Picture

<FieldsConfiguration>
  <Fields>
    <Picture Name="PartnerLogo">
      <Code>$("Profile.Org.PartnerLogo")</Code>
    </Picture>
  </Fields>
</FieldsConfiguration>

Attribute für `Picture`

Attributname	Beschreibung

Attributname	Beschreibung
`Asset` (optional)	Angabe eines Asset einer Bildergalerie, nur möglich in PowerPoint: `<Picture Name="Mountains" Asset="Bildergalerie/General/Berge.jpg" />` Das `Asset`-Attribut wird zwar in allen anderen Vorlagentypen auch angezeigt, es kann aber nicht verwendet werden.

Objects und ObjectCollections

Object bzw. ObjectCollection s können auch dynamisch über Code definiert werden.

Wenn Sie auf Daten über die Datenschnittstelle zugreifen möchten, geht dies über die Formulare (Forms)-Konfiguration.
Die Konfiguration als Feld (Field) ist nur nötig, wenn aufgrund von Benutzereingaben oder Datenübermittelung dynamisch ein neues Objekt bzw. Objekte erzeugt werden sollen.

Inhalte für `Object` bzw. `ObjectCollection`

Elementname	Beschreibung

Elementname	Beschreibung
`Schema`	Definiert alle benötigten Daten, die schlussendlich in einer Vorlage verwendet können sollen.

Der Code muss ein bzw. mehrere JavaScript-Objekt erzeugen, welches dem konfigurierten Schema entsprechen.

Beispiel:

<FieldsConfiguration>
  <Fields>
    <ObjectCollection Name="Recipients">
      <Code><![CDATA[
        [
          { Name: "Erika Muster", Address: "Erika Muster\nMusterstrasse 123\n8360 Eschlikon TG" },
          { Name: "Max Mustermann", Address: "Bernhard Mustermann\nMusterweg 24\n6340 Baar" },
        ]
      ]]>
      </Code>
      <Schema>
        <Text Name="Name" />
        <Text Name="Address" />
      </Schema>
    </ObjectCollection>

    <Object Name="Recipient">
      <Schema>
        <Text Name="Name" />
        <Text Name="Address" />
      </Schema>
        <Code><![CDATA[
            function main() {
               return { Name: "Erika Muster", Address: "Erika Muster\nMusterstrasse 123\n8360 Eschlikon TG" }
            }
          ]]></Code>
    </Object>
  </Fields>
</FieldsConfiguration>

GlobalFields

Über das Element GlobalFields kann ein global abgelegtes Field geholt werden.

<FieldsConfiguration>
  <Fields>
    <GlobalFields Key="Fields.Report" />
  </Fields>
</FieldsConfiguration>

Dabei können GlobalFields in jeder Fields-Konfiguration - in einer Vorlage oder in einem Eintrag in der globalen Konfiguration - referenziert werden.

Mehr Informationen zu den Globalen Konfigurationen sind hier zu finden: Globale Konfigurationen | Umgang mit typisierten Feldern.

Ein konkretes Beispiel zum Erkennen des Zusammenhangs zwischen dem globalen Eintrag und der Referenz auf einen globalen Eintrag gibt es hier: Globale Konfigurationen | Globale Einträge in den Vorlagen referenzieren.

Attribute für `GlobalFields`

Die Referenz auf einen globalen Eintrag passiert mittels dem Key-Attribut. Wählt man dieses aus, wird einem automatisch eine Liste mit allen zur Verfügung stehenden globalen Einträgen angezeigt.

Attributname	Beschreibung

Attributname	Beschreibung
`Key` (erforderlich)	Die ID des globalen Eintrags, der referenziert werden soll.

Fields modifizieren

Das Element Modifications in GlobalFields erlaubt die Modifizierung von jedem Field, das durch die Referenzierung des GlobalField in der Field-Pipeline bei der Dokumentgenerierung inkludiert wird.

Um ein Field zu modifizieren, wird im GlobalField das Modifications-Element eröffnet. Darin wird das zu modifizierende Field mit demselben Name erneut definiert und sein Wert bzw. sein Code anders definiert. So wird bei der Dokumentgenerierung nicht das ursprüngliche Field in die Field-Pipeline inkludiert sondern das modifizierte.

Beispiel

Das GlobalField mit Id Fields.IsPresident enthält ein YesNo-Field mit dem Wert true. Die Konfiguration sieht so aus:

<FieldsGlobalFields>
  <YesNo Name="IsPresident" Value="true" />
</FieldsGlobalFields>

In einer Vorlage soll für das YesNo-Field IsPresident ausnahmsweise false verwendet werden. Um das zu erreichen, wird in der Fields-Konfiguration dieser Vorlage IsPresident neu definiert:

<FieldsConfiguration>
  <Fields>
    
    <GlobalFields Key="Fields.IsPresident">
      <Modifications>
        <YesNo Name="IsPresident" Value="false" />
      </Modifications>
    </GlobalFields>
    
  </Fields>
</FieldsConfiguration>

Wird aus der Vorlage ein Dokument generiert, wird nun die neue Definition berücksichtigt und damit der Wert false verwendet - auch falls dieses Field in anderen Fields referenziert wird.

Beispiele

<FieldsConfiguration>
  <Fields>
  
    <!-- Platzhalter befüllen vom Layout -->
    <Picture Name="PartnerLogo" Asset="Bildergalerie/General/Berge.jpg" />
    <Text Name="Page" Value="Seite" />
    <!-- FormattedText holen -->
    <FormattedText Name="Title">
      <Code>$.translations.getFormattedText("FormattedTexts.FormattedTitle")</Code>
    </FormattedText>
    
    <!-- Daten im Inhalt der Vorlage -->
    <Text Name="Greeting" translate-Value="Greetings.KindRegards1" />
    <!-- Globaler Eintrag referenzieren -->
    <GlobalFields Key="Letters.Subject" />
    <!-- WordContent-Textbaustein holen -->
    <WordContent Name="Introduction">
      <Code>$.snippets.getWordContent("Introduction")</Code>
    </WordContent>
    
    <WordTableRows Name="ParticipantTableRows">
      <Code><![CDATA[
        function main() {
          const builder = $.wordTableRows.getBuilder();
          const participants = $("Forms.Participants");
          
          for (const participant of participants) {			
            const name = $.formattedText.parse("<p>{{FirstName}} <b>{{LastName}}</b></p>", { FirstName: participant.FirstName, LastName: participant.LastName });
            builder.append(
              name,
              $.snippets.getWordContent("Participant_Description", { Description: participant.Description })
            );
          }
          
          return builder.build();
        }
      ]]></Code>
    </WordTableRows>
    
  </Fields>
</FieldsConfiguration>

Felder (Fields)

Zweck und Einsatz

Grundaufbau

Elemente

Attributwerte aus globalen Übersetzungen

Text

Attribute für Text

FormattedText

Attribute für FormattedText

WordContent

Attribute für WordContent

InlineWordContent

Attribute für InlineWordContent

WordTableRows

Attribute für WordTableRows

Binding

Date

Attribute für Date

YesNo

Attribute für YesNo

Picture

Attribute für Picture

Objects und ObjectCollections

Inhalte für Object bzw. ObjectCollection

GlobalFields

Attribute für GlobalFields

Fields modifizieren

Beispiel

Beispiele

Attribute für `Text`

Attribute für `FormattedText`

Attribute für `WordContent`

Attribute für `InlineWordContent`

Attribute für `Date`

Attribute für `YesNo`

Attribute für `Picture`

Inhalte für `Object` bzw. `ObjectCollection`

Attribute für `GlobalFields`