Skip to main content
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.

The JavaScript syntax of the Code element and the $ API are described on the Code (JavaScript) page.

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 nameDescription
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 nameDescription
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 nameDescription
Format / translate-Format (optional)Date format for display in the document.

YesNo​

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

Hint​

A Hint field stores a completion hint for the person editing the generated document. It differs from every other field type in one respect: it produces no value for the document and is therefore not available through $("Fields.<Name>").

<FieldsConfiguration>
  <Fields>
    <Hint Name="RecipientHint" translate-Value="Hints.Recipient" />
  </Fields>
</FieldsConfiguration>
AttributeDescription
Name (required)Name of the hint. It is referenced by this name from the Word content control.
Value (optional)Fixed hint text.
translate-Value (optional)Key from the global translations, e.g. Hints.Recipient. This makes the hint multilingual, resolved in the UI language (see below).

Placing a hint in the template​

The hint is placed in the Word add-in through the Insert Hint button in the Templating group. Both are entered in the same input box: as you type, it suggests the Hint fields configured here; without a chosen suggestion, the text entered applies. This yields two variants:

Tag on the content controlWhere the text comes from
primedocs.HintField=[Name]Refers to a Hint field configured here. Multilingual through translate-Value.
primedocs.HintText=[TEXT]Fixed text directly in the tag, without a field configuration and without translation.

For multilingual templates HintField is therefore the right choice. HintText suits single-language cases and is the only variant that is also permitted inside a WordContent snippet.

Why Hint is a field type of its own

The hint text is resolved in the UI language, not in the document language — unlike field values that flow into the document. A completion hint addresses the person editing, not the document. A Text field with translate-Value does not achieve that.

Behaviour in the generated document​

The hint text is not written into the document. During generation the content control is instead

  • locked against editing,
  • marked as hidden text (Word character format «Hidden») and
  • replaced by a ❓ with the text «Click here for additional information».

This is only visible while hidden text is shown in Word. The hint text itself appears in the Quick Check.

note

The inserted text «Click here for additional information» follows the UI language as well. The hint therefore uses the language of the person editing throughout.

Restrictions​

  • Hint fields cannot be inserted through «Bind field»: they do not appear in that button's field selection.
  • If primedocs.HintField=[Name] refers to a name that is missing from the Fields configuration, generation aborts with an error. The same applies if the name points to a field of a different type.

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. This is supported in Word and PowerPoint templates; in all other template types both values are ignored and reported as a warning.

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

The same mapping applies in both formats:

SpecifiedResult
WidthInCm onlyThe height is computed from the image's aspect ratio.
HeightInCm onlyThe width is computed from the image's aspect ratio.
bothThe image is stretched to the exact dimensions: the aspect ratio is not preserved.
neitherThe target application decides the size.

The values are exact target sizes, not upper bounds: a source image smaller than the specified size is scaled up to that size.

Valid values are greater than 0 and at most 200 cm. Values outside that range count as unset and are reported as a warning during generation.

Word​

In Word the dimensions apply directly to the picture placeholder: no additional tag is required. Without WidthInCm/HeightInCm the placeholder keeps the size defined in the template. The dimensions also apply to SVG images.

When both dimensions are set, primedocs removes the aspect ratio lock on the inserted picture. Without that step, Word would re-derive the width from the height and discard the specified width.

If the second dimension cannot be computed from the aspect ratio within the valid range, for instance with extremely narrow images, the size is left unchanged entirely, with a warning during generation. If primedocs cannot read the image's aspect ratio, the second dimension is derived from the placeholder's proportions instead, again with a warning.

The inserted picture is regular document content: it can be selected and edited, and it does not depend on a live Word data binding. When the profile is switched in an open document, the add-in replaces the picture itself and re-applies the size defined in the field.

PowerPoint​

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

ValueBehaviour
ExactThe image is inserted at the given size. At least one of WidthInCm/HeightInCm must be set.
FitThe 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.

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.

ValueAlignment within the original shape frame
TopLefttop left
TopRighttop right
BottomLeftbottom left
BottomRightbottom right
Centercentred
(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, unlike 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 nameDescription
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.

  • Word and PowerPoint: embedded as a vector graphic together with an automatically generated PNG fallback. Office 2019 and later shows the vector graphic, older versions the fallback. In Word, the SVG is rasterised only in special cases: when an already open document is refreshed through the add-in, and in Word legacy image parts.
  • Excel: in headers and footers the SVG is converted to a PNG (rasterised) before embedding: Excel does not render vector graphics there.
  • Outlook signatures: the SVG is likewise converted to a PNG, because Outlook Classic does not render vector graphics in HTML/VML.
  • 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 nameDescription
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.

Managing GlobalFields in the visual Fields editor​

References to global fields can be managed in the visual Fields editor of the template editor, without switching to the XML view. They appear in the same list as the other fields: the Key on the left, the type "GlobalFields" on the right. The field search includes them.

Adding a reference. In "Add field", select the type "GlobalFields" and pick the Key from the list of existing global configurations. The type is only offered when the data source contains referenceable global field configurations. A Key the template already references is rejected.

Removing a reference. An existing reference is first marked for deletion and shown struck through; it is removed when you save. A newly added reference that has not been saved yet disappears immediately.

Preview. The "Preview" tab shows the resolved global configuration for the selected Key as XML, including any Code blocks it contains. The display is read-only. If the Key cannot be resolved, a note appears in its place.

Modifications only in the XML view

The Modifications element is not shown in the visual Fields editor and cannot be edited there. Changing it remains the job of the document function's XML view.

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 valueResult
stringUnformatted text
FormattedTextFormatted text
WordContentWord content
nullThe 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 nameDescription
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.

Visual Fields editor​

Fields can be edited in the template editor of primedocs Desktop, either directly as XML or in the visual Fields editor. The visual editor shows the field list (with a search box) on the left and the attributes and code of the selected field on the right. It is only available when the XML deserialises successfully.

Desktop client only

The visual Fields editor is part of the Desktop client (WPF, Windows). Field management in the Web Admin is a separate feature and is not available yet: the commands described here cannot be found on the web.

Editing Object and ObjectCollection schemas​

A visual schema editor is available for Object and ObjectCollection. Add or remove elements and set their names and types there. A schema can itself contain Object and ObjectCollection elements; edit their nested schemas in the same way.

Names must be unique at each level regardless of case, and each schema must contain at least one element. Names start with a letter (a-z, A-Z) or underscore; subsequent characters may also be digits. For Date, exactly one of Format or translate-Format must be set. Errors are shown at the affected level and must be corrected before saving. The field's code editor remains available for both types to return values matching the schema.

Reordering fields​

The field order is changed with the arrow buttons above the field list ("Move the selected field up/down"), or with Alt+↑ and Alt+↓. The new order is written to the XML. Drag and drop is not supported.

A separate button next to them sorts the whole field list alphabetically; clicking again switches between A–Z and Z–A.

note

While the search filter above the field list is active, reordering is disabled. Clear the search first, then fields can be moved again.

Duplicating a field​

Ctrl+D creates a copy of the selected field directly below the source field. The copy is named <Name>_Copy, further copies <Name>_Copy2, <Name>_Copy3 and so on. For Object and ObjectCollection, the Schema is copied as well.

Changing the field type afterwards​

The Change Type command (Ctrl+T) converts an existing field into another field type without recreating it. A warning dialogue with the target type dropdown appears before the conversion.

Changing the type discards attributes irreversibly

Attributes that the new type does not support are discarded on confirmation. Depending on the target type this affects Value, translate-Value, Format, translate-Format, Asset, word-UpdateBehavior and the DynamicSnippet metadata (translate-Name, Description, translate-Description, SearchKeywords, translate-SearchKeywords, AutoTextName). When switching to YesNo, a non-boolean Value is cleared. The Schema only survives the switch between Object and ObjectCollection; for any other target type it is removed.

There is no undo: the warning dialogue is the only prompt. Back up the template or copy the XML before changing the type of a field that carries configuration.

The Code is kept where the target type supports code; Hint is the only type without code: there the Code and the GlobalCode references are removed. XML comments on the field are preserved.

Pre-filled code per field type​

When a new field is created, the editor pre-fills a main() skeleton matching the field type, instead of a generic return ""; for every type. On a later type change the skeleton is only seeded when the target type requires code (Object, ObjectCollection, FormattedText, WordContent, InlineWordContent, WordTableRows, DynamicSnippet) and no code is present yet.

For the content types FormattedText, WordContent, InlineWordContent, WordTableRows and Picture, the engine type-checks the return value and reports an error on a mismatch; a plain string is not coerced automatically there.

Field typeReturn value in the skeleton
Text, DynamicSnippet""
YesNofalse
Datenew Date()
Object{}
ObjectCollection[]
FormattedText$.formattedText.fromText("")
WordContent$.wordContent.fromText("")
InlineWordContent$.inlineWordContent.fromText("")
WordTableRows$.wordTableRows.getBuilder() … builder.build()
Picturenull
Hint(no Code element)

The return value expected per field type is described in Return value of Field types.

JavaScript syntax check​

The code editor marks the first JavaScript syntax error with a red squiggly underline; hovering it shows the message in a tooltip. The check runs when the field is opened and shortly after the last keystroke.

No squiggle does not mean valid

The syntax check is informational only: it is deliberately tolerant to avoid false positives, and it does not block saving. It replaces neither the Fields validation nor a test run of the template: code without a squiggle can still fail at runtime.

Code that starts with a top-level object literal ({ MyText: "…" }), which primedocs interprets as an object rather than a block, is deliberately not flagged as an error.

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>