Word: Dive into Fields
- 1 Attach fields document function in template editor
- 2 Configure simple field and insert into template
- 3 Information about all field types
- 4 Typ Text
- 4.1 In use
- 5 Typ FormattedText
- 6 Typ WordContent
- 7 Builder (Advanced)
- 8 Typ Date
- 9 Typ YesNo
- 9.1 Examples
- 10 Typ Picture
- 10.1 Examples
- 11 Modify fields
- 11.1 Example
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:
Description of the document function: https://primesoft-group.atlassian.net/wiki/x/YQapAw
Description for creating dynamic content using JavaScript (from here on ‘JS’): https://primesoft-group.atlassian.net/wiki/x/AYCEGg
Description of the concept request
We would particularly like to emphasise the importance of the following chapters:
Description of all field types: Fields | Elements
Which field type can be used in which Office application (Word, Outlook (web), PowerPoint and Excel): Fields | Overview of field type per Office application
Which field type requires which return type: Code | Return value of field types
All primedocs functions that can be used in JS: Code | Functions
How to access which field type in JS: Code | Access to fields
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
The WordContent field allows the dynamic insertion of multiple paragraphs into a template. Together with the Forms document function, more complex templates can be realised and several templates can be consolidated into one.
The paragraphs are either saved in a text module of the WordContent type (see HERE) or output programmatically (see Builder).
A WordContent field can only return WordContent.
The formatting is saved directly in WordContent text modules.
The most important JavaScript functions:
WordContent fields can also use Code | Builder API. More on this below: Word: Dive into Fields | Builder (Advanced).
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
Place the cursor at the desired position in the text section.
Click on the Insert snipet pplaceholder button in the primedocs ribbon.
Enter the name of the placeholder and confirm by clicking on the Insert button.
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
a snippet with the snippet placeholders and with key
Forms fields that should later be in the snippet
a WordContent field that fetches the snippet, fills the parameters with the Forms fields and is later used in the template
Procedure
Create a snippet of type WordContent:
Insert a snippet placeholder with the name EventName.
Insert a second snippet placeholder with the name EventDate.
in Word:
Mark the text section and save it in the desired category:
as type “Word content
set “Invitation” as the key.
Create Forms fields in Forms, see Forms documentation
a text field for
EventName
a date field for
EventDate
Create a WordContent field and place it in the template:
The following code shows a WordContent field
InvitationSnippet
.The snippet with the
Invitation
key is retrieved using thegetWordContent()
function of the Snippet API.To fill the text module placeholders with content, the data is provided via the
EventName
andEventDate
parameters. These can be filled with all types of text (fixed text, form fields, fields, user data, etc.).Insert the previously created Forms fields into the parameters:
The Forms field
Forms.EventName
is transferred to the snippet placeholder EventName.The Forms field
Forms.EventDate
is transferred to the snippet placeholder EventDate. We use thegetDateAsString()
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
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; theHasSignerMain
field returnstrue
orfalse
here.If
$('HasSignerMain')
returnstrue
, the system checks whether the user fieldUser.Function
contains the same value as the global translationStaff.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
GlobalField
s 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