Help Center

CheckMarket Scripting Language (CSL)

2 comments

CheckMarket offers a powerful scripting language to enhance your surveys and reports called the CheckMarket Scripting Language or CSL for short.

At its most basic level, it is easy to use. You can use it to place variables in your surveys and reports by selecting them from a drop-down.

At its most advanced, our scripting language gives you tremendous freedom to use complex logic to make calculations, show or hide certain blocks of texts or images and much more. So put on your computational thinking cap and let’s dig in…

Basic concepts

Syntax

Variables in the scripting language are wrapped with double curly brackets, like this: {{someVariable}}. They are case-insensitive, so {{SomeVariable}} is the same as {{someVariable}}.

Hierarchy

The variables are hierarchical, so you can navigate through them by using dot notation from top level objects working your way down. Here are some examples:

  • Report title: {{report.title}}
  • Report filter title: {{report.filter.title}}
  • Title of the first report element: {{report.elements.1.title}}
  • Title of the element with ID 123: {{report.elements.id-123.title}}
  • Label of the first answer option of the question of the first data source of the first report element: {{report.elements.1.data.1.question.answerChoices.1.label}}

Variables

Where can you find the variables that are available?

  • Survey variables: can be found by clicking on the ‘variables’ button on the toolbar in the text editor of your questions, emails, notifications, …
    Here is a list of survey interface variables.

 

  • Report variables: In the ReportBuilder, you can find these variables inside the text editor by using the expand button expand icon in the properties pane under ‘Comment’ on the right. Here you’ll find the ‘Variables’ menu:

Advanced operators

Our scripting language, CSL, supports more than just variables. Using special operators you can implement your own logic. To give you an idea, here’s an example:

{{#if (eq element.title 'Cross tab')}}
  The title of this element is Cross tab.
{{/if}}

In the example above, we check if the report element title is equal to “Cross tab”. If so, we display “The title of this element is Cross tab”. If it’s not, nothing is shown.

List of operators

You can use block operators to show/hide content depending on your own logic.

OperatorDescription
ifUse the if helper to conditionally display a block. If its argument returns false, null, ”, 0 or [], the block will not be visible.
{{#if (and title description)}}
  This text is only visible if there's a title AND a description.
{{/if}}
if + elseSpecify an else block to be displayed if the first condition is not met.
{{#if contact}}
  <h1>{{contact.firstName}} {{contact.lastName}}</h1>
{{else}}
  <h1>Unknown respondent</h1>
{{/if}}
else ifCombine multiple #if blocks using else if. The system will evaluate each ‘if’ in order until it finds one that is true or it reaches the ‘else’. Once one of the ‘if’ blocks is true, the others are ignored even if they are true too.
{{#if contact}}
  <h1>{{contact.firstName}} {{contact.lastName}}</h1>
{{else if respondent.questions.yourName}}
  <h1>{{respondent.questions.yourName}}</h1>
{{else}}
  <h1>Unknown respondent</h1>
{{/if}}
unlessUse the unless helper as the inverse of the if helper. Its content will be displayed if the condition is not met (if the value is either false, null, ”, 0 or [])
{{#unless response}}
  <h3 class="warning">Warning: There's no response!</h3>
{{/unless}}
eachIterate over a list using the built-in each helper. Inside the block, you can use this to reference the element being iterated over, or immediately use underlying properties.
<ul>
  {{#each report.elements}}
    <li>{{title}}</li>
  {{/each}}
</ul>
each + elseTogether with an each operator, you can optionally provide an else section which will display only when the list is empty.
{{#each report.elements}}
  <h2>{{title}}</h2>
{{else}}
  <p>No elements in this list!</p>
{{/each}}

Using logical operators you can check and compare variables. These operators are most often used inside block operators like #if.

Logical operators are wrapped inside parentheses, like this: (eq element.title ‘Cross tab’). The first word is the operator, followed by the arguments. The arguments can be variables, plain text or numbers. Text needs to be wrapped in single quotes.

OperatorDescription
andUse this if all arguments need to be truthy.
{{#if (and author publisher)}}
  This text is only visible if there's an author AND a publisher.
{{/if}}
orUse this if any of the arguments need to be truthy.
{{#if (or author publisher)}}
  This text is visible if there's an author OR a publisher.
{{/if}}
eqUse this to check if two arguments are equal.
{{#if (eq element.title 'Cross tab')}}
  The element title is <i>Cross tab</i>!
{{/if}}
neUse this to check if two arguments are not equal.
{{#if (ne element.title 'Cross tab')}}
  The element title is not <i>Cross tab</i>!
{{/if}}
ltUse this to check if the first argument is less than the second.
{{#if (lt counter 12)}}
  The counter value ({{counter}}) is less than 12!
{{/if}}
gtUse this to check if the first argument is greater than the second.
{{#if (gt counter 12)}}
  The counter value ({{counter}}) is greater than 12!
{{/if}}
leUse this to check if the first argument is less than or equal to the second.
{{#if (le counter 12)}}
  The counter value ({{counter}}) is less than or equal to 12!
{{/if}}
geUse this to check if the first argument is greater than or equal to the second.
{{#if (ge counter 12)}}
  The counter value ({{counter}}) is greater than or equal to 12!
{{/if}}

Use math operators to work with numbers. You can perform calculations or control how numbers are presented.

OperatorDescription
addAdd two or more numbers.
10 + 5 = {{add 10 5}}
Result: 10 + 5 = 15
subtractSubtract two or more numbers.
10 - 5 = {{subtract 10 5}}
Result: 10 - 5 = 5
multiplyMultiply two or more numbers.
10 * 5 = {{multiply 10 5}}
Result: 10 * 5 = 50
divideDivide two or more numbers.
10 / 5 = {{divide 10 5}}
Result: 10 / 5 = 2
sqrtCalculate the square root of a number.
The square root of 25 is {{sqrt 25}}
Result: The square root of 25 is 5
powCalculate the first argument raised to the power of the second argument.
Three to the power of two is {{pow 3 2}}
Result: Three to the power of two is 9
modCalculate the remainder after dividing the first argument by the second.
5 % 4 = {{mod 5 4}}
Result: 5 % 4 = 1
absReturn the absolute value of a number.
The absolute value of -10 is {{abs -10}}
Result: The absolute value of -10 is 10
roundRound a number to the amount of digits specified. If no digits are specified, the number is rounded to 0 digits.
The first rounded value is {{round 25.9999}}, the second is {{round 12.123456 2}}
Result: The first rounded value is 26. The second is 12.12
randomGenerate a random number between the numbers specified.
A random number between 5 and 10 is {{random 5 10}}
Result: A random number between 5 and 10 is 8
countGet a count of the number of items in a list/array.
There are {{count report.elements}} elements in this report
Result: There are 3 elements in this report
kFormat a number to the K notation.
{{k 12468}}
Result: 12K
decExplicitly choose the decimal separator.
{{dec 12.3 ','}}
Result: 12,3

Use date operators to display or manipulate dates and times.

OperatorDescription
dateFormatDisplay a date using a specified format.
Your birthdate: {{dateFormat contact.dateOfBirth 'MMM d yy'}}
Result: Your birthdate: Feb 12 87

Some examples of the formats you can use:

d: 08/17/2000
D: Thursday, August 17, 2000
f: Thursday, August 17, 2000 16:32
F: Thursday, August 17, 2000 16:32:32
g: 08/17/2000 16:32
G: 08/17/2000 16:32:32
m: August 17
r: Thu, 17 Aug 2000 23:32:32 GMT
s: 2000-08-17T16:32:32
t: 16:32
T: 16:32:32
u: 2000-08-17 23:32:32Z
U: Thursday, August 17, 2000 23:32:32
y: August, 2000
dddd, MMMM dd yyyy: Thursday, August 17 2000
dddd, MMMM dd: Thursday, August 17
M/yy: 8/00
dd-MM-yy: 17-08-00
dateAddAdd a certain timespan to a date.
Specify the date, number of units to add (subtracting can be done by using a negative value) and the unit.
The unit can be one of the following: year, month, day, hour, minute and second.
We'll reply to you before {{dateFormat (dateAdd respondent.dateResponded 3 'day') 'D'}}.
Result: We'll reply to you before Thursday, August 17, 2000.

Note: the date is always returned in the ISO 8601 format. Use dateFormat if you’d like to render it in a pretty way.

Use text operators to change how text is rendered.

OperatorDescription
upperCaseConvert the text to upper case letters.
{{upperCase 'Some text'}}
Result: SOME TEXT
lowerCaseConvert the text to lower case letters.
{{lowerCase 'Some TEXT'}}
Result: some text

Use custom temporary variables to split big functions into smaller parts. These variables are not stored anywhere, they’re only temporarily available within the same page.

OperatorDescription
setSave a temporary value. You need to specify a name and the value.
{{set 'mySum' (add 1 2)}}

Note: no result is returned at this time. Use the function below to retrieve this variable.

getRetrieve a temporary value using the name you specified with the set operator.
{{get 'mySum'}}
Result: 3

You can combine all these operators to create more advanced logic. Some examples:

{{#if (lt element.statistics.1.nps element.statistics.2.nps)}}
Your NPS score is lower than the group as a whole. Please review the NPS action plan.
{{/if}}

Translation: ‘If the NPS from your region is less than the benchmark of the whole group, show a message’. That would mean that this element has two data sources, both from the same NPS question, the second data source is set to be a benchmark, so that it will not be affected by the share filter. Data source 1 is affected by the share filter, thus allowing this comparison to be made.

Formatted / unformatted text

It is possible to use formatted text and images (HTML) together with CSL. If you use variables that contain HTML formatting, the content will be displayed using the formatting:

{{survey.questions.myDataLabel.text}}
Example text with a part in italics.

Alternatively, you can also strip the HTML formatting and display everything as plain text by using .unformatted:

{{survey.questions.myDataLabel.text.unformatted}}
Example text with a part in italics.

Need help?

Our CheckMarket Scripting Language offers tremendous possibilities, that cannot all be covered for free by our helpdesk staff. Use of our scripting language, CSL, is included in our plans and we offer consulting by a specialist for clients that need it.

Do you want to create advanced surveys/reports but don’t have the time? Do you need help scripting a survey or report? Let one of our project managers do the scripting for you!

Request a quote

2 comments

Join the conversation
  • allan cheung - April, 2019 reply

    Is there example of how to use the checkmarket scripting language in the survey?

    Pieter De Witte - April, 2019 reply

    Yes, there’s a page about using CSL in surveys.
    You can use these variables in questions, text/media, notifications, etc.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.