Version: 4.1 (2026-H2)

Felder (Fields)

Ü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.

Grundaufbau

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

Elemente

Attribute, die für alle Elemente angeboten werden:

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

Attributwerte aus globalen Übersetzungen

Einige Attribute können anstelle eines festen Wertes mit dem Wert einer globalen Übersetzung befüllt werden. Diese Attribute werden jeweils mit einem translate- vorangestellt.

Text

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

Attribute für Text

Attributname	Beschreibung
`Value` / `translate-Value` (optional)	Vordefinierter Text oder dynamischer Text aus den globalen Übersetzungen. Nur eines der beiden Attribute darf gesetzt sein.

FormattedText

FormattedText ermöglicht die Einfügung von formatiertem Text. FormattedText ist sowohl ein Typ der globalen Übersetzung als auch ein Snippet-Typ.

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

hinweis

Attribut word-UpdateBehavior

Die Typen FormattedText, WordContent, InlineWordContent und WordTableRows unterstützen das optionale Attribut word-UpdateBehavior. Damit wird gesteuert, ob ein Feld bei einer Aktualisierung in Word (z. B. durch einen Sprach-, Profil- oder Eigenschaftswechsel) mit den aus primedocs berechneten Werten überschrieben werden soll. Standard ist Enabled; zur Deaktivierung Disable setzen. Letzteres sollte nur verwendet werden, wenn die initial generierten Felder direkt vom Benutzer editiert werden sollen (z. B. bei einem Lückentext).

WordContent

Das WordContent-Field ermöglicht die dynamische Einfügung von mehreren Textabschnitten in eine Vorlage. Zusammen mit der Dokumentfunktion Forms können komplexere Vorlagen realisiert oder mehrere Vorlagen zu einer konsolidiert werden.

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

Ein WordContent enthält immer einen oder mehrere Paragraphen und muss daher in der Vorlage auf einem eigenen Paragraphen als Platzhalter hinterlegt werden. Für dynamisch formatierte Ausgaben innerhalb einer Zeile dient der Typ InlineWordContent.

InlineWordContent

Das InlineWordContent-Field ermöglicht das dynamische Einfügen von formatierten Textabschnitten innerhalb eines Paragraphen. Technisch besteht ein InlineWordContent nur aus einem Paragraphen und den Textinhalten (mit oder ohne Formatierung) — damit lassen sich Fix-Texte und formatierte Texte in einem Paragraphen abbilden.

Dieser Typ kann aktuell nur durch das Konvertieren von WordContent oder FormattedText erzeugt werden, wobei die Quelle nur einen Paragraphen enthalten darf.

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

Unterstützt das optionale Attribut word-UpdateBehavior.

WordTableRows

Der WordTableRows-Feldtyp ermöglicht die dynamische Generierung ganzer Tabellenzeilen innerhalb einer bestehenden Tabelle. Felder vom Typ WordTableRows können nur in Word-Dokumenten verwendet werden.

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

Jeder Eintrag des Builders muss genau gleich viele Spalten haben. Der Builder akzeptiert Werte vom Typ string, int, double, FormattedText, WordContent und InlineWordContent. Gibt der JavaScript-Code keine Tabellenzeile zurück, wird die Template-Zeile ausgeblendet (beim Drucken oder PDF-Export ist sie nicht sichtbar).

Unterstützt das optionale Attribut word-UpdateBehavior.

Binding: Um ein WordTableRows-Feld zu binden, müssen Sie genau eine vollständige Tabellenzeile im Editor auswählen. 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
`Format` / `translate-Format` (optional)	Datumsformat für die Anzeige im Dokument.

YesNo

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

Picture

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

Ab primedocs 4.0.30153 kann ein Picture-Feld für Outlook auch über die Base64-Kodierung der Bilddatei definiert werden:

<Picture Name="PictureBase64">
  <Code><![CDATA[
    function main() {
      return {
        Source: "base64:<<base64String>>"
      }
    }
  ]]></Code>
</Picture>

Bild über die Editor-Toolbar einfügen

Der Base64-String muss nicht von Hand erzeugt werden: Die Toolbar des Fields-Editors enthält eine Schaltfläche, über die eine Bilddatei ausgewählt und automatisch als Base64-String in die Konfiguration eingefügt wird.

Bildgrösse festlegen (`HeightInCm` / `WidthInCm`)

Ein Picture-Feld kann statt eines reinen Strings ein Objekt zurückgeben und damit die einzufügende Bildgrösse in Zentimetern vorgeben. (Aktuell nur in PowerPoint; Word folgt.)

<Picture Name="Logo">
  <Code><![CDATA[
    function main() {
      return {
        Source: "base64:<<base64String>>",
        HeightInCm: 2,
        WidthInCm: 5
      };
    }
  ]]></Code>
</Picture>

Ob die angegebenen Masse angewendet werden, hängt vom Bildmodus (PictureMode) des Ziel-Platzhalters ab:

Modus	Verhalten
`Exact`	Das Bild wird in der angegebenen Grösse eingefügt. Mindestens eines von `WidthInCm`/`HeightInCm` muss gesetzt sein; fehlen beide, werden die Originalmasse verwendet.
`Fit`	Das Bild wird in den Platzhalter eingepasst; `WidthInCm`/`HeightInCm` werden ignoriert.

Wird im Modus Exact nur eine Dimension angegeben, wird die andere anhand des Seitenverhältnisses des Bildes proportional berechnet.

Attribute für Picture

Attributname	Beschreibung
`Asset` (optional)	Angabe eines Assets einer Bildergalerie, nur in PowerPoint möglich: `<Picture Name="Mountains" Asset="Bildergalerie/General/Berge.jpg" />`. Das Attribut wird zwar in allen Vorlagentypen angezeigt, ist aber nur in PowerPoint wirksam.

SVG-Bilder

Liefert ein Picture-Feld eine SVG-Grafik, wird diese in Word und PowerPoint als Vektorgrafik eingebettet — mit einem automatisch erzeugten PNG-Fallback für ältere Office-Versionen. Es ist keine zusätzliche Konfiguration nötig; die SVG wird anhand ihres Inhalts erkannt.

Objects und ObjectCollections

Object- bzw. ObjectCollection-Felder können dynamisch über Code definiert werden. Der Zugriff auf Daten über die Datenschnittstelle erfolgt normalerweise über die Forms-Konfiguration. Die Konfiguration als Field ist nur nötig, wenn aufgrund von Benutzereingaben oder Datenübermittlung dynamisch ein oder mehrere Objekte erzeugt werden sollen.

Das Schema-Element definiert alle Daten, die in einer Vorlage verwendet werden können. Der Code muss ein bzw. mehrere JavaScript-Objekte erzeugen, die dem konfigurierten Schema entsprechen.

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

hinweis

Code im Object: main() oder Klammer-Ausdruck

Der Code muss entweder eine function main() enthalten, die das Objekt zurückgibt, oder aus genau einem Ausdruck bestehen.

Abweichend vom JavaScript-Standard werden geschweifte Klammern auf oberster Ebene nicht als Block-Statement, sondern als Objekt interpretiert (primedocs umschliesst sie automatisch mit (…)). Ein direkt notiertes Objektliteral funktioniert daher; bei mehreren Eigenschaften empfiehlt sich aber die explizite Form, um Mehrdeutigkeiten zu vermeiden:

<!-- empfohlen: function main() -->
<Code>function main() { return { Name: "Erika Muster" }; }</Code>

<!-- oder ein einzelner, geklammerter Ausdruck -->
<Code>({ Name: "Erika Muster" })</Code>

GlobalFields

Das GlobalFields-Element kann verwendet werden, um ein global abgelegtes Field abzurufen.

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

Attribute für GlobalFields

Attributname	Beschreibung
`Key` (erforderlich)	Die ID des zu referenzierenden globalen Eintrags.

Felder modifizieren

Das Modifications-Element in GlobalFields ermöglicht die Modifikation eines beliebigen Feldes, das durch die Referenzierung des GlobalField in der Field-Pipeline bei der Dokumentgenerierung einbezogen wird.

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

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

Beispiele

<FieldsConfiguration>
  <Fields>

    <!-- Platzhalter vom Layout befüllen -->
    <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" />
    <!-- Globalen Eintrag referenzieren -->
    <GlobalFields Key="Letters.Subject" />
    <!-- WordContent-Snippet 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>

Grundaufbau​

Elemente​

Attributwerte aus globalen Übersetzungen​

Text​

FormattedText​

WordContent​

InlineWordContent​

WordTableRows​

Date​

YesNo​

Picture​

Bildgrösse festlegen (HeightInCm / WidthInCm)​

Objects und ObjectCollections​

GlobalFields​

Felder modifizieren​

Beispiele​