Code
The code
tag is available in every field type and offers the option of implementing the output of a field as required using JavaScript.
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.
<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 inmain
.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 += '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 |
|
Field |
|
Profile field: User |
|
Profile field: Organisation |
|
Function calls
Furthermore, $.
initiates the call of a primedocs function: $.myFunction()
It is possible to use general JavaScript functions (e.g. foreach()
on array
s (ObjectCollections) or replace()
on string
s). 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 |
|
FormattedText |
|
WordContent |
|
Date |
|
YesNo |
|
Picture | Image (z. B. |
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 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 |
$ | getDate() | Date |
$.formattedText | fromText() | FormattedText |
$.formattedText | parse() | FormattedText |
$.wordContent | fromFormattedText() | WordContent |
$.wordContent | fromText() | WordContent |
$.translations | getText() | String |
$.translations | getFormattedText() | FormattedText |
$.snippets | getFormattedText() | FormattedText |
$.snippets | getWordContent() | WordContent |
$.formattedText | getBuilder() | FormattedText-Builder |
$.wordContent | getBuilder() | WordContent-Builder |
Getters
API | 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
.
<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
Im Folgenden wird jede Funktion detailliert beschrieben:
Function | Purpose |
---|---|
getText(String id) |
|
getDateAsString(String id) |
|
joinNonEmpty(String separator, String item1, String item2, […]) |
More information here: https://primesoft-group.atlassian.net/wiki/pages/resumedraft.action?draftId=513114113&draftShareId=80b57d2b-c81a-47ab-b7c1-c74d27363d16 |
formatDate(Date date, String format) |
|
formattedText API
Function | Purpose |
---|---|
formattedText.fromText(String text) |
Example with a string:
Example with reference to a field:
|
formattedText.parse(String html, Object parameters) |
Example without named parameters: Example with named parameters: |
formattedText.getBuilder() See chapter Code | Builder API | Creates a builder object in order to append FormattedText or Text to it using the
|
wordContent API
Function | Purpose |
---|---|
wordContent.fromFormattedText(FormattedText ft) |
Example with FormattedText from translation:
Example with FormattedText from snippets
Example with reference to field:
|
wordContent.fromText(String text) |
Example with a string:
Example with reference to a field:
|
wordContent.getBuilder() See chapter Code | Builder API | Creates a builder object in order to append WordContent, FormattedText or Text to it using the
|
translations API
The following functions are available in the translations
group:
Function | Purpose |
---|---|
translations.getText(String id) |
|
translations.getFormattedText(String id, Object parameters) | Retrieves a formatted translation from the global translations.
Example without
Example with
|
snippets API
The following functions are available in the snippets
group:
Function | Purpose |
---|---|
snippets.getWordContent(String key, Object placeholders) |
SnippetPlaceholder can only be filled with strings. Example without
Example with
|
snippets.getFormattedText(String key) |
|
Builder API
The Builder API can be used in a FormattedText
field or a WordContent
field and enables the assembly of Text
s, FormattedTexts
s and WordContent
s 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() |
|
wordContent.getBuilder() |
|
append(WordContent/FormattedText content) |
See detailed example further below |
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
Getters
Funktion | Zweck |
---|---|
$(String name) / $.get(String name) |
|
$.getText(String name) |
|
$.getDate(String name) |
|
$.getFormattedText(String name) |
|
$.getWordContent(String name) |
|
$.getYesNo(String name) |
|
$.getObject(String name) |
|
$.getObjectCollection(String name) |
|
Use customised functions
With GlobalCode
, specially defined functions can also be used in a code
definition. For more information, read here: 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 loopsArrow expressions (
=>
)
Example with CDATA tag and &
instead of &
PrimeSoft AG, Bahnhofstrasse 4, 8360 Eschlikon, Switzerland