Version: 4.1 (2026 H2)

Fields

This document function can be used to link content in order to integrate it into the document.

Suppose you use the Forms function to request a date and a title from the user and want to place this data together in a footer.
You can then use this document function to output the date field and the text field together in one Field.

note

Not every field type can be placed directly in the document in every Office application — see Overview: field type per Office application.

Basic Structure

<FieldsConfiguration>
  <Fields>
    <!-- Insert fields here -->
  </Fields>
</FieldsConfiguration>

Elements

Attributes that are offered for all elements:

Attribute name	Description
`Name` (required)	Is required for identification. Must not contain any spaces and must be unique.

Attribute Values from Global Translations

Some attributes can be filled with the value of a global translation instead of a fixed value. These attributes are each preceded by a translate-.

Text

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

Attributes for Text

Attribute name	Description
`Value` / `translate-Value` (optional)	Predefined text or dynamic text from the global translations. Only one of the two attributes may be set.

FormattedText

FormattedText allows the insertion of formatted text. FormattedText is both a type of global translation and a Snippet type.

<FieldsConfiguration>
  <Fields>
  
    <!-- Get FormattedText as a global translation -->
    <FormattedText Name="EnclosuresTitle">
      <Code>$.translations.getFormattedText("FormattedTexts.EnclosuresTitle")</Code>
    </FormattedText>
    
    <!-- Get FormattedText as a Snippet -->
    <FormattedText Name="SimpleSnippet">
      <Code>$.snippets.getFormattedText("FormattedTexts.SimpleSnippet")</Code>
    </FormattedText>
    
  </Fields>
</FieldsConfiguration>

note

word-UpdateBehavior attribute

The types FormattedText, WordContent, InlineWordContent and WordTableRows support the optional word-UpdateBehavior attribute. It controls whether a field is overwritten with the values calculated by primedocs during an update in Word (e.g. through a language, profile or property change). The default is Enabled; set Disable to deactivate. The latter should only be used when the initially generated fields are intended to be edited directly by the user (e.g. for a fill-in-the-blank text).

WordContent

The WordContent field allows the dynamic insertion of multiple text sections into a template. Together with the Forms document function, more complex templates can be realised or several templates can be consolidated into one.

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

A WordContent always contains one or more paragraphs and must therefore be placed on its own paragraph as a placeholder in the template. For dynamically formatted output within a line, use the InlineWordContent type.

InlineWordContent

The InlineWordContent field allows the dynamic insertion of formatted text sections within a paragraph. Technically, an InlineWordContent consists of only one paragraph and the text content (with or without formatting) — this allows fixed and formatted text to be represented in a single paragraph.

Currently this type can only be created by converting WordContent or FormattedText, where the source must contain only one paragraph.

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

Supports the optional word-UpdateBehavior attribute.

WordTableRows

The WordTableRows field type enables the dynamic generation of entire table rows within an existing table. Fields of type WordTableRows can only be used in Word documents.

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

Every builder entry must have exactly the same number of columns. The builder accepts values of type string, int, double, FormattedText, WordContent and InlineWordContent. If the JavaScript code does not return a table row, the template row is hidden (it is not visible when printing or exporting to PDF).

Supports the optional word-UpdateBehavior attribute.

Binding: To bind a WordTableRows field, you must select exactly one full table row in the editor. This row serves as the template row for all generated entries.

Date

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

Attributes for Date

Attribute name	Description
`Format` / `translate-Format` (optional)	Date format for display in the document.

YesNo

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

Picture

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

A Picture field can also be filled via a Base64 string. The string must start with the prefix base64:.

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

Insert an image via the editor toolbar

You don't have to produce the Base64 string by hand: the XML editor toolbar (template editor, Desktop) provides the "Insert image as base64" button. It opens a file picker (formats BMP, GIF, JPG/JPEG, PNG, TIF/TIFF; max. 50 MB) and inserts the ready-made base64:… string at the cursor position.

Only the string is inserted — so place the cursor inside the Source value; it does not generate a full Picture element. SVG is not offered by the file dialog (SVG remains usable in the Picture field independently of this).

Setting the image size (`HeightInCm` / `WidthInCm`)

Instead of a plain string, a Picture field can return an object to specify the size of the inserted image in centimetres. (Currently PowerPoint only; Word to follow.)

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

Whether the given dimensions are applied depends on the picture mode of the target shape. This is set in PowerPoint via the shape tag PRIMEDOCS.PICTUREMODE (see Picture mode (PRIMEDOCS.PICTUREMODE)), not in the field configuration:

Value	Behaviour
`Exact`	The image is inserted at the given size. At least one of `WidthInCm`/`HeightInCm` must be set.
`Fit`	The image is fitted into the shape; `WidthInCm`/`HeightInCm` are ignored.
(no tag)	PowerPoint's default behaviour (the image is stretched to the shape dimensions); `WidthInCm`/`HeightInCm` are ignored.

In Exact mode, if only one dimension is given, the other is computed proportionally from the image's aspect ratio.

Picture mode (`PRIMEDOCS.PICTUREMODE`)

The picture mode is not an attribute of the field or placeholder definition, but a tag on the PowerPoint shape (managed via the PowerPoint add-in). It controls how a Picture bound to that shape is fitted:

Fit — The image is fitted into the shape dimensions while preserving its aspect ratio; the WidthInCm/HeightInCm of the Picture field are ignored.
Exact — The image is inserted at the exact dimensions from WidthInCm/HeightInCm; a missing dimension is computed from the aspect ratio.
(no tag) — PowerPoint's default behaviour (stretch). There is no default mode.

Picture alignment (`PRIMEDOCS.PICTUREANCHOR`)

Like the picture mode, the picture alignment is a tag on the PowerPoint shape (managed via the PowerPoint add-in). It defines where within the original shape frame the image is aligned — relevant whenever the fitted image ends up smaller than the shape.

Value	Alignment within the original shape frame
`TopLeft`	top left
`TopRight`	top right
`BottomLeft`	bottom left
`BottomRight`	bottom right
`Center`	centred
(no tag)	centred — `Center` is the default

note

The picture alignment only takes effect if PRIMEDOCS.PICTUREMODE is also set on the shape. Without a picture mode, PowerPoint's default behaviour applies and the tag has no effect. An unsupported value produces a warning; alignment then falls back to Center.

As of version 4.0.30171.0, both tags — picture mode and picture alignment — also take effect on the slide master.

In addition to the alignment, the Picture field can shift the image via PowerPointOffsetXInCm and PowerPointOffsetYInCm, in centimetres. Positive values shift right and down respectively, negative values left and up. The shift is applied after the alignment and — like WidthInCm/HeightInCm — is only permitted in PowerPoint templates.

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

When an image is bound with a picture mode set, primedocs additionally removes borders as well as shadow and 3D effects from the target shape so that only the image remains visible.

Attributes for Picture

Attribute name	Description
`Asset` (optional)	Specifies an asset of an image gallery, only possible in PowerPoint: `<Picture Name="Mountains" Asset="Bildergalerie/General/Berge.jpg" />`. The attribute is shown in all template types but is only effective in PowerPoint.

SVG images

Picture fields also support SVG graphics (vector logos, icons). The format is detected automatically from the content — no additional configuration is required.

PowerPoint: embedded as a vector graphic, with an automatically generated PNG fallback for older Office versions.
Word and Excel: the SVG is converted to a PNG (rasterised) before embedding.
In the Web App and the Desktop client, the SVG is rendered directly in the preview.

Objects and ObjectCollections

Object and ObjectCollection fields can be defined dynamically via Code. Access to data via the data interface is normally done through the Forms configuration. Configuration as a Field is only necessary if one or more objects are to be created dynamically based on user input or data transmission.

The Schema element defines all the data that can ultimately be used in a template. The Code must produce one or more JavaScript objects that match the configured schema.

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

note

Code in an Object: main() or a parenthesised expression

The Code must either contain a function main() that returns the object, or consist of exactly one expression.

Unlike standard JavaScript, top-level curly braces are not interpreted as a block statement but as an object (primedocs automatically wraps them in (…)). A directly written object literal therefore works; with multiple properties, the explicit form is recommended to avoid ambiguity:

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

<!-- or a single, parenthesised expression -->
<Code>({ Name: "Erika Muster" })</Code>

GlobalFields

The GlobalFields element can be used to retrieve a globally stored Field.

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

Attributes for GlobalFields

Attribute name	Description
`Key` (required)	The ID of the global entry to be referenced.

Modify Fields

The Modifications element in GlobalFields allows the modification of any field that is included by referencing the GlobalField in the Field pipeline during document generation.

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

When a document is generated from the template, the new definition is taken into account and the value false is used — even if this field is referenced in other fields.

DynamicSnippet

A DynamicSnippet is a dynamic snippet (in German: "dynamischer Textbaustein"). Unlike the other field types, it is not placed at a fixed position in the document: it is evaluated during document generation and then offered to the user for insertion in the snippet pane (the "Dynamic snippets" group) and — optionally — as an AutoText.

This makes it possible to provide snippets that depend on the document's full data context (form input, profile, language) and that update automatically when the form, profile or language changes.

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

note

Dynamic snippets are only available in Word. They cannot be bound in the document and cannot be referenced by other fields via $() — they are used exclusively through the snippet pane or AutoText.

Return value of the `Code` block

The content type is determined at runtime from the return value:

Return value	Result
`string`	Unformatted text
`FormattedText`	Formatted text
`WordContent`	Word content
`null`	The snippet is suppressed entirely (it appears neither in the snippet pane nor as AutoText).

Instead of the content alone, an object can be returned to set content and metadata dynamically. Content is required (string, FormattedText, WordContent or null); the remaining properties are optional and override the corresponding attributes:

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

Attributes for `DynamicSnippet`

Attribute name	Description
`Name` (optional)	Field name and display name in the snippet pane. Optional when `translate-Name` is set.
`translate-Name` (optional)	Translation key for the display name in the snippet pane.
`Description` / `translate-Description` (optional)	Description in the snippet pane. `translate-Description` takes precedence when both are set.
`SearchKeywords` / `translate-SearchKeywords` (optional)	Search keywords for the snippet search. `translate-SearchKeywords` takes precedence when both are set.
`AutoTextName` (optional, max. 32 characters)	When set, the snippet is additionally provided as an AutoText (see below).

Using it as an AutoText

When AutoTextName is set, the user can insert the snippet via AutoText: type the name in the document and press the AutoText shortcut. The shortcut (Ctrl+F3 by default) is configured in the datasource setting "Hotkey for Snippet Auto Texts".

A DynamicSnippet can also be stored globally and referenced via GlobalFields.

Examples

<FieldsConfiguration>
  <Fields>

    <!-- Fill placeholders from the layout -->
    <Picture Name="PartnerLogo" Asset="Bildergalerie/General/Berge.jpg" />
    <Text Name="Page" Value="Seite" />
    <!-- Get FormattedText -->
    <FormattedText Name="Title">
      <Code>$.translations.getFormattedText("FormattedTexts.FormattedTitle")</Code>
    </FormattedText>

    <!-- Data in the template content -->
    <Text Name="Greeting" translate-Value="Greetings.KindRegards1" />
    <!-- Reference a global entry -->
    <GlobalFields Key="Letters.Subject" />
    <!-- Get a WordContent snippet -->
    <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>

Basic Structure​

Elements​

Attribute Values from Global Translations​

Text​

FormattedText​

WordContent​

InlineWordContent​

WordTableRows​

Date​

YesNo​

Picture​

Setting the image size (HeightInCm / WidthInCm)​

Picture mode (PRIMEDOCS.PICTUREMODE)​

Picture alignment (PRIMEDOCS.PICTUREANCHOR)​

Objects and ObjectCollections​

GlobalFields​

Modify Fields​

DynamicSnippet​

Return value of the Code block​

Attributes for DynamicSnippet​

Using it as an AutoText​

Examples​

Basic Structure

Elements

Attribute Values from Global Translations

Text

FormattedText

WordContent

InlineWordContent

WordTableRows

Date

YesNo

Picture

Setting the image size (`HeightInCm` / `WidthInCm`)

Picture mode (`PRIMEDOCS.PICTUREMODE`)

Picture alignment (`PRIMEDOCS.PICTUREANCHOR`)

Objects and ObjectCollections

GlobalFields

Modify Fields

DynamicSnippet

Return value of the `Code` block

Attributes for `DynamicSnippet`

Using it as an AutoText

Examples