Table of Contents

minLevel	1
maxLevel	3
outline	true
style	nonedefault
type	list
printable	true

The code tag is available in every field type and offers the option of implementing the output of a field as required using JavaScript.

Tip
You can find more examples of fields or an introduction to JavaScript in the Layouter manual.

Calls in code

Within the <Code> element, two variants are possible for executing code.

Shortened call

If the code consists of only one statement, it can be written directly into the block.
The return statement is implicit.

Code Block

language	xml

<Text Name="Footer">
  <Code>$.getText('Profile.User.FirstName')</Code>
</Text>

Detailed call

If the code consists of several statements and/or contains variables, it must be written within the function main().
Within the same code block, other functions can also be defined for use in main.
The return statement is explicitin main must be set explicitly.

Code Block

language	xml

<Text Name="Footer">
  <Code>
    function main() { 
      let firstName = $.getString('Profile.User.FirstName');
      if (firstName == 'Foo') {
        firstName += 'Bar';
      }
      return firstName;
    }
  </Code>
</Text>

API description

In a code element $ initiates the use of the primedocs API.

Access to fields

Forms fields, fields and profile fields can be accessed with $('[field]'). Below is an example for each field type:

Forms field	`<Code>$("Forms.Subject")</Code>`
Field	`<Code>$("Header")</Code>`
Profile field: User	`<Code>$("Profile.User.FirstName")</Code>`
Profile field: Organisation	`<Code>$("Profile.Org.Unit")</Code>`

Function calls

Furthermore, $. initiates the call of a primedocs function: $.myFunction()

It is possible to use general JavaScript functions (e.g. foreach() on arrays (ObjectCollections) or replace() on strings). Consult Mozilla's JavaScript documentation for more information.

Return value of field types

The return value of main() in code must always correspond to the field in terms of data type.
For example, it is not possible to output a date forms field in a text field. Conversely, a date field cannot output string/text but only date forms fields or date fields.

Here is an overview:

Field type	Return type
Text	`String`
FormattedText	`FormattedText`
WordContent	`WordContent`
Date	`Date`
YesNo	`Boolean`
Picture	Image (z. B. `Profile.Org.Logo`)

Functions

The use of functions works according to JavaScript standards:

most functions require one or more arguments, which are specified using parameters. The parameters have a parameter type.
Each function has an explicit return type.

Overview of all primedocs

Native functions

All native functions can be viewed in the official Mozilla documentation and tried out via a Playground. According to this list, these can also be used in primedoc's code.

primedocs' own functions

The following is a sortable table with all primedocs ' own functions: which API they belong to , the target field type (in which field type they may be returned) and the respective return type.

API

A function is then always composed of [API].[Function].

API	Function	Return type

Target field type

$

getText

getDateAsString()

String

Text-based

getDateAsText()

String

Text-based (Text, FormattedText, WordContent)

$

joinNonEmpty()

String

Text-based

$

formatDate()

String

Text-basedsetDate

$

getDate()

Date

All except YesNo

$.formattedText

fromText()

void

All except YesNo

FormattedText

$.formattedText

formattedText.fromText

parse()

FormattedText

$.wordContent

wordContent.

fromFormattedText()

WordContent

$.wordContent

wordContent.

fromText()

WordContent

$.translations

translations.

getText()

String

Text

$.translations

translations.

getFormattedText()

FormattedText

$.snippets

snippets.

getFormattedText()

FormattedText

$.snippets

snippets.

getWordContent()

WordContent

$.formattedText

formattedText.

getBuilder()

FormattedText-Builder

FormattedText

$.wordContent

wordContent.

getBuilder()

WordContent-Builder

WordContent

Getters

builder

API

append()

void

Text, FormattedText, WordContent

builder

build()

void

Text, FormattedText, WordContent

Functions with named parameters

Function	Return type
	$()	Feldtyp (je nach Id)
$	get()	Feldtyp (je nach Id)
$	getText()	String
$	getDate()	Date
$	getFormattedText()	FormattedText
$	getWordContent()	WordContent
$	getYesNo()	YesNo
$	getObject()	Object
$	getObjectCollection()	ObjectCollection

Functions with named parameters

Some functions contain an object with a comma-separated list of key-value pairs as the second parameter. We call the key-value pairs ‘named parameters’.

The values of the key-value pairs can be any type of string. This includes

Calling profile data / Forms fields / Fields, see below Key name
Fixed text, see below Key info
References to variables, see below Key function

In the following example, a global translation of type FormattedText is returned in a field header. The function call to getFormattedText requires the ID of the global translation and, as a second parameter, a list of three key-value pairs with the keys name, info and function.

Code Block

language	xml

<FormattedText Name="Header">
  <Code>
    function main(){
      let myVariable = $("Forms.SignerMain.User.Function");
      return $.translations.getFormattedText("FormattedTexts.FooterBoldWithParams", {
        name: $("Forms.SignerMain.User.FirstName") + " " + $("SignerMainLastName"),
        info: "Fixtext ist auch möglich",
        function: myVariable 
      });
    }
  </Code>
</FormattedText>

Explanation of all functions

Functions in detail per API

Each function is described in detail belowIm Folgenden wird jede Funktion detailliert beschrieben:

Function

Purpose

formattedText.fromText(String text)

Converts a string to a FormattedText.
Parameter text: String or field that returns a string.
Return type: String

Example with a string:

$.formattedText.fromText('A funny sentence.')

Example with reference to a field:

$.formattedText.fromText($('Forms.Subject'))

Function

Purpose

getText(String id)

Fetches unformatted text explicitly via id. Alternatively, an implicit call can also be made (see example).
Parameter id: Field id. The field after id must output a string.
Return type: String

Code Block

language	xml

<Text Name="FirstName2"><!-- explicit-->
  <Code>$.getText('Profile.User.FirstName')</Code>
</Text>

<Text Name="FirstName1"><!-- implicit -->
  <Code>$('Profile.User.FirstName')</Code>
</Text>

getDateAsString(String id)

Retrieves Fetches a date field using id and converts it into a string (= to unformatted text).
Parameter id: Field id. The field behind id must output a date.
Return type: String

Code Block

language	xml

<Text Name="Date">
  <Code>$.getDateAsStringgetDateAsText("Forms.Date")</Code>
</Text>

joinNonEmpty(String separator, String item1, String item2, […])

Combines the items of type String in the list and then separates them with the separator.
Parameter separator: String. Character that acts as a separator between all list elements.
Parameters item1, item2 and ff.: all parameters after separator form a list of strings that are output one after the other.
Return type: String

$.joinNonEmpty(' / ", $("Profile.Org.Title'), $('Profile.Org.Unit')) Result: 'Example company / example department'

More information here: https://primesoft-group.atlassian.net/wiki/spaces/PD/pages/edit-v2/395444225#Funktion-joinNonEmpty() (german)resumedraft.action?draftId=513114113&draftShareId=80b57d2b-c81a-47ab-b7c1-c74d27363d16

formatDate(Date date, String format)

Adapts the format of a date object date to the desired format.
Parameter date: Date object, either from date form field, date field or from new Date().
Parameter format: String. Specifies the date format according to this list: https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings A global translation can also be retrieved in the parameter.
Return type: String

$.formatDate($("Forms.Date").Value, "yyyy-MM-dd")

getDate()

Gets a date object so that you can calculate with it. Return type: Date
See below for more information.

Gets a date object stored in a variable for the function setDate().
Return type: Date

See example: https://primesoft-group.atlassian.net/wiki/spaces/PD/pages/edit-v2/395444225#Beispiel%3A-60-Tage-hinzuf%C3%BCgen (german)

setDate(Date date)

Sets a new value for a date object. No return type.
See below for more information.

Sets a new value date on a date object.
Parameter date: Date object, either from date form field, date field or from new Date().
Return type: void (returns nothing, just does something)

See example: https://primesoft-group.atlassian.net/wiki/spaces/PD/pages/edit-v2/395444225#Beispiel%3A-60-Tage-hinzuf%C3%BCgen (german)

formattedText API

Function

Purpose

formattedText.fromText(String text)

Converts a string to a FormattedText.
Parameter text: String or field that returns a string.
Return type: String

Example with a string:

$.formattedText.fromText('A funny sentence.')

Example with reference to a field:

$.formattedText.fromText($('Forms.Subject'))

formattedText.parse(String html, Object parameters)

Builds a FormattedText from the arguments.
Parameter html: String containing the HTML definition of the FormattedText and any placeholders in the format {{placeholderName}}.
Parameter parameters: Description of all parameters that occur as placeholders in html.
Placeholder names within a FormattedText must be unique.
Return type: FormattedText

Example without named parameters:
$.formattedText.parse('<p data-word-style-id='Quote'>paragraph in built-in "Quote" style</p>');

Example with named parameters:
$.formattedText.parse('<p data-word-style-id='Quote'>{{something}}</p>', { something: 'Paragraph in built-in "Quote" Style' });

formattedText.getBuilder()

See chapter https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/edit-v2/444891137?draftShareId=97cc045f-e537-4739-b64a-36771d63dd94#Builder-API

Creates a builder object in order to append FormattedText or Text to it using the append() function.

$.formattedText.getBuilder()

wordContent API

Function

Purpose

wordContent.fromFormattedText(FormattedText ft)

Converts a FormattedText to a WordContent.
Parameter ft: Parameter type: FormattedText, mandatory.
Return type: WordContent

Example with FormattedText from translation:

$.wordContent.fromFormattedText($.translations.getFormattedText("FormattedTexts.CopyTo"))

Example with FormattedText from snippets

$.wordContent.fromFormattedText($.snippets.getFormattedText("Introduction"))

Example with reference to field:

$.wordContent.fromFormattedText($("IntroductionFT"))

wordContent.fromText(String text)

Converts a text to a WordContent.
Parameter text: Parameter type: String, mandatory.
Return type: WordContent

Example with a string:

$.wordContent.fromText("Ein lustiger SatzA funny sentence.")

Example with reference to a field:

$.wordContent.fromText($("Forms.Subject"))

wordContent.getBuilder()

See chapter https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/edit-v2/444891137?draftShareId=97cc045f-e537-4739-b64a-36771d63dd94#Builder-API

Creates a builder object in order to append WordContent, FormattedText or Text to it using the append() function.

$.wordContent.getBuilder()

translations API

The following functions are available in the translations group:

Function

Purpose

translations.getText(String id)

Retrieves an unformatted translation from the global translations.
Parameter id: Parameter type: String, mandatory, specification of the ID of the translation entry in the global translations
Return type: String

$.translations.getText("Texts.Subject")

translations.getFormattedText(String id, Object parameters)

Retrieves a formatted translation from the global translations.

Parameter id: Parameter type: String, mandatory, specification of the ID of the translation entry in the global translations
Parameter parameters: Parameter type: Object, if the translation has parameters, mandatory:
List of key-value pairs with values according to the translation (types in handlebars: strings, arrays or booleans).
Return type: FormattedText

Example without parameters:

$.translations.getFormattedText("ContractTitle")

Example with parameters:

$.translations.getFormattedText("FormattedTexts.Paragraphs.BoldNormal", { bold: $("Forms.Subject"), normal: "Untertitel-Text" } )

snippets API

The following functions are available in the snippets group:

Function

Purpose

snippets.getWordContent(String key, Object placeholders)

Retrieves a WordContent text module with a specific key.
Parameter key: mandatory, parameter type: String, specification of the text module snippet key
Parameter placeholders: Parameter type: Object, there are SnippetPlaceholders, mandatory,
List of key-value pairs with string values
Return type: WordContent

Info
SnippetPlaceholder can only be filled with strings.

Example without placeholders:

$.snippets.getWordContent("Introduction")

Example with placeholders:

$.snippets.getWordContent("Introduction", { dateToday: $.getDateAsString("Forms.Date"), guests: $("Guests") } )

snippets.getFormattedText(String key)

Retrieves a formatted text as a text module with a specific key.
Parameter key: Parameter type: String, mandatory, specification of the text module snippet key
Return type: FormattedText

$.snippets.getFormattedText("FooterFTSnippet")

Builder API

The Builder API can be used in a FormattedText field or a WordContent field and enables the assembly of Texts, FormattedTextss and WordContents in the sense of a modular system, in which each text, regardless of type, is strung together.

Use

The use of the Builder only makes sense if several text paragraphs have to be strung together conditionally.

Functions

Function	Purpose
formattedText.getBuilder()	Creates a FormattedText builder object to append `FormattedText` or `text` with the `append()` function. Parameters: none Return type: `FormattedText` builder object Call in a `FormattedText` field: `$.formattedText.getBuilder()`
wordContent.getBuilder()	Creates a WordContent builder object to append `WordContent`, `FormattedText` or `Text` with the `append()`function. Parameters: none Return type: `WordContent` builder object Call in a `WordContent` field: `$.wordContent.getBuilder()`
append(WordContent/FormattedText content)	Adds the content of parameter `content` to the builder pipeline. Parameter `content`: mandatory, parameter type `WordContent` or `FormattedText`, depending on which field type you are in. Return type: `WordContent` or `FormattedText` Call on the builder object, e.g. in a `WordContent` field: `builder` `.append($.snippets.getWordContent("Introduction"))` `.append($.wordContent.fromText(" - mit Builder"))` See detailed example further below
build()	Last mandatory function call in a series of builder functions. Triggers the build pipeline and then assembles all 'appended' parts from left to right. Parameters: none Return type: noneFormattedText/WordContent Call on the builder object: `builder.build()`

Application

The following rules apply when using the Builder:

A FormattedText field can only output FormattedText and Text.
A WordContent field can output WordContent, FormattedText and Text.

The non-field type objects must first be converted to the target field type. For example, in a WordContent field, a FormattedText must be called from the conversion function fromFormattedText():

.append($.wordContent.fromFormattedText($.translations.getFormattedText('FormattedTexts.CopyTo')))

The same for WordContent fields or FormattedText fields and the output of text:

.append($.formattedText.fromText(' - with Builder'))

Example: Builder for WordContent field and FormattedText field

Code Block

language	xml

<FieldsConfiguration>
  <Fields>

    <WordContent Name="WCSnippetBuilder">
      <Code>$.wordContent.getBuilder() // Create builder object
            .append($.snippets.getWordContent("Introduction")) // Attach WordContent
            .append($.wordContent.fromFormattedText($.translations.getFormattedText("FormattedTexts.CopyTo"))) // FormattedText as glob. Attach translation
            .append($.wordContent.fromText(" - mit Builder")) // TextAttach anhängentext
            .build() // Alles zusammenbauen
      </Code>
    </WordContent>
    
    <FormattedText Name="FTSnippetBuilder">
      <Code>$.formattedText.getBuilder() // Create builder object
            .append($.snippets.getFormattedText("IntroductionFT")) // FormattedText Attach as snippet
            .append($.translations.getFormattedText("FormattedTexts.CopyTo")) // FormattedText as glob. Attach translation
            .append($.formattedText.fromText(" - mit Builder")) // Attach text
            .build() // Assemble everything
      </Code>
    </FormattedText>
        
  </Fields>
</FieldsConfiguration>

Getters

Funktion	Zweck
$(String name) / $.get(String name)	Gets a field according to the argument. Parameter `name`: Parameter type: `String`, mandatory, specification of the field name Return type: corresponding to the retrieved field see also https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/edit-v2/444891137#Access-to-fields `$("Profile.User.FirstName")` / `$.get("Forms.Date")`
$.getText(String name)	Retrieves a text. Parameter `name`: Parameter type: `String`, mandatory, specification of the field name Return type: Text `$.getText("Forms.Subject")`
$.getDate(String name)	Retrieves a `date`. Parameter `name`: Parameter type: `String`, mandatory, specification of the field name Return type: Text `$.getDate("DateWrittenOut")`
$.getFormattedText(String name)	Retrieves a `FormattedText`. Parameter `name`: Parameter type: `String`, mandatory, specification of the field name Return type: `FormattedText` `$.getFormattedText("Forms.Subject")`
$.getWordContent(String name)	Retrieves a `WordContent`. Parameter `name`: Parameter type: `String`, mandatory, specification of the field name Return type: `WordContent` `$.getWordContentText("Forms.Subject")`
$.getYesNo(String name)	Retrieves a `YesNo`. Parameter `name`: Parameter type: `String`, mandatory, specification of the field name Return type: `YesNo` `$.getYesNo("Confidentiality")`
$.getObject(String name)	Retrieves an `object`. Parameter `name`: Parameter type: `String`, mandatory, specification of the name of a field Return type: `Object` `$.getObject("SingleRecipient")`
$.getObjectCollection(String name)	Retrieves an `ObjectCollection`. Parameter `name`: Parameter type: `String`, mandatory, specification of the field name Return type: `ObjectCollection` `$.getObjectCollection("Participants")`

Use customised functions

With GlobalCode, specially defined functions can also be used in a code definition. For more information, read here: https://primesoft-group.atlassian.net/wiki/spaces/PDTEN/pages/61407710/Global+Configurations#GlobalCode .

CDATA-Tag

The CDATA tag (<![CDATA[My text]]>) ensures that everything between the start and end tag does not go through the parser. This is called ‘escaping’.

Without a CDATA tag, for example, the logical AND operator must be output as an HTML entity: &. By using the CDATA tag, you can only use &, which results in more readable code.

We recommend the use of CDATA tags if the code in the field contains the following:

logical AND operators &
Comparison operators (<, <=, >, >=), e.g. in loops
Arrow expressions (=>)

Example with CDATA tag and & instead of &

Code Block

language	xml

<FieldsConfiguration>
  <Fields>
  
    <YesNo Name="IsPresident">
      <Code><![CDATA[$("Profile.User.Function") === "President" && !$("Profile.Org.Unit")]]></Code>
    </YesNo>
    
    <YesNo Name="IsPresidentNoCDATA">
      <Code>$("Profile.User.Function") === "President" &amp;&amp; !$("Profile.Org.Unit")</Code>
    </YesNo>
    
  </Fields>
</FieldsConfiguration>

Version	Old Version 1	New Version 2
Changes made by	Daniela Zimmermann	Daniela Zimmermann
Saved on	Aug 27, 2024	Oct 01, 2024

Content Comparison

Versions Compared

Key

Calls in code

Shortened call

Detailed call

API description

Access to fields

Function calls

Return value of field types

Functions

Native functions

primedocs' own functions

Functions with named parameters

Functions with named parameters

Functions in detail per API

formattedText API

formattedText API

wordContent API

translations API

snippets API

Builder API

Use

Functions

Application

Example: Builder for WordContent field and FormattedText field

Getters

Use customised functions

CDATA-Tag