Code

• 1 Calls in code
  • 1.1 Shortened call
  • 1.2 Detailed call
  • 1.3 Function libraries via "GlobalCode"
• 2 API description
  • 2.1 Access to fields
  • 2.2 Function calls
  • 2.3 Return value of Field types
  • 2.4 Native functions
  • 2.5 primedocs' own functions
    • 2.5.1 Functions with named parameters
    • 2.5.2 Functions in detail per API
• 3 Use customised functions
• 4 CDATA-Tag

---

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

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.

<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 in main must be set explicitly.

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

Function libraries via "GlobalCode"

If you want to provide functions for many fields, this can be controlled and distributed centrally via GlobalCode configurations.

Further information and examples are described on the Global Configurations page.

API description

In a Code element, $ initiates the use of the primedocs API.

Access to fields

With $("[field]") you access Forms fields, Fields and profile fields. 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 a String/text but only Date Forms fields or Date Fields.

Here is an overview:

Field type	Return type
Text	String
FormattedText	FormattedText
WordContent	WordContent
InlineWordContent	InlineWordContent
WordTableRows	WordTableRows
Date	Date
YesNo	Boolean
Picture	Image (e.g. Profile.Org.Logo)
Object	JavaScript object that conforms to the schema.
ObjectCollection	A JavaScript array with objects that match the schema.

Native functions

All native functions can be viewed in the official Mozilla documentation and tried out via a Playground. These can also be used in primedocs Code according to this list.

primedocs' own functions

The following is a sortable table with all primedocs functions: which API they belong to and the respective return type. A function is then always composed of [API].[Function].

API	Function	Return type
$	getDateAsText(…)	String
$	joinNonEmpty(…)	String
$	formatDate(…)	String
$	formatNumber(…)	String
$	getDate(…)	Date
$	getReference(…)	FieldReference
$	getChoiceLabel(…)	String
$	getChoiceValue(…)	String
$.formattedText	from(…)	FormattedText
$.formattedText	fromText(…)	FormattedText
$.formattedText	parse(…)	FormattedText
$.wordContent	from(…)	WordContent
$.wordContent	fromFormattedText(…)	WordContent
$.wordContent	fromText(…)	WordContent
$.inlineWordContent	from(…)	InlineWordContent
$.inlineWordContent	fromFormattedText(…)	InlineWordContent
$.inlineWordContent	fromWordContent(…)	InlineWordContent
$.inlineWordContent	extractParagraphContentFromWordContent(…)	InlineWordContent
$.inlineWordContent	extractParagraphContentFromFormattedText(…)	InlineWordContent
$.translations	getText(…)	String
$.translations	getFormattedText(…)	FormattedText
$.snippets	getFormattedText(…)	FormattedText
$.snippets	getWordContent(…)	WordContent
$.formattedText	getBuilder(…)	FormattedText-Builder
$.wordContent	getBuilder(…)	WordContent-Builder
$.wordTableRows	getBuilder(…)	WordTableRows-Builder

Getters

API	Function	Return type
	$(…)	Field type (depending on Id)
$	get(…)	Field type (depending on Id)
$	getText(…)	String
$	getDate(…)	Date
$	getFormattedText(…)	FormattedText
$	getWordContent(…)	WordContent
$	getInlineWordContent(…)	InlineWordContent
$	getWordTableRows(…)	WordTableRows
$	getReference(…)	FieldReference
$	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:

1. Calling profile data / Forms fields / Fields, see below Key name
2. Fixed text, see below Key info
3. 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.

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

Functions in detail per API

Each function is described in detail below:

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 <br><Text Name="FirstName2"><!-- explicit --><br> <Code>$.getText('Profile.User.FirstName')</Code><br></Text><br><br><Text Name="FirstName1"><!-- implicit --><br> <Code>$('Profile.User.FirstName')</Code><br></Text><br>
getDateAsText(String id)	- Fetches a date field using id and converts it to unformatted text. - Parameter id: Field id. The field behind Id must output a date. - Return type: String <br><Text Name="Date"><br> <Code>$.getDateAsText("Forms.Date")</Code><br></Text><br>
joinNonEmpty(String separator, String item1, String item2, […])	- Combines the items of type String listed 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"
formatDate(Date date, String format)	- Adapts the format of a date object date to the desired format. - Parameter date: Date object, either from a date Forms field, a date Field or from new Date(). - Parameter format: String. Specifies the date format according to this list: Custom date and time format strings - Microsoft Learn. A global translation can also be retrieved in the parameter. - Return type: String $.formatDate($("Forms.Date").Value, "yyyy-MM-dd")
formatNumber(String number, String format)	- Converts the String to the desired format. - Parameter number: String, either from a Forms field or via native JavaScript values. - Parameter format: String. Specifies the number format according to this list: Standard numeric format strings. A global translation can also be retrieved in the parameter. - Return type: String $.formatNumber($("Forms.Price"), "N2")
formatNumber(String number, Object options)	- Formats the String taking into account user-defined options, which are based on the .NET implementation of NumberFormatInfo. The default culture settings are overridden. - Parameter number: String, either from a Forms field or via native JavaScript values. - Parameter options: Object. NumberDecimalDigits, NumberGroupSeparator and NumberDecimalSeparator can be specified. A global translation can also be retrieved. - Return type: String <br>$.formatNumber(11500.43243, { NumberDecimalDigits: 2, NumberGroupSeparator: $.translations.getText("Separator"), NumberDecimalSeparator: "-" }); <br>// Result: 11*500-43 if Separator = *<br>
formatNumber(String number, String format, Object options)	- Formats the String to the desired format taking into account user-defined options, which are based on the .NET implementation of NumberFormatInfo. This can be used, for example, to explicitly override the NumberGroupSeparator, but still format the number as a currency. - Parameter number: String, either from a Forms field or via native JavaScript values. - Parameter format: String. Specifies the number format according to this list: Standard numeric format strings. A global translation can also be retrieved in the parameter. - Parameter options: Object. NumberDecimalDigits, NumberGroupSeparator and NumberDecimalSeparator can be specified. A global translation can also be retrieved. - Return type: String <br>return $.formatNumber(11500.43243, "N2", { NumberDecimalDigits: 2, NumberGroupSeparator: "*", NumberDecimalSeparator: "-" }); <br>// Result: 11*500-43 if Separator = *<br>

formattedText API

Function	Purpose
formattedText.from(Object object)	- Converts a string to a FormattedText. - Parameter text: String or field that returns a string. - Return type: FormattedText Example with a string: $.formattedText.from("A funny sentence.") Example with reference to a field: $.formattedText.from($("Forms.Subject"))
formattedText.fromText(String text)	- Converts a string to a FormattedText. - Parameter text: String or field that returns a string. - Return type: FormattedText 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 Builder	Creates a Builder object in order to append FormattedText or Text to it using the append() function. $.formattedText.getBuilder()

wordContent API

Function	Purpose
wordContent.from(Object object)	- Converts an Object to a WordContent. - Parameter object: Parameter types: FormattedText or Text - Return type: WordContent Example with a string: $.wordContent.fromText("A funny sentence.") Example with reference to a field: $.wordContent.fromText($("Forms.Subject")) Example with FormattedText from Snippet: $.wordContent.fromFormattedText($.snippets.getFormattedText("Introduction")) Example with reference to a field: $.wordContent.fromFormattedText($("IntroductionFT"))
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 Snippet: $.wordContent.fromFormattedText($.snippets.getFormattedText("Introduction")) Example with reference to a 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("A funny sentence.") Example with reference to a field: $.wordContent.fromText($("Forms.Subject"))
wordContent.getBuilder() See chapter Builder	Creates a Builder object in order to append WordContent, FormattedText or Text to it using the append() function. $.wordContent.getBuilder()

inlineWordContent API

Function	Purpose
inlineWordContent.from(Object object)	- Converts an Object to an InlineWordContent. - Parameter object: Parameter types: Text , FormattedText or WordContent - Return type: InlineWordContent If the FormattedText or WordContent contains more than one paragraph, an error is thrown Example with Text: $.inlineWordContent.from("A funny sentence.") Example with FormattedText from Snippet: $.inlineWordContent.from($.snippets.getFormattedText("Demo")) Example with WordContent from Snippet: $.inlineWordContent.from($.snippets.getWordContent("Demo"))
inlineWordContent.fromText(String text)	- Converts a string to an InlineWordContent. - Parameter text: String or field that returns a string. - Return type: InlineWordContent Example with a string: $.inlineWordContent.fromText("A funny sentence.") Example with reference to a field: $.inlineWordContent.fromText($("Forms.Subject"))
inlineWordContent.fromFormattedText(FormattedText ft)	- Converts a FormattedText to an InlineWordContent. - Parameter ft: Parameter type: FormattedText, mandatory. - Return type: InlineWordContent Example with FormattedText from translation: $.inlineWordContent.fromFormattedText($.translations.getFormattedText("FormattedTexts.CopyTo")) Example with FormattedText from Snippet: $.inlineWordContent.fromFormattedText($.snippets.getFormattedText("Introduction")) Example with reference to a field: $.inlineWordContent.fromFormattedText($("IntroductionFT"))
inlineWordContent.fromWordContent(WordContent wordContent)	- Converts a WordContent to an InlineWordContent. - Parameter wordContent: Parameter type: WordContent, mandatory. - Return type: InlineWordContent If the WordContent contains more than one paragraph, an error is thrown. Example with WordContent from Snippet: $.inlineWordContent.fromWordContent($.snippets.getWordContent("Demo"))
inlineWordContent.extractParagraphContentFromWordContent(WordContent wordContent)	- Converts a WordContent to an InlineWordContent. - Parameter wordContent: Parameter type: WordContent, mandatory. - Return type: InlineWordContent If the WordContent contains more than one paragraph, an error is thrown. Example with WordContent from Snippet: $.inlineWordContent.extractParagraphContentFromWordContent($.snippets.getWordContent("Demo"))
inlineWordContent.extractParagraphContentFromFormattedText(FormattedText ft)	- Converts a FormattedText to an InlineWordContent. - Parameter formattedText: Parameter type: FormattedText, mandatory. - Return type: InlineWordContent If the FormattedText contains more than one paragraph, an error is thrown. Example with FormattedText from Snippet: $.inlineWordContent.extractParagraphContentFromWordContent($.snippets.getFormattedText("Demo"))

wordTableRows API

Function	Purpose
wordTableRows.getBuilder() See chapter Builder	Creates a Builder object in order to append a table row to it using the append() function. $.wordTableRows.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: "Subtitle text" } )

snippets API

The following functions are available in the snippets group:

Function	Purpose
snippets.getWordContent(String key, Object placeholders)	- Retrieves a WordContent Snippet with a specific key. - Parameter key: mandatory, parameter type: String, specification of the Snippet key - Parameter placeholders: Parameter type: Object, if there are SnippetPlaceholders, mandatory, List of key-value pairs with String values - Return type: WordContent > ℹ️ Info > SnippetPlaceholders can only be filled with strings. Example without placeholders: $.snippets.getWordContent("Introduction") Example with placeholders: $.snippets.getWordContent("Introduction", { dateToday: $.getDateAsText("Forms.Date"), guests: $("Guests") } )
snippets.getFormattedText(String key)	- Retrieves a formatted text as a Snippet with a specific key. - Parameter key: Parameter type: String, mandatory, specification of the 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, FormattedTexts 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, possibly conditionally.

Functions

Function	Purpose
formattedText.getBuilder()	- Creates a FormattedText Builder object to append FormattedText or Text to it using 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 InlineWordContent, WordContent, FormattedText or Text to it using the append() function. - Parameters: none - Return type: WordContent Builder object - Call in a WordContent Field: $.wordContent.getBuilder()
wordTableRows.getBuilder()	- Creates a WordTableRows Builder object to append table rows to it using the append() function. - Parameters: value for the respective cell in the template row. Values of type string, int, double, FormattedText, WordContent, InlineWordContent are supported. Each call of append() on the same Builder object must be given the same number of parameters. - Return type: WordTableRows Builder object - Call in a WordTableRows Field: $.wordTableRows.getBuilder()
append(InlineWordContent/WordContent/FormattedText/Text content)	- Appends the content of parameter content to the Builder pipeline. - Parameter content: mandatory, parameter type InlineWordContent, WordContent, FormattedText or Text, 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"))
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: FormattedText/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 objects foreign to the Field type must first be converted to the target Field type. For example, in a WordContent Field, the call of a FormattedText must pass through the conversion function fromFormattedText():

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

The same applies to WordContent Fields or FormattedText Fields and the output of text:

.append($.formattedText.fromText(" - mit Builder"))

Example: Builder for WordContent Field and FormattedText Field

<FieldsConfiguration>
  <Fields>

    <WordContent Name="WCSnippetBuilder">
      <Code>$.wordContent.getBuilder() // Builder-Objekt erstellen
            .append($.snippets.getWordContent("Introduction")) // WordContent anhängen
            .append($.wordContent.fromFormattedText($.translations.getFormattedText("FormattedTexts.CopyTo"))) // FormattedText als gl. Übersetzung anhängen
            .append($.wordContent.fromText(" - mit Builder")) // Text anhängen
            .build() // Alles zusammenbauen
      </Code>
    </WordContent>
    
    <FormattedText Name="FTSnippetBuilder">
      <Code>$.formattedText.getBuilder() // Builder-Objekt erstellen
            .append($.snippets.getFormattedText("IntroductionFT")) // FormattedText als Snippet anhängen
            .append($.translations.getFormattedText("FormattedTexts.CopyTo")) // FormattedText als gl. Übersetzung anhängen
            .append($.formattedText.fromText(" - mit Builder")) // Text anhängen
            .build() // Alles zusammenbauen
      </Code>
    </FormattedText>
        
  </Fields>
</FieldsConfiguration>

Getters

Function	Purpose
$(String name) / $.get(String name)	- Fetches 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 Code $("Profile.User.FirstName") / $.get("Forms.Date")
$.getText(String name)	- Fetches a Text. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: Text $.getText("Forms.Subject")
$.getDate(String name)	- Fetches a Date. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: Text $.getDate("DateWrittenOut")
$.getFormattedText(String name)	- Fetches a FormattedText. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: FormattedText $.getFormattedText("OtherFormattedText")
$.getWordContent(String name)	- Fetches a WordContent. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: WordContent $.getWordContent("OtherWordContent")
$.getInlineWordContent(String name)	- Fetches an InlineWordContent. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: InlineWordContent $.getInlineWordContent("OtherInlineWordContent")
$.getWordTableRows(String name)	- Fetches a WordTableRows. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: WordTableRows $.getWordTableRows("OtherWordTableRows")
$.getYesNo(String name)	- Fetches a YesNo. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: YesNo $.getYesNo("Confidentiality")
$.getObject(String name)	- Fetches an Object. - Parameter name: Parameter type: String, mandatory, specification of the name of a field - Return type: Object $.getObject("SingleRecipient")
$.getObjectCollection(String name)	- Fetches an ObjectCollection. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: ObjectCollection $.getObjectCollection("Participants")
$.getReference(String name)	- Fetches a FieldReference. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: FieldReference > ℹ️ Info > A FieldReference can currently only be used with SnippetPlaceholders.
$.getChoiceLabel(String name)	- Fetches the Label of a Choice element. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: Text $.getChoiceLabel("Choice")
$.getChoiceValue(String name)	- Fetches the Value of a Choice element. - Parameter name: Parameter type: String, mandatory, specification of the field name - Return type: Text $.getChoiceValue("Choice")

---

Use customised functions

With GlobalCode, you can also use your own defined functions in a Code definition. For more information, read here: Global Configurations.

---

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 simply 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 &

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