/
Word: Dive into Fields

Word: Dive into Fields


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

image-20240116-091531.png

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.

image-20240116-095243.png

<p></p>: one paragraph

<b></b>: bold

Code

Access to the global translation text module works like this:

<FormattedText Name="Footer"> <Code>$.translations.getFormattedText("FormattedTexts.FooterBold")</Code> </FormattedText>

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

<p data-word-style-id="FusszeileFett">{{bold}}</p>

TIP
Consult the developer tools in a created document to find out the available Word styles and their StyleId. How to do this is described here: Developer tools: Tabs in prioritised order

Control structure (if)

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

{{#if bold}} <p><b>{{bold}}</b></p> {{/if}} {{#if normalbold}} <p>{{normal}}</p> {{/if}} {{#if empty}} <p data-word-style-id="InvisibleLine">{{empty}}</p> {{/if}}

Loop (each)

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

{{#each items}} <p>&#8211;&#009;{{this}}</p> {{/each}}

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

<p>Autor: <b>{{firstName}} {{lastName}}</b>, {{function}}</p>

JS-Code

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

<FormattedText Name="Footer"> <Code>$.translations.getFormattedText("FormattedTexts.FooterBoldWithParams", { firstName: $("Forms.FirstName"), // Forms lastName: lastName, // Variable function: "Doctor" // Fixtext }) </Code> </FormattedText>

Field “ReferenceNo”

Covers the following contents:

  • Named parameters

  • Defined word style

  • Control structure

Global translation with Id: FormattedTexts.Paragraphs.BoldNormalHeader

{{#if bold}} <p data-word-style-id="KopfzeileFett">{{bold}}</p> {{/if}} {{#if normal}} <p data-word-style-id="Kopfzeile">{{normal}}</p> {{/if}}

Field “ReferenceNo”, which fetches the translation:

<FormattedText Name="ReferenzNr"> <Code>$.translations.getFormattedText("FormattedTexts.Paragraphs.BoldNormalHeader", { bold: $.formattedText.fromText("Header_Step"), // Referenz auf das Text-Field "Header_Step" normal: $.formattedText.fromText($("Forms.ReferenzNr")), })</Code> </FormattedText> <Text Name="Header_Step" Value="Referenz-Nr:" />

Result in Word

Field “EnclosuresBox”

Covers the following contents:

  • Defined word style

  • Control structure

  • Loop

Global translation with Id: FormattedTexts.EnclosuresBox

{{#if enclosures}} <p><b>Beilagen</b></p> {{#each enclosures}} <p data-word-style-id="NormalNoSpacing">&#8211;&#009;{{this}}</p> {{/each}} {{/if}} {{#if copies}} <p><b>Kopie an</b></p> {{#each copies}} <p data-word-style-id="NormalNoSpacing">&#8211;&#009;{{this}}</p> {{/each}} {{/if}} {{#if empty}} <p data-word-style-id="InvisibleLine">&#160;</p> {{/if}}

Field “EnclosuresBox”, that fetches the translation:

<FieldsGlobalFields> <FormattedText Name="EnclosuresBox"> <Code><![CDATA[ function main() { let enclosures = []; // Create array that will contain multiple inserts if($("Forms.Enclosures")){ // if the user has entered something in the field... enclosures = $("Forms.Enclosures").split("\n"); // fill the array with every element that comes before a line break } let copies = []; // Create array that will contain multiple entries if($("Forms.CopyTo")){ // if the user has entered something in the field... copies = $("Forms.CopyTo").split("\n"); // fill the array with every element that comes before a line break } // If both arrays have the length 0 (and are therefore empty), the value is 'true' let empty = (enclosures.length === 0 && copies.length === 0) ? "true" : ""; return $.translations.getFormattedText("FormattedTexts.EnclosuresBox", { enclosures: enclosures, copies: copies, empty: empty }); } ]]></Code> </FormattedText> </FieldsGlobalFields>

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.

image-20240116-094938.png

Code

Accessing to the Word content works like this:

<FormattedText Name="FooterFTSnippet"> <Code>$.snippets.getFormattedText("FooterFTSnippet")</Code> </FormattedText>

Typ WordContent

Examples

WordContent-Field Introduction

<WordContent Name="Introduction"> <Code> $.snippets.getWordContent('Introduction'); // Parameter is snippet key </Code> </WordContent>

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:

<WordContent Name="ContractTitles"> <Code>$.snippets.getWordContent("Introduction", { dateToday: $("Forms.Date"), // Placeholder is filled with Forms field guests: $("Guests") } // filled with field )</Code> </WordContent>

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.

The content controls of snippt placeholders are yellow..

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

SaveWordContentSnippet.mp4

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.

ATTENTION
Make sure that you are in administration mode, because WordContents can only be stored in the template snippets. The reason for this is that WordContents are a technical type of text module.

The template text modules are only visible to template administrators.

Users continue to save their personal text modules as classic OpenXml snippets.

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

In Fields, only the key of a WordContent is accessed.

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.

        Properties of the created WordContent text module

         

  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

    5. <WordContent Name="InvitationSnippet"> <Code> // Snippet of type WordContent with two parameters "EventName" and "EventDate" $.snippets.getWordContent('Invitation', { EventName: $('Forms.EventName'), EventDate: $.getDateAsString('Forms.EventDate') }); </Code> </WordContent>
  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:

    Content in the WordContent field in the created document (left) and Forms dialogue (right)

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

<FormattedText Name="Footer"> <Code> function main() { // Snippet of type FormattedText, parameter is snippet key let ftSnippet = $.snippets.getFormattedText("FooterFTSnippet"); // Translation of type FormattedText, parameter is Id of the translation entry let ftTranslation = $.translations.getFormattedText("FormattedTexts.FooterBold"); // Translation of type FormattedText with three parameters ‘firstName’, ‘lastName’ and ‘function’ let lastName = $("Forms.LastName"); // Translation of type FormattedText with parameter; parameter is snippet key and a list of parameters let ftAdvanced = $.translations.getFormattedText("FormattedTexts.FooterBoldWithParams", { firstName: $("Forms.FirstName"), // Forms lastName: lastName, // Variable function: "Doctor" // Fixtext }); // Goal: link all variables created above with Builder: Information about Builder below return $.formattedText .getBuilder() .append(ftSnippet) .append(ftTranslation) .append(ftAdvanced) .build(); } </Code> </FormattedText>

Result in Word

image-20240116-094538.png

FormattedText-Field HeaderContact with Builder

JS-Code

<FormattedText Name="HeaderContact"> <Code> function main(){ function main(){ let job = $("Profile.User.Function"); let name = $.joinNonEmpty(" ", $("Profile.User.Title"), $("Profile.User.FirstName"), $("Profile.User.LastName")); let address = $("Forms.Address"); let refCityDate = $.joinNonEmpty("\n", $("RefNrForm"), $("Profile.User.Postal.City") + ", " + $.getDateAsString("Forms.Date")); // Builder return $.formattedText.getBuilder() .append($.translations.getFormattedText("FormattedTexts.Paragraphs.NormalBoldHeader", { bold: "", // bold erscheint danach nicht normal: job })) .append($.translations.getFormattedText("FormattedTexts.Paragraphs.BoldNormalHeader", { bold: name, normal: address })) .append($.translations.getFormattedText("FormattedTexts.Paragraphs.NormalBoldHeader", { bold: "", // bold erscheint danach nicht normal: "\n" + refCityDate + "\n\n" })) .build(); } </Code> </FormattedText>

Result in Word

image-20240815-151210.png

WordContent-Field HeaderContact with Builder

JS-Code

<WordContent Name="HeaderContact"> <Code> function main(){ let job = "\n" + $("Profile.User.Function"); let name = $.joinNonEmpty(" ", $("Profile.User.Title"), $("Profile.User.FirstName"), $("Profile.User.LastName")); let addressSnippet = $.snippets.getWordContent("AddressSnippet", { address: $.wordContent.fromText("Forms.Address"); }); let refCityDate = $.joinNonEmpty("\n", $("RefNrForm"), $("Profile.User.Postal.City") + ", " + $.getDateAsString("Forms.Date")); let nameFT = $.translations.getFormattedText("FormattedTexts.Normal", { normal: name }); // Builder return $.wordContent.getBuilder() .append($.wordContent.fromText(job)) .append($.wordContent.fromFormattedText(nameFT)) .append($.snippets.getWordContent(addressSnippet)) .append($.wordContent.fromText("\n" + refCityDate + "\n\n")) .build(); } </Code> </WordContent>

Result in Word

image-20240815-151146.png

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

The CheckBox content control cannot be inserted into templates:
Fields | Overview of field type per Office application

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.

<YesNo Name="HasSignerMain"> <Code>$("Forms.SignerMain") !== null</Code> </YesNo>

More extensive example

In this example, several conditions are checked:

<YesNo Name="SignerIsRegierungsrat"> <Code> function main(){ let rr = $.translations.getText("Staff.RRFunction"); // get global translation return $("HasSignerMain") ? ($("Forms.SignerMain.User.Function") === rr ? true : false) : false; } </Code> </YesNo>
  • $('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

<Picture Name="SignerMainSignature"> <Code>$("Forms.SignerMain.User.Sign")</Code> </Picture>

Get the logo of an organisation

<Picture Name="Logo"> <Code>$("Profile.Org.Logo")</Code> </Picture>

Get image from the files (asset)

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

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:

<FieldsGlobalFields> <Text Name="Subject"> <Code>$("Forms.Subject")</Code> </Text> <FormattedText Name="CityDate"> <Code>$.translations.getFormattedText("FormattedTexts.Paragraph.BoldNormal", { bold: $("Profile.User.Postal.City"), normal: $("Date") })</Code> </FormattedText> <WordContent Name="Introduction"> <Code>$.snippets.getWordContent("Introduction")</Code> </WordContent> <Date Name="Date"> <Code>$("Forms.Date").Value</Code> </Date> <Picture Name="UserImage"> <Code>$("Profile.User.ProfileImage")</Code> </Picture> <Text Name="IsGLMitgliedText"> <Code>$("IsGLMitglied").toString()</Code> </Text> <YesNo Name="IsGLMitglied" Value="false" />+ <!-- A YesNo field ‘IsPresident’ with the value ‘true’ is retrieved here --> <GlobalFields Key="Fields.IsPresident" /> </FieldsGlobalFields>

Field configuration in template

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

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

At this point, the fields are displayed as follows:

image-20240729-100751.png

Modification

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

<FieldsConfiguration> <Fields> <GlobalFields Key="Fields.Contract"> <Modifications> <!-- other subject --> <Text Name="Subject" Value="Vertragsnachtrag" /> <!-- supplemented with abbreviation --> <FormattedText Name="CityDate"> <Code>$.translations.getFormattedText("FormattedTexts.Paragraph.BoldNormal", { bold: $("Profile.User.Postal.City"), normal: $.joinNonEmpty(", ", $("Date"), $("Profile.User.Alias")) })</Code> </FormattedText> <!-- other snippet --> <WordContent Name="Introduction"> <Code>$.snippets.getWordContent("IntroductionAppendum")</Code> </WordContent> <!-- Now defined plus 60 days --> <Date Name="Date"> <Code> function main(){ let result = $("Forms.Date").Value; result.setDate(result.getDate() + 60); return result; } </Code> </Date> <!-- Now defined with the image from a Forms field --> <Picture Name="UserImage"> <Code>$("Forms.SignerMain.User.ProfileImage")</Code> </Picture> <!-- set to 'false' --> <YesNo Name="IsGLMitglied" Value="false" /> <YesNo Name="IsPresident" Value="false" /> </Modifications> </GlobalFields> </Fields> </FieldsConfiguration>

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:

image-20240729-101040.png

 

Related content

PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland