You are viewing the documentation for Blueriq 14. Documentation for other versions is available in our documentation directory.

What is it for?

The Text Substitution Language (TSL) is used for adding AttributeExpression, IF/ELSE logic and HTML to certain types of text

TSL stands for “Text Substitution Language”. Its function is to substitute TSL-anchors at run-time by the current attribute value.

Additional formatting of these substituted texts is available, for dates and numbers. Furthermore, by using TSL statements combined with functions and expressions, it enables you to create conditional text blocks.



It is possible to use HTML formatting within TSL. If you choose to do so, make sure that the channel you are using supports HTML.

Where can I use TSL?

The Text Substitution Language (TSL can for example be used in these Blueriq elements: 


Simplified TSL syntax overview: 

TSLSimplified syntax
TSL anchor[[[ ]]]
TSL comment/* */
TSL IF statement[[[IF expr]]] [[[/IF]]]
TSL IF ELSE statement[[[IF expr]]] [[[ELSE]]] [[[/IF]]]
TSL IF ELSEIF statement[[[IF expr1]]] [[[ELSEIF expr2]]] [[[/IF]]]
TSL FOREACH statement[[[FOREACH entity]]] [[[/FOREACH]]]
TSL FOREACH IN statement[[[FOREACH entity IN relation]]] [[[/FOREACH]]]
TSL FOREACH WHERE statement[[[FOREACH entity WHERE condition]]] [[[/FOREACH]]]
TSL FOREACH ORDER BY statement[[[FOREACH entity ORDER BY attr DESC|ASC]]] [[[/FOREACH]]]
TSL sequence[[[#]]]
TSL format[[[expression{format}]]]


TSL anchor


TSL anchors are used to mark attributes or expressions to be interpreted as Text Substitution Language.


So if you want to use an attribute value in a text block, you insert the attribute at the position you want the value to appear and enclose it with Text Substitution Language anchors.

If you want to interpret an expression in a text block, place the expression between the TSL anchors.


Syntax

[text] [[[expr]]] [text]


Inputs

  • expr is an attribute or expression that you want interpreted by the Text Substitution Language
  • text is plain text

Note: You cannot ‘nest’ anchors. So [[[<expr1>[[[< expr2>]]]]]] will result in an error.


Example

Suppose you want to create a welcoming message after a user has logged on to your application. Then you could create the following TSL message:

Welcome [[[user.first_name]]] [[[user.last_name]]]

When user John Doe logged in, the message shown in your application is: “Welcome John Doe”

Back to Top


TSL comment


You can use TSL comment tags in order to add comment to your TSL.


Syntax

/* [text] */


Inputs: 

  • text: to be commented out


Example

/* The statement below creates a list of all user names. 
This is a multi line comment. */
[[[FOREACH user]]]Name: [[[user.last_name]]], [[[user.first_name]]][[[/FOREACH]]]


Back to Top


TSL IF statement


The IF statement enables you to selectively perform tasks within your TSL message, based on some criteria which evaluate to TRUE or FALSE.


Syntax

[[[IF expr]]] message [[[/IF]]]


Inputs

  • expr: is an expression that evaluates to TRUE or FALSE
  • message: is a TSL message, so it can contain plain text and other TSL conditions


Example

Suppose you want to create a welcoming message after a user has logged in to your application. Then you could create the following TSL message:

Welcome [[[IF user.gender = 'male']]]Mr.[[[/IF]]] [[[IF user.gender = 'female']]]Mrs.[[[/IF]]] [[[user.first_name]]] [[[user.last_name]]]

When user John Doe logged on, the message shown in your application is: “Welcome Mr. John Doe”

When user Jane Doe logged on, the message shown in your application is: “Welcome Mrs. Jane Doe”

If the gender is unknown the message will look like this: “Welcome Jane Doe”

Back to Top


TSL IF ELSE statement


The IF ELSE statement enables you to selectively perform tasks within your TSL message, based on some criteria, which evaluate to TRUE or FALSE.

When TRUE executes the task specified in the IF part of the statement, in all other cases executes the task specified in the ELSE part of the statement.


Syntax

[[[IF expr]]] message1 [[[ELSE]]] message2 [[[/IF]]]


Inputs

  • expr: is an expression that evaluates to TRUE or FALSE
  • message1 and message2: are TSL messages, so they can contain plain text and other TSL conditions


Example

Suppose you want to create a welcoming message after a user has logged in to your application. Then you could create the following TSL message:

Welcome [[[IF user.gender = 'male']]]Mr.[[[ELSE]]] Mrs.[[[/IF]]] [[[user.first_name]]] [[[user.last_name]]]

When user John Doe logged on, the message shown in your application is: “Welcome Mr. John Doe”

If the gender is unknown the message will look like this: “Welcome Jane Doe”

Back to Top



TSL IF ELSEIF statement

The IF ELSEIF statement enables you to selectively perform tasks within your TSL message, based on some criteria, which evaluate to TRUE or FALSE.

When TRUE executes the task specified in the IF part of the statement, the task specified in the ELSEIF part of the statement is only executed when the specified criteria are met.


Syntax

[[[IF expr1]]] message1 [[[ELSEIF expr2]]] message2 [[[/IF]]]


Inputs

  • expr1 and expr2: are expressions which evaluate to TRUE or FALSE

  • message1 and message2: are TSL messages, so they can contain plain text and other TSL conditions.


Example

Suppose you want to create a welcoming message after a user has logged in to your application. Then you could create the following TSL message:

[[[IF time.hour >= 0 AND time.hour < 6]]]Good night [[[ELSEIF time.hour >= 6 AND time.hour < 12]]]Good morning [[[ELSEIF time.hour >= 12 AND time.hour < 18]]]Good afternoon [[[ELSEIF time.hour >= 18 AND time.hour ⇐ 23]]]Good evening[[[/IF]]] [[[user.first_name]]] [[[user.last_name]]]

When user John Doe logged on at 8 o’clock am, the message shown in your application is: “Good morning John Doe”

When user John Doe logged on at 7 o’clock pm, the message shown in your application is: “Good evening John Doe”

make sure the entire time.hour range is covered, otherwise the message would simply say “John Doe”

Back to Top



TSL FOREACH statement


Use this statement to repeat a text for each instance of an entity.


Syntax

[[[FOREACH entity]]] message [[[/FOREACH]]]


Inputs

  • entity: is an entity name

  • message: is a TSL message, so it can contain plain text and other TSL conditions


Example

Suppose you want to create an overview of all registered users. Then you could create the following message:

[[[FOREACH user]]]Name: [[[user.last_name]]], [[[user.first_name]]][[[/FOREACH]]]


If you have three registered users: John Doe, Jane Doe and Mr X your user list would look like this: Name: Doe, John Name: Doe, Jane Name: X, Mr

Back to Top



TSL FOREACH IN statement


Use this statement to repeat a text for a subset of instances of an entity.


Syntax

[[[FOREACH entity IN relation]]] message [[[/FOREACH]]]


Inputs

  • entity: is the child entity

  • relation: is the relationship between the parent and the child entity

  • message: is a TSL message, so it can contain plain text and other TSL conditions


Example

Suppose you created a parent and a child entity. The parent has a multivalue relation with the child via the attribute Parent.Has_Children.

If the following instances where created:


Parent instanceParent.NameChild instanceChild.NameChild.Date_of_birth
Parent_1JohnChild_1Kim26-September-1998


Child_2Rick13-May-2000


Child_3Bob3-August-2003
Parent_2DaveChild_4Mary4-June-1982


To create an overview of the children per parent you could create the following TSL message:

[[[FOREACH Parent]]] [[[Parent.Name]]] has children: [[[FOREACH Child IN Parent.Has_children]]] Name: [[[Child.Name]]] Date of birth: [[[Child.Date_of_birth]]], [[[/FOREACH]]] [[[/FOREACH]]]

This results in:

John has children: Name: Kim Date of birth: 26-09-1998, Name: Rick Date of birth: 13-05-2000, Name: Bob Date of birth: 03-08-2003 Dave has children: Name: Mary Date of birth: 04-06-1982

If we leave out the outer iteration [[[FOREACH Parent]]] the system would use the ‘current-instance’ of the Parent entity. In this case we are responsible for selecting an instance of the Parent entity before using this message.

You can combine the IN, WHERE and ORDER BY if you wish. Example:

Persons older than 40: [[[FOREACH Person IN TestEntity.rel WHERE Person.Age>10 ORDER BY Person.Age Asc]]] [[[Person.Name]]], [[[Person.Age]]]; [[[/FOREACH]]]


Back to Top


TSL FOREACH WHERE statement


Use this statement to repeat a text for a subset of instances of an entity.


Syntax

[[[FOREACH entity WHERE condition]]] message [[[/FOREACH]]]


Inputs

  • entity: is the child entity

  • condition: the condition that must hold for an instance

  • message: is a TSL message, so it can contain plain text and other TSL conditions


Example

Suppose you have multiple persons. If the following instances where created:

Person instancePerson.NameAge
Person_1John25
Person_2Peter31
Person_3Angela47
Person_4 Dave 82


To create an overview of all persons older than 40 you could create the following TSL message:

Persons older than 40: [[[FOREACH Person WHERE Person.Age>40]]] [[[Person.Name]]], [[[Person.Age]]]; [[[/FOREACH]]]


This results in:

Persons older than 40: Angela, 47; Dave, 82;


You can combine the IN, WHERE and ORDER BY if you wish. Example:

Persons older than 40: [[[FOREACH Person IN TestEntity.rel WHERE Person.Age>10 ORDER BY Person.Age Asc]]] [[[Person.Name]]], [[[Person.Age]]]; [[[/FOREACH]]]


Back to Top


TSL FOREACH ORDER BY statement


When you use the FOREACH or FOREACH IN statement to repeat a text for multiple instances, you can add the ORDER BY statement to create an ordered list of texts. Add either DESC if you want to sort the list descending or ASC if you want to order the list ascending.


Syntax

[[[FOREACH entity ORDER BY attr DESC|ASC]]] message [[[/FOREACH]]]
[[[FOREACH entity IN relation ORDER BY attr DESC|ASC]]] message [[[/FOREACH]]]


Inputs

  • entity: is the child entity
  • attr: the attribute by which the list of instances will be ordered. DESC stands for descending order. ASC stands for ascending sort order

  • message: is a TSL message, so it can contain plain text and other TSL conditions
  • relation: is the relationship between the parent and the child entity

You can combine the IN, WHERE and ORDER BY if you wish. Example:

Persons older than 40: [[[FOREACH Person IN TestEntity.rel WHERE Person.Age>10 ORDER BY Person.Age Asc]]] [[[Person.Name]]], [[[Person.Age]]]; [[[/FOREACH]]]


Back to Top


TSL sequence


Use this operator to add a sequence-number to each instance in a set of instances.


Note: The sequence operator returns the sequence-number of the FOREACH loop that it is used in. It is not the sequence in which the instances where created. The sequence number starts at 0.


Syntax

[[[#]]]


Input

  • # is the sequence operator


Example

Suppose you want to create an overview of all registered users. Then you could create the following message:

[[[FOREACH user]]][[[# user.last_name]]], [[[user.first_name]]][[[/FOREACH]]]

If you have three registered users: John Doe, Jane Doe and Mr X your user list would look like this: 0 Doe, John 1 Doe, Jane 2 X, Mr

Or you want to create a comma separated list that contains all users:

[[[FOREACH user]]] [[[user.first_name]]] [[[user.last_name]]]
[[[IF # != (COUNT user.last_name - 1)]]], [[[ELSE]]]. [[[/IF]]]
[[[/FOREACH]]] /*end user loop*/

Than the result would look like this:

John Doe, Jane Doe, Mr X.

Back to Top



TSL format

There are two different types of formatting available in TSL, number formats and date formats. Both formats are applied to attributes or expressions in the same way.


Syntax


[[[expression{format}]]]


Inputs

  • expression: is a number or date

  • format: is the number or date formatting


Numbers

In TSL, you can use number formats to change the appearance of numbers, without changing the number behind the appearance. The number format you apply does not affect the actual value. In this context a number can be any of the following basetypes; number, integer, currency or percentage.

The number formats used in TSL are common Java decimal formats. The most commonly used formatting symbols are listed below. For a complete documentation we refer to the online java documentation that is available at https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/text/DecimalFormat.html.


SymbolNameMeaning
0Digit_zerodisplays insignificant zeros if a number has fewer digits than there are zeros in the format
#Digitdisplays only significant digits and does not display insignificant zeros
,Thousand separatorThe integer portion of a number is often split into groups by a grouping separator. Western numbers generally separate numbers into thousands, or groups of 3 digits. However, other styles exist.
.Decimal separatorThe separator between integer and fractional parts of a number
-Minus signSign to specify a negative value
;Sub pattern separatorSeparates formatting for positive and negative numbers
%Percentage signMultiply by 100 and show as percentage
¤(ALT_0164)Currency signUse localized currency symbol (for € sign simply use ALT_0128)
Escape characterUse special characters as ordinary characters


These symbols are used to create a format pattern. How this pattern is created is shown in the examples below.

To use the symbols as ordinary characters in your expression use the escape character.


Note that the formatting depends on the language that is used. This means that when you specify a thousand separator , in the Dutch language this is outputted as a .


Examples

Format patternNumberResult (with English language)Result (with Dutch language)
{0000000000}9813756.19800098137560009813756
{##########}9813756.19898137569813756
{#,###.##}9813756.1989,813,756.29.813.756,2
{#,-##0.00}-9813756.1989,813,756.20-9.813.756,20-
{-#,##0.00}9813756.198-9,813,756.20-9.813.756,20
{#,##0.00;-#,##0.00}9813756.1989,813,756.209.813.756,20
{#,##0.00;-#,##0.00}-9813756.198-9,813,756.20-9.813.756,20
{#,##0.## %}0.880 %80 %
{% #,##0.##}0.8% 80% 80
{¤ #,##0.00}9813756.198£ 9,813,756.20€ 9.813.756,20
{#,##0.00 ¤}9813756.1989,813,756.20 £9.813.756,20 €
{#,##0.00 €}9813756.1989,813,756.20 €9.813.756,20 €
{€ #,##0.00}9813756.198€ 9,813,756.20€ 9.813.756,20
{‘#’#}123#123#123


Dates

In TSL, you can use date formats to change the appearance of dates, without changing the date behind the appearance. The date format you apply does not affect the actual value.

Date patternDescription
dDisplays the day as a number without a leading zero.
ddDisplays the day as a number with a leading zero when appropriate.
MDisplays the month as a number without a leading zero.
MMDisplays the month as a number with a leading zero when appropriate.
yyDisplays the year as a two-digit number.
yyyyDisplays the year as a four-digit number.
hDisplays the hour as a number without a leading zero, based on the 12-hour clock.
HHDisplays the hour as a number with a leading zero, based on the 24-hour clock.
hhDisplays the hour as a number with a leading zero, based on the 12-hour clock.
mmDisplays the minute as a number with a leading zero.
ssDisplays the second as a number with a leading zero.
SDisplays the decisecond
SSDisplays the centisecond
SSSDisplays the millisecond
aDisplays AM for times from midnight until noon and PM for times from noon until midnight.


The following characters are allowed to be used as separators in a date pattern:


CharacterDescription
-Hyphen
,Comma
.Period
;Semicolon
:Colon

Space
/Forward slash
TTime separator

These symbols are used to create a format pattern.


Examples

Format patternExample result
TODAY{dd-MM-yyyy}11-04-2019
NOW{dd-MM-yyyyTHH:mm:ss.SSS}11-04-2019T11:06:56.330

NOW{hh:mm a}

09:40 AM

Back to Top