Word: Dive into Fields

Owned by Daniela Zimmermann
Last updated: Oct 01, 2024
19 min read

This page introduces the Fields document function.

Fields offer the option of making a template dynamic depending on the selected profile, its organisational data, forms fields and more.

For the sake of simplicity and to avoid misunderstandings, we will always refer to fields.

NOTE

This page is a supplement to the technical documentation. It explains how to do something and provides more detailed and explained examples than the technical documentation.
On the contrary, the technical documentation explains how something is.

For a better understanding, we therefore recommend that you follow further links and read the relevant sections.

Attach fields document function in template editor

The Fields or Fields document function is added in the template editor by clicking on
Document functions → Manage → + Add in the Fields entry.

The standard configuration shows a few example fields

<FieldsConfiguration> <Fields> <Text Name="Field01" Value="Content of Field01" /> <Text Name="Field02" Value="Content of Field02" /> <Text Name="Field03"> <Code> "[" + $("Field01") + "] [" + $("Field02") + "]" </Code> </Text> </Fields> </FieldsConfiguration>

These text fields should be deleted to start with:

Configure simple field and insert into template

We would like to insert a field greeting that displays the text ‘Lorem Ipsum’ in the Word template:

<FieldsConfiguration> <Fields> <!-- a text field --> <Text Name="Greeting" Value="Lorem Ipsum" /> </Fields> </FieldsConfiguration>

Click on the Editor button in the menu bar or use the key combination Ctrl+E to open the template in Word.

In the open Word template, open the primedocs ribbon and then click on the Bind field button.

This opens the ‘Select field’ dialogue box.

Select Greeting from the dropdown (in this case, Greeting is already preselected as it is the only available field).

Click on Insert.

The field is now inserted.

 

The Fields content controls are blue.

Save the Word template.

Since version 4.0.20093, you no longer have to close and reopen the editor to bind a newly created field :partying_face: The newly created field only needs to be saved in the editor for it to appear in the ‘Select field’ dialogue.

Return to the template editor and click on ‘Test document’ or use Ctrl+T. Now fill in all the parameters as if you were a user. The document is then generated in test mode.

(Templating: Basics | Test document )

 

The text ‘Lorem Ipsum’ is now displayed, which we have stored as the value in the field:

Information about all field types

Before we go into more detail about the different field types, we recommend that you read the following pages of the technical documentation carefully. They form the basis for the application examples that follow for each field type in this chapter:

We would particularly like to emphasise the importance of the following chapters:

The following information is supplementary:

Typ Text

  • The text field outputs unformatted text.

  • A JS function in the text field must have the return value String.

  • The formatting must be applied in the Word template using styles - however, this is applied to the entire content in the content control.

  • If several styles need to be displayed in a field content control in Word, use the Word: Dive into Fields | Typ FormattedText .

  • See the list of all primedocs functions: Code | Explanation of all functions per API

In use

JS-Code

<Text Name="Footer"> <Code> function main() { // Fields let profileData = $('Profile.User.FirstName'); // Get profile data (implicit, like getText()) let field = $.getText('Forms.TextField'); // Get Forms field (a text field, explicitly with getText()) let formsField = $.getDateAsString('Forms.Date'); // Get Forms field (a date field) let otherField = $.getText('Page'); // Get another field (must be present in the same config!) // Translations let translation = $.translations.getText('Texts.Enclosures'); // Get unformatted text return $.joinNonEmpty("\n", profileData, field, formsField, otherField, " ", translation); } </Code> </Text> <Text Name="Page" translate-Value="Texts.Page" />

Result in Word

Typ FormattedText

  • The field of type FormattedText allows the insertion of formatted text in the following areas:

    • Global translation of type Formatted text

    • Text module of type Formatted Text

  • FormattedText cannot contain tables, tables of contents, images or other complex Word content. WordContent fields are available for this purpose.

  • A FormattedText field can only return a FormattedText.

  • The formatting is provided in a global translation using HTML or saved in a FormattedText text module. FormattedText is therefore suitable for mapping more complex logic with different Word styles (often used in letterheads or for lists of inserts).

  • The most important JavaScript functions:

  • FormattedText fields can also use the Code | Builder API . More on this below: Word: Dive into Fields | Builder (Advanced) .

FormattedTexts as global translation

The advantage of FormattedTexts in the global translations is that you do not have to create a text module but can create the text programmatically with HTML (see examples below).

Examples“Footer“

The FormattedText is created as a global translation of the type ‘FormattedText’.

The Id of our example is FormattedTexts.FooterBold.

<p></p>: one paragraph

<b></b>: bold

Code

Access to the global translation text module works like this:

Defined Word-Style

With the attribute data-word-style-id you specify which style a paragraph should have. This makes it possible to output several differently formatted paragraphs in one field. The attribute can also be used in <span>.

Control structure (if)

A control structure checks whether a condition is fulfilled and outputs the content.

Loop (each)

A loop goes through a list and repeats the content for each element in the list.

Examples

Field ‘Footer’ with named parameters

In the translation entry, you can create placeholders or parameters in paragraphs (<p></p>) in order to fill them with data. Which data is ultimately displayed in these placeholders is defined in the field using named parameters with the same name.

Definition in the global translations

Global translation with Id: FormattedTexts.FooterBoldWithParams, with named parameters

JS-Code

Gets the translation of type FormattedText. Parameters are: Snippet key and a list of named parameters

Field “ReferenceNo”

Covers the following contents:

  • Named parameters

  • Defined word style

  • Control structure

Global translation with Id: FormattedTexts.Paragraphs.BoldNormalHeader

Field “ReferenceNo”, which fetches the translation:

Result in Word

Field “EnclosuresBox”

Covers the following contents:

  • Defined word style

  • Control structure

  • Loop

Global translation with Id: FormattedTexts.EnclosuresBox

Field “EnclosuresBox”, that fetches the translation:

Result in Word

FormattedText as a Word content

As mentioned, text modules of the FormattedText type cannot save tables, images or other complex Word content. For this reason, a FormattedText is only created as a text module and retrieved into a field if it is a paragraph with text that has one or more styles.

The FormattedText is stored as a text module of the type “Formatted text” and has a key.

The key of our example is FooterFTSnippet.

Code

Accessing to the Word content works like this:

Typ WordContent

Examples

WordContent-Field Introduction

WordContent-Field ContractTitles with named parameters

You can enter snippet placeholders or parameters in the text module. The data that is ultimately displayed in these placeholders is defined in the field using named parameters with the same name:

Create WordContent snippets

Before you can create a WordContent field, you need a WordContent text module: a snippet of the type Word content. The three most important points:

  • In order to store dynamic content (fields, forms, profile data), content control elements, so-called snippet placeholders, are inserted in the corresponding paragraph.

  • Like all other text modules, WordContent text modules are saved to the desired category in the snippet bar using drag'n'drop.

  • You need a key to use them in fields.

Insert snippet placeholder

So that dynamic text (from fields, forms fields or profile data) can be inserted into a WordContent snippet, we need content controls, so-called snippet placeholders.

A text module placeholder can be inserted into a text section in the Word editor of a template, which is then saved as a WordContent text module.

Procedure

  1. Place the cursor at the desired position in the text section.

  2. Click on the Insert snipet pplaceholder button in the primedocs ribbon.

  3. Enter the name of the placeholder and confirm by clicking on the Insert button.

  4. A yellow content control is then inserted.

WordContent-save as a snippet

WordContent snippets are saved like all other snippet using drag'n'drop.
Watch the demo or read the instructions with all the explanations:

Demo

Procedure

Open the snippet bar by clicking on snippet in the primedocs ribbon.

Select the text section and drag and drop it into the Template snippet folder in any category.

Now customise the properties of the text module to be created:

  • The name is generated automatically. Adjust it if necessary.

  • Select the type ‘Word content’ (WordContent).

  • Enter a key (Key).

Then confirm with OK.

Application example: Invitation

A department has several templates for an invitation. Although the invitation text is always the same, two values are different depending on the template. The text is therefore saved as a WordContent snippet with snippet placeholders for greater flexibility.

The following text should be displayed at the end of the created document:
Invitation to the event ‘[event]’ on [date].

The event and date are dynamic content that we want to query from the user via forms and then display in the text.

For this application example, we need

  1. a snippet with the snippet placeholders and with key

  2. Forms fields that should later be in the snippet

  3. a WordContent field that fetches the snippet, fills the parameters with the Forms fields and is later used in the template

Procedure

  1. Create a snippet of type WordContent:

    1. Insert a snippet placeholder with the name EventName.

    2. Insert a second snippet placeholder with the name EventDate.

       

    3. in Word:

       

    4. Mark the text section and save it in the desired category:

      1. as type “Word content

      2. set “Invitation” as the key.

         

  2. Create Forms fields in Forms, see Forms documentation

    1. a text field for EventName

    2. a date field for EventDate

  3. Create a WordContent field and place it in the template:

    1. The following code shows a WordContent field InvitationSnippet.

    2. The snippet with the Invitation key is retrieved using the getWordContent() function of the Snippet API.

    3. To fill the text module placeholders with content, the data is provided via the EventName and EventDate parameters. These can be filled with all types of text (fixed text, form fields, fields, user data, etc.).

    4. Insert the previously created Forms fields into the parameters:

      1. The Forms field Forms.EventName is transferred to the snippet placeholder EventName.

      2. The Forms field Forms.EventDate is transferred to the snippet placeholder EventDate. We use the getDateAsString() function, as it is a date field that returns a date - but we need a string. More information here: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/edit-v2/444891137#Functions.1

  4. The Field InvitationSnippet is then inserted into the Word template using the Bind field button in the document and the template is saved.

    This is the result in Word when you test the document:

Builder (Advanced)

The Builder enables the assembly of Texts, FormattedTexts and WordContents in the sense of a modular system, in which each text, regardless of type, is strung together.

The Builder API can be used in fields of type WordContent and FormattedText: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/edit-v2/444891137#Builder-API

FormattedText-Field Footer with Builder

Result in Word

FormattedText-Field HeaderContact with Builder

JS-Code

Result in Word

WordContent-Field HeaderContact with Builder

JS-Code

Result in Word

Typ Date

See technical documentation: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61408865/Fields#Date

The date appears in the format defined in Forms.

Click here for more information: https://primesoft-group.atlassian.net/wiki/spaces/PD/pages/edit-v2/513114113?draftShareId=80b57d2b-c81a-47ab-b7c1-c74d27363d16#Datumsfunktionen-und-mit-Daten-rechnen

Typ YesNo

See technical documentation: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61408865/Fields#YesNo

A field of type YesNo is currently used to use logic in several fields or to make the code clearer.

Examples

Simple example

In this example, the following condition is checked: If the Forms field is not null (i.e. if it exists), true is output, otherwise false.

More extensive example

In this example, several conditions are checked:

  • $('HasSignerMain') is first used to check whether there is a main signatory; the HasSignerMain field returns true or false here.

  • If $('HasSignerMain') returns true, the system checks whether the user field User.Function contains the same value as the global translation Staff.RRFunction. If this is the case, true is returned.

  • In all other cases, false is returned.

This means that SignerIsRegierungsrat returns true if the user who created the document and is the main signatory is a member of the government.

Typ Picture

See technical documentation: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61408865/Fields#Picture

Fields of type Picture can be used to bring images into a field. This can be done in two ways:

  • Via a reference to profile or organisation data

  • Via an address to a file (asset)

Examples

Get signature image of a signatory

Get the logo of an organisation

Get image from the files (asset)

Modify fields

GlobalFields that have been referenced in a template or a global entry can be modified. We recommend modifying as often as necessary and as little as possible.

The technical documentation provides an introduction to the topic: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61408865/Fields#Modify-fields

Example

Global entry Fields.Contract

The configuration of the GlobalField with Id Fields.Contract contains several fields and a reference to another GlobalField:

Field configuration in template

The global entry is referenced in the content template in the Fields configuration:

At this point, the fields are displayed as follows:

Modification

Now you want to define the fields differently in this specific template. To do this, they are modified as follows:

Result

If a new document is created, primedocs includes the new definitions and not the originally referenced ones.

This means that the new values are displayed in the same fields in a created document:

 

PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland