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
TIP
Read the technical documentation first: https://primesoft-group.atlassian.net/wiki/pages/resumedraft.action?draftId=511934473&draftShareId=cc5e663d-b237-406d-a5eb-8ae0e131ee35
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:
<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>–	{{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">–	{{this}}</p>
{{/each}}
{{/if}}
{{#if copies}}
<p><b>Kopie an</b></p>
{{#each copies}}
<p data-word-style-id="NormalNoSpacing">–	{{this}}</p>
{{/each}}
{{/if}}
{{#if empty}}
<p data-word-style-id="InvisibleLine"> </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
.
Code
Accessing to the Word content works like this:
<FormattedText Name="FooterFTSnippet">
<Code>$.snippets.getFormattedText("FooterFTSnippet")</Code>
</FormattedText>
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 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
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.
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
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.
Properties of the created WordContent text module
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
<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>
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
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
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
Typ Date
See technical documentation: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61408865/Fields#Date
NOTE
Please note: Fields | Overview of field type per Office application
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; 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
<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
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
:
<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:
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:
Related content
PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland