Purpose and use

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. This also allows you to manage what happens if the user does not fill in both forms fields.

Basic structure

<FieldsConfiguration>
  <Fields>
    <!-- Insert form elements and groups here -->
  </Fields>
</FieldsConfiguration>

Elements

Attributes that are offered for all elements:

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-. The two attributes are mutually exclusive, so only a fixed value or a translated value may be used.

Text

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

Attributes for Text

FormattedText

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

When inserting using global translations, it is possible to output differently formatted text passages in a content control in the document, depending on profile data or selected data in forms. This is often used in headers and footers, for example, because bold and non-bold styles are often used in one content control.

Attributes for FormattedText

There are no further attributes. The dynamisation of content and data is made possible in the code element with JavaScript and the software's own functions. https://primesoft-group.atlassian.net/wiki/x/DgC7Fw

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

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>

Attributes for WordContent

There are no other attributes. The insertion of WordContent is made possible in the code element with JavaScript and the software's own functions. https://primesoft-group.atlassian.net/wiki/x/DgC7Fw

Date

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

Attributes for Date

YesNo

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

Attributes for YesNo

Picture

<FieldsConfiguration>
  <Fields>
    <Picture Name="PartnerLogo" Asset="\\fileshare\PartnerLogo.png" />
  </Fields>
</FieldsConfiguration>

Attributes for Picture

GlobalFields

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

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

GlobalFields can be referenced in any Fields configuration - in a template or in an entry in the global configuration.

More information about the global configurations can be found here: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61407710/Global+Configurations#Working-with-typed-fields.

A concrete example for recognizing the connection between the global entry and the reference to a global entry can be found here: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61407710/Global+Configurations#Referencing-global-entries-in-the-templates.

Attributes for GlobalFields

The reference to a global entry is made using the Key attribute. If you select it, a list of all available global entries is automatically displayed.

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.

To modify a field, the Modifications element is opened in the GlobalField. In it, the field to be modified is redefined with the same name and its value or code is defined differently. This means that the original field is not included in the field pipeline during document generation, but the modified field is.

Example

The GlobalField with Id Fields.IsPresident contains a YesNo field with the value true. The configuration looks like this:

<FieldsGlobalFields>
  <YesNo Name="IsPresident" Value="true" />
</FieldsGlobalFields>

In a template, false is to be used for the YesNo field IsPresident as an exception. To achieve this, IsPresident is redefined in the fields configuration of this template:

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

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

Example

<FieldsConfiguration>
  <Fields>
  
    <!-- Fill placeholder from layout -->
    <Picture Name="PartnerLogo" Asset="\\e123\User\Muster\BeispielLogo.PNG" />
    <Text Name="Page" Value="Seite" />
    <!-- get FormattedText -->
    <FormattedText Name="Title">
      <Code>$.translations.getFormattedText("FormattedTexts.FormattedTitle")</Code>
    </FormattedText>
    
    <!-- Data in the content of the template -->
    <Text Name="Greeting" translate-Value="Greetings.KindRegards1" />
    <!-- Referencing a global entry -->
    <GlobalFields Key="Letters.Subject" />
    <!-- get WordContent-Snippet -->
    <WordContent Name="Introduction">
      <Code>$.snippets.getWordContent("Introduction")</Code>
    </WordContent>
    
  </Fields>
</FieldsConfiguration>

Fields in Office templates

As already explained in https://primesoft-group.atlassian.net/wiki/x/JgGpAw , the fields are then inserted manually into the template. Depending on their type, they are inserted as a specific content control, which creates a DataBinding between primedocs and the document. DataBindings are tracked in documents by primedocs and the fields are continuously validated during document generation and when the document is updated.

Overview of inserted content control per field type

The following table shows which field type is inserted into the template as which content control:

Overview of field type per Office application

As a supplement, the following matrix shows which field type can be used in which Office applications:

*Outlook e-mails and signatures are only saved in HTML in the web-enabled Outlook version. This means that