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.

Die JavaScript-Syntax des Code-Elements und die $-API beschreibt die Seite Code (JavaScript).

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>

Hint

Ein Hint-Field hinterlegt einen Ausfüllhinweis für die Person, die das erzeugte Dokument bearbeitet. Es unterscheidet sich von allen anderen Field-Typen in einem Punkt: Es liefert keinen Wert für das Dokument und ist deshalb nicht über $("Fields.<Name>") abrufbar.

<FieldsConfiguration>
  <Fields>
    <Hint Name="RecipientHint" translate-Value="Hints.Recipient" />
  </Fields>
</FieldsConfiguration>

Attributname	Beschreibung
`Name` (erforderlich)	Bezeichnung des Hinweises. Darüber wird er im Word-Inhaltssteuerelement referenziert.
`Value` (optional)	Fester Hinweistext.
`translate-Value` (optional)	Schlüssel aus den globalen Übersetzungen, z.B. `Hints.Recipient`. Der Hinweis wird damit mehrsprachig und in der Oberflächensprache aufgelöst (siehe unten).

Hinweis in der Vorlage platzieren

Gesetzt wird der Hinweis im Word-Add-In über die Schaltfläche Hinweis einfügen in der Gruppe Vorlagenbearbeitung. Erfasst wird beides im selben Eingabefeld: Beim Tippen schlägt es die hier konfigurierten Hint-Fields vor; ohne gewählten Vorschlag gilt der eingegebene Text. Daraus entstehen zwei Varianten:

Tag im Inhaltssteuerelement	Herkunft des Texts
`primedocs.HintField=[Name]`	Verweist auf ein hier konfiguriertes `Hint`-Field. Über `translate-Value` mehrsprachig.
`primedocs.HintText=[TEXT]`	Fester Text direkt im Tag, ohne Field-Konfiguration und ohne Übersetzung.

Für mehrsprachige Vorlagen ist deshalb HintField die richtige Wahl; HintText eignet sich für einsprachige Fälle und ist die einzige Variante, die auch in einem WordContent-Snippet zulässig ist.

Warum Hint ein eigener Field-Typ ist

Der Hinweistext wird in der Oberflächensprache aufgelöst, nicht in der Dokumentsprache — anders als Feldwerte, die ins Dokument fliessen. Ein Ausfüllhinweis richtet sich an die bearbeitende Person, nicht an das Dokument. Ein Text-Field mit translate-Value leistet das nicht.

Verhalten im erzeugten Dokument

Der Hinweistext wird nicht in das Dokument geschrieben. Beim Generieren wird das Inhaltssteuerelement stattdessen

gegen Bearbeitung gesperrt,
als ausgeblendeter Text markiert (Word-Zeichenformat «Ausgeblendet») und
durch ein ❓ mit dem Text «Hier klicken für weitere Informationen» ersetzt.

Sichtbar ist das nur, solange in Word ausgeblendeter Text eingeblendet wird. Der eigentliche Hinweistext erscheint im Quick Check.

hinweis

Auch der eingesetzte Text «Hier klicken für weitere Informationen» folgt der Oberflächensprache. Für den Hinweis gilt damit durchgehend die Sprache der bearbeitenden Person.

Einschränkungen

Hint-Fields lassen sich nicht über «Feld binden» einfügen: In der Feldauswahl dieser Schaltfläche erscheinen sie nicht.
Verweist primedocs.HintField=[Name] auf einen Namen, der in der Fields-Konfiguration fehlt, bricht die Generierung mit einer Fehlermeldung ab. Dasselbe gilt, wenn der Name auf ein Field eines anderen Typs zeigt.

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. Unterstützt wird das in Word- und PowerPoint-Vorlagen; in allen anderen Vorlagentypen werden die beiden Angaben ignoriert und als Warnung gemeldet.

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

In beiden Formaten gilt dieselbe Zuordnung:

Angabe	Ergebnis
nur `WidthInCm`	Die Höhe wird aus dem Seitenverhältnis des Bildes berechnet.
nur `HeightInCm`	Die Breite wird aus dem Seitenverhältnis des Bildes berechnet.
beide	Das Bild wird auf die exakten Masse gestreckt: Das Seitenverhältnis bleibt nicht erhalten.
keine	Die Zielanwendung bestimmt die Grösse.

Die Angaben sind exakte Zielgrössen und keine Obergrenzen: Ein Quellbild, das kleiner ist als die angegebene Grösse, wird auf diese Grösse hochskaliert.

Gültig sind Werte grösser als 0 und höchstens 200 cm. Werte ausserhalb dieses Bereichs gelten als nicht gesetzt und werden beim Generieren als Warnung gemeldet.

Word

In Word wirken die Masse direkt auf den Bildplatzhalter: Es ist kein zusätzliches Tag nötig. Ohne WidthInCm/HeightInCm behält der Platzhalter die in der Vorlage hinterlegte Grösse. Die Masse gelten auch für SVG-Bilder.

Sind beide Masse gesetzt, hebt primedocs am eingefügten Bild die Sperre des Seitenverhältnisses auf. Ohne diesen Schritt würde Word die Breite aus der Höhe neu berechnen und die angegebene Breite verwerfen.

Lässt sich die zweite Dimension aus dem Seitenverhältnis nicht innerhalb des gültigen Bereichs berechnen, etwa bei extrem schmalen Bildern, bleibt die Grösse ganz unverändert, mit einer Warnung beim Generieren. Kann primedocs das Seitenverhältnis des Bildes nicht lesen, wird die zweite Dimension aus den Proportionen des Platzhalters abgeleitet, ebenfalls mit einer Warnung.

Das eingefügte Bild ist normaler Dokumentinhalt: Es lässt sich anklicken und bearbeiten, und es hängt nicht an einer laufenden Datenbindung von Word. Wird das Profil in einem offenen Dokument gewechselt, tauscht das Add-In das Bild selbst aus und wendet die im Feld definierte Grösse erneut an.

PowerPoint

In PowerPoint hängt es vom Bildmodus des Ziel-Shapes ab, ob die Masse angewendet werden. Dieser wird ü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.

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, anders als 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.

Word und PowerPoint: Einbettung als Vektorgrafik, zusammen mit einem automatisch erzeugten PNG-Fallback. Office ab 2019 zeigt die Vektorgrafik, ältere Versionen den Fallback. In Word wird die SVG nur in Sonderfällen gerastert: beim Aktualisieren eines bereits geöffneten Dokuments über das Add-In sowie in Word-Legacy-Bildteilen.
Excel: In Kopf- und Fusszeilen wird die SVG vor dem Einbetten in ein PNG umgewandelt (gerastert): Excel stellt dort keine Vektorgrafiken dar.
Outlook-Signaturen: Die SVG wird ebenfalls in ein PNG umgewandelt, da Outlook Classic in HTML/VML keine Vektorgrafiken darstellt.
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.

GlobalFields im visuellen Fields Editor verwalten

Referenzen auf globale Felder lassen sich im visuellen Fields Editor des Vorlageneditors verwalten, ohne in die XML-Ansicht zu wechseln. Sie erscheinen in derselben Liste wie die übrigen Felder: links der Key, rechts der Typ «GlobalFields». Die Feldsuche filtert sie mit.

Referenz hinzufügen. Über «Feld hinzufügen» den Typ «GlobalFields» wählen und den Key aus der Liste der vorhandenen globalen Konfigurationen übernehmen. Der Typ wird nur angeboten, wenn in der Datenquelle referenzierbare globale Feldkonfigurationen vorliegen. Ein Key, den die Vorlage bereits referenziert, wird abgelehnt.

Referenz entfernen. Eine bestehende Referenz wird zunächst zum Löschen markiert und durchgestrichen dargestellt; entfernt wird sie beim Speichern. Eine neu hinzugefügte, noch nicht gespeicherte Referenz verschwindet sofort.

Vorschau. Der Tab «Vorschau» zeigt zum ausgewählten Key die aufgelöste globale Konfiguration als XML, einschliesslich der enthaltenen Code-Blöcke. Die Anzeige ist schreibgeschützt. Lässt sich der Key nicht auflösen, erscheint an dieser Stelle ein Hinweis.

Modifications nur in der XML-Ansicht

Das Modifications-Element wird im visuellen Fields Editor nicht dargestellt und lässt sich dort nicht bearbeiten. Für Änderungen daran bleibt die XML-Ansicht der Dokumentfunktion zuständig.

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.

Visueller Fields-Editor

Fields lassen sich im Vorlageneditor von primedocs Desktop wahlweise direkt als XML oder im visuellen Fields-Editor bearbeiten. Der visuelle Editor zeigt links die Feldliste (mit Suchfeld) und rechts die Attribute sowie den Code des ausgewählten Feldes. Er steht nur zur Verfügung, wenn sich das XML gültig deserialisieren lässt.

Nur im Desktop Client

Der visuelle Fields-Editor ist Teil des Desktop Clients (WPF, Windows). Die Feldverwaltung im Web-Admin ist eine separate Funktion und steht noch nicht zur Verfügung: Die hier beschriebenen Befehle sind im Web nicht zu finden.

Schema von Object und ObjectCollection bearbeiten

Für Object und ObjectCollection steht ein visueller Schema-Editor zur Verfügung. Dort Elemente hinzufügen oder entfernen und deren Namen und Typ festlegen. Ein Schema kann selbst Object- und ObjectCollection-Elemente enthalten; deren untergeordnete Schemas lassen sich auf dieselbe Weise bearbeiten.

Auf jeder Ebene müssen die Namen unabhängig von Gross- und Kleinschreibung eindeutig sein und mindestens ein Element vorhanden sein. Namen beginnen mit einem Buchstaben (a-z, A-Z) oder Unterstrich; danach sind zusätzlich Ziffern erlaubt. Für Date muss genau eines der Attribute Format oder translate-Format gesetzt sein. Fehler werden an der betroffenen Ebene angezeigt und müssen vor dem Speichern korrigiert werden. Der Code-Editor des Felds bleibt für beide Typen verfügbar, um die Werte passend zum Schema zurückzugeben.

Reihenfolge ändern

Die Reihenfolge der Felder wird über die Pfeil-Schaltflächen über der Feldliste geändert («Ausgewähltes Feld nach oben/unten verschieben»), alternativ mit Alt+↑ und Alt+↓. Die neue Reihenfolge wird ins XML übernommen. Drag & Drop wird nicht unterstützt.

Daneben sortiert eine Schaltfläche die gesamte Feldliste alphabetisch; ein weiterer Klick wechselt zwischen A–Z und Z–A.

hinweis

Solange der Suchfilter über der Feldliste aktiv ist, ist das Umsortieren deaktiviert. Zuerst die Suche leeren, danach lässt sich wieder verschieben.

Feld duplizieren

Ctrl+D legt eine Kopie des ausgewählten Feldes direkt hinter dem Quellfeld an. Die Kopie erhält den Namen <Name>_Copy, weitere Kopien <Name>_Copy2, <Name>_Copy3 und so weiter. Bei Object und ObjectCollection wird auch das Schema mitkopiert.

Feldtyp nachträglich ändern

Der Befehl Typ ändern (Ctrl+T) wandelt ein bestehendes Feld in einen anderen Feldtyp um, ohne es neu anlegen zu müssen. Vor der Umwandlung erscheint ein Warndialog mit dem Dropdown für den Zieltyp.

Der Typwechsel verwirft Attribute unwiderruflich

Attribute, die der neue Typ nicht unterstützt, werden beim Bestätigen verworfen. Betroffen sind je nach Zieltyp Value, translate-Value, Format, translate-Format, Asset, word-UpdateBehavior sowie die DynamicSnippet-Metadaten (translate-Name, Description, translate-Description, SearchKeywords, translate-SearchKeywords, AutoTextName). Beim Wechsel auf YesNo wird ein nicht-boolescher Value geleert. Das Schema überlebt ausschliesslich den Wechsel Object ↔ ObjectCollection; bei jedem anderen Zieltyp wird es entfernt.

Es gibt kein Undo: Der Warndialog ist die einzige Rückfrage. Vor dem Typwechsel eines gepflegten Feldes daher die Vorlage sichern oder das XML kopieren.

Der Code bleibt erhalten, sofern der Zieltyp Code unterstützt; Hint ist der einzige Typ ohne Code: Dort entfallen Code und die GlobalCode-Referenzen. XML-Kommentare am Feld bleiben bestehen.

Vorbefüllter Code je Feldtyp

Wird ein neues Feld angelegt, füllt der Editor ein zum Feldtyp passendes main()-Skelett vor, statt eines generischen return ""; für alle Typen. Beim nachträglichen Typwechsel wird das Skelett nur gesetzt, wenn der Zieltyp zwingend Code braucht (Object, ObjectCollection, FormattedText, WordContent, InlineWordContent, WordTableRows, DynamicSnippet) und noch kein Code vorhanden ist.

Bei den Inhaltstypen FormattedText, WordContent, InlineWordContent, WordTableRows und Picture prüft die Engine den Rückgabewert und meldet bei einem Mismatch einen Fehler; ein einfacher String wird dort nicht automatisch umgewandelt.

Feldtyp	Rückgabewert im Skelett
`Text`, `DynamicSnippet`	`""`
`YesNo`	`false`
`Date`	`new Date()`
`Object`	`{}`
`ObjectCollection`	`[]`
`FormattedText`	`$.formattedText.fromText("")`
`WordContent`	`$.wordContent.fromText("")`
`InlineWordContent`	`$.inlineWordContent.fromText("")`
`WordTableRows`	`$.wordTableRows.getBuilder()` … `builder.build()`
`Picture`	`null`
`Hint`	(kein `Code`-Element)

Welcher Rückgabewert pro Feldtyp erwartet wird, beschreibt Rückgabewert von Field-Typen.

JavaScript-Syntaxprüfung

Der Code-Editor markiert den ersten JavaScript-Syntaxfehler mit einer roten Wellenlinie; ein Tooltip zeigt beim Überfahren die Meldung. Geprüft wird beim Öffnen und danach kurz nach der letzten Eingabe.

Keine Wellenlinie heisst nicht «valide»

Die Syntaxprüfung ist rein informativ: Sie ist bewusst tolerant ausgelegt, um Fehlalarme zu vermeiden, und blockiert das Speichern nicht. Sie ersetzt weder die Fields-Validierung noch einen Test der Vorlage: Code ohne Wellenlinie kann zur Laufzeit trotzdem fehlschlagen.

Bewusst nicht als Fehler markiert wird Code, der mit einem Objektliteral auf oberster Ebene beginnt ({ MyText: "…" }) und den primedocs abweichend vom JavaScript-Standard als Objekt statt als Block interpretiert.

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​

Hint​

Hinweis in der Vorlage platzieren​

Verhalten im erzeugten Dokument​

Einschränkungen​

Picture​

Bildgrösse festlegen (HeightInCm / WidthInCm)​

Word​

PowerPoint​

Bildmodus (PRIMEDOCS.PICTUREMODE)​

Bildausrichtung (PRIMEDOCS.PICTUREANCHOR)​

Objects und ObjectCollections​

GlobalFields​

Felder modifizieren​

GlobalFields im visuellen Fields Editor verwalten​

DynamicSnippet​

Rückgabewert des Code-Blocks​

Attribute für DynamicSnippet​

Verwendung als AutoText​

Visueller Fields-Editor​

Schema von Object und ObjectCollection bearbeiten​

Reihenfolge ändern​

Feld duplizieren​

Feldtyp nachträglich ändern​

Vorbefüllter Code je Feldtyp​

JavaScript-Syntaxprüfung​

Beispiele​

Grundaufbau

Elemente

Attributwerte aus globalen Übersetzungen

Text

FormattedText

WordContent

InlineWordContent

WordTableRows

Date

YesNo

Hint

Hinweis in der Vorlage platzieren

Verhalten im erzeugten Dokument

Einschränkungen

Picture

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

Word

PowerPoint

Bildmodus (`PRIMEDOCS.PICTUREMODE`)

Bildausrichtung (`PRIMEDOCS.PICTUREANCHOR`)

Objects und ObjectCollections

GlobalFields

Felder modifizieren

GlobalFields im visuellen Fields Editor verwalten

DynamicSnippet

Rückgabewert des `Code`-Blocks

Attribute für `DynamicSnippet`

Verwendung als AutoText

Visueller Fields-Editor

Schema von Object und ObjectCollection bearbeiten

Reihenfolge ändern

Feld duplizieren

Feldtyp nachträglich ändern

Vorbefüllter Code je Feldtyp

JavaScript-Syntaxprüfung

Beispiele