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.

---

Basic Structure

<FieldsConfiguration>
  <Fields>
    <!-- Insert form elements and groups 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>

From primedocs 4.0.30153, a Picture field for Outlook can also be defined via the Base64 encoding of the image file:

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

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.

---

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>

---

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.

---

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>