Version: 4.1 (2026 H2)

Felder (Fields)

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

Wird beispielsweise über die Formulare (Forms)-Funktion ein Datum und ein Titel vom Benutzer abgefragt, können diese Daten über diese Dokumentfunktion zusammen in einem Field ausgegeben werden — etwa gemeinsam in einer Fusszeile.

hinweis

Nicht jeder Field-Typ kann in jeder Office-Anwendung direkt im Dokument platziert werden — siehe Übersicht: Field-Typ pro Office-Anwendung.

Grundaufbau

<FieldsConfiguration>
  <Fields>
    <!-- Felder 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, im Editor genau eine vollständige Tabellenzeile 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>

Ein Picture-Field kann auch über einen Base64-String befüllt werden. Der String muss dabei mit dem Präfix base64: beginnen.

<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 XML-Editors (Vorlageneditor, Desktop) enthält die Schaltfläche «Bild als Base64 einfügen». Sie öffnet einen Dateiauswahl-Dialog (Formate BMP, GIF, JPG/JPEG, PNG, TIF/TIFF; max. 50 MB) und fügt an der Cursor-Position den fertigen base64:…-String ein.

Eingefügt wird nur der String — der Cursor muss also innerhalb des Source-Werts stehen; es wird kein vollständiges Picture-Element erzeugt. SVG wird vom Dateidialog nicht angeboten (im Picture-Field ist SVG davon unabhängig weiterhin nutzbar).

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 des Ziel-Shapes ab. Dieser wird in PowerPoint über das Shape-Tag PRIMEDOCS.PICTUREMODE gesetzt (siehe Bildmodus (PRIMEDOCS.PICTUREMODE)) und nicht in der Field-Konfiguration:

Wert	Verhalten
`Exact`	Das Bild wird in der angegebenen Grösse eingefügt. Mindestens eines von `WidthInCm`/`HeightInCm` muss gesetzt sein.
`Fit`	Das Bild wird in das Shape eingepasst; `WidthInCm`/`HeightInCm` werden ignoriert.
(kein Tag)	PowerPoint-Standardverhalten (das Bild wird in die Shape-Dimensionen gestreckt); `WidthInCm`/`HeightInCm` werden ignoriert.

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

Bildmodus (`PRIMEDOCS.PICTUREMODE`)

Der Bildmodus ist kein Attribut der Field- oder Platzhalterdefinition, sondern ein Tag am PowerPoint-Shape (verwaltet über das PowerPoint-Add-In). Er steuert, wie ein an dieses Shape gebundenes Picture eingepasst wird:

Fit — Das Bild wird unter Beibehaltung des Seitenverhältnisses in die Shape-Dimensionen eingepasst; WidthInCm/HeightInCm des Picture-Felds werden ignoriert.
Exact — Das Bild wird in den exakten Massen aus WidthInCm/HeightInCm eingefügt; eine fehlende Dimension wird seitenverhältnistreu berechnet.
(kein Tag) — PowerPoint-Standardverhalten (Stretch). Es gibt keinen Default-Modus.

Bildausrichtung (`PRIMEDOCS.PICTUREANCHOR`)

Wie der Bildmodus ist die Bildausrichtung ein Tag am PowerPoint-Shape (verwaltet über das PowerPoint-Add-In). Sie legt fest, an welcher Stelle des ursprünglichen Shape-Rahmens das Bild ausgerichtet wird — relevant immer dann, wenn das eingepasste Bild kleiner ausfällt als das Shape.

Wert	Ausrichtung im ursprünglichen Shape-Rahmen
`TopLeft`	oben links
`TopRight`	oben rechts
`BottomLeft`	unten links
`BottomRight`	unten rechts
`Center`	zentriert
(kein Tag)	zentriert — `Center` ist der Default

hinweis

Die Bildausrichtung wirkt nur, wenn am Shape auch PRIMEDOCS.PICTUREMODE gesetzt ist. Ohne Bildmodus greift das PowerPoint-Standardverhalten und das Tag bleibt ohne Wirkung. Ein nicht unterstützter Wert führt zu einer Warnung; ausgerichtet wird dann auf Center.

Beide Tags — Bildmodus und Bildausrichtung — greifen ab Version 4.0.30171.0 auch auf dem Folienmaster.

Zusätzlich zur Ausrichtung kann das Picture-Feld das Bild verschieben, über PowerPointOffsetXInCm und PowerPointOffsetYInCm in Zentimetern. Positive Werte verschieben nach rechts bzw. nach unten, negative nach links bzw. nach oben. Die Verschiebung wird nach der Ausrichtung angewendet und ist — wie WidthInCm/HeightInCm — nur in PowerPoint-Vorlagen zulässig.

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

Wird ein Bild mit gesetztem Bildmodus gebunden, entfernt primedocs am Ziel-Shape zudem Rahmen sowie Schatten- und 3D-Effekte, damit nur das Bild sichtbar bleibt.

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

Picture-Felder unterstützen auch SVG-Grafiken (Vektorlogos, Icons). Das Format wird automatisch anhand des Inhalts erkannt — eine zusätzliche Konfiguration ist nicht nötig.

PowerPoint: Einbettung als Vektorgrafik, mit automatisch erzeugtem PNG-Fallback für ältere Office-Versionen.
Word und Excel: Die SVG wird vor dem Einbetten in ein PNG umgewandelt (gerastert).
In der Web-App und im Desktop-Client wird die SVG in der Vorschau direkt dargestellt.

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.

DynamicSnippet

Ein DynamicSnippet ist ein dynamischer Textbaustein. Anders als die übrigen Field-Typen wird er nicht an einer festen Stelle im Dokument platziert: Er wird bei der Dokumentgenerierung ausgewertet und dem Benutzer anschliessend im Snippet-Bereich (Gruppe «Dynamische Textbausteine») sowie – optional – als AutoText zum Einfügen angeboten.

Damit lassen sich Bausteine bereitstellen, die vom vollen Datenkontext des Dokuments abhängen (Formulareingaben, Profil, Sprache) und sich bei einem Formular-, Profil- oder Sprachwechsel automatisch aktualisieren.

<FieldsConfiguration>
  <Fields>
    <DynamicSnippet translate-Name="Texts.Currency" AutoTextName="Waehrung">
      <Code>function main() { return $.formattedText.parse("<p><b>{{t}}</b></p>", { t: $("Forms.Currency") }); }</Code>
    </DynamicSnippet>
  </Fields>
</FieldsConfiguration>

hinweis

DynamicSnippets stehen nur in Word zur Verfügung. Sie können nicht im Dokument gebunden und nicht über $() von anderen Fields referenziert werden — die Verwendung erfolgt ausschliesslich über den Snippet-Bereich bzw. AutoText.

Rückgabewert des `Code`-Blocks

Der Inhaltstyp wird zur Laufzeit aus dem Rückgabewert bestimmt:

Rückgabewert	Ergebnis
`string`	Unformatierter Text
`FormattedText`	Formatierter Text
`WordContent`	Word-Inhalt
`null`	Der Baustein wird vollständig unterdrückt (erscheint weder im Snippet-Bereich noch als AutoText).

Statt des reinen Inhalts kann auch ein Objekt zurückgegeben werden, um Inhalt und Metadaten dynamisch zu setzen. Content ist erforderlich (String, FormattedText, WordContent oder null); die übrigen Eigenschaften sind optional und überschreiben die entsprechenden Attribute:

<DynamicSnippet Name="Introduction">
  <Code><![CDATA[
    function main() {
      return {
        Content: $.snippets.getWordContent("Introduction"),
        Name: "Einleitung",
        Description: "Standard-Einleitung",
        SearchKeywords: "intro einleitung",
        AutoTextName: "intro"
      };
    }
  ]]></Code>
</DynamicSnippet>

Attribute für `DynamicSnippet`

Attributname	Beschreibung
`Name` (optional)	Feldname und Anzeigename im Snippet-Bereich. Optional, wenn `translate-Name` gesetzt ist.
`translate-Name` (optional)	Übersetzungsschlüssel für den Anzeigenamen im Snippet-Bereich.
`Description` / `translate-Description` (optional)	Beschreibung im Snippet-Bereich. `translate-Description` hat Vorrang, wenn beide gesetzt sind.
`SearchKeywords` / `translate-SearchKeywords` (optional)	Suchbegriffe für die Snippet-Suche. `translate-SearchKeywords` hat Vorrang, wenn beide gesetzt sind.
`AutoTextName` (optional, max. 32 Zeichen)	Wenn gesetzt, wird der Baustein zusätzlich als AutoText bereitgestellt (siehe unten).

Verwendung als AutoText

Ist AutoTextName gesetzt, kann der Benutzer den Baustein per AutoText einfügen: den Namen im Dokument eintippen und die AutoText-Tastenkombination drücken. Die Tastenkombination (Standard Ctrl+F3) wird in der Datasource-Einstellung «Hotkey for Snippet Auto Texts» festgelegt.

Ein DynamicSnippet kann auch global abgelegt und über GlobalFields referenziert werden.

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

Bildmodus (PRIMEDOCS.PICTUREMODE)​

Bildausrichtung (PRIMEDOCS.PICTUREANCHOR)​

Objects und ObjectCollections​

GlobalFields​

Felder modifizieren​

DynamicSnippet​

Rückgabewert des Code-Blocks​

Attribute für DynamicSnippet​

Verwendung als AutoText​

Beispiele​

Grundaufbau

Elemente

Attributwerte aus globalen Übersetzungen

Text

FormattedText

WordContent

InlineWordContent

WordTableRows

Date

YesNo

Picture

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

Bildmodus (`PRIMEDOCS.PICTUREMODE`)

Bildausrichtung (`PRIMEDOCS.PICTUREANCHOR`)

Objects und ObjectCollections

GlobalFields

Felder modifizieren

DynamicSnippet

Rückgabewert des `Code`-Blocks

Attribute für `DynamicSnippet`

Verwendung als AutoText

Beispiele