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}}
notInvert the inner logic.
{{#if (not author)}}
  This text is visible if there's no author.
{{/if}}
eqUse this to check if two arguments are equal.
{{#if (eq element.title "Cross tab")}}
  The element title is Cross tab!
{{/if}}
neUse this to check if two arguments are not equal.
{{#if (ne element.title "Cross tab")}}
  The element title is not Cross tab!
{{/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
averageAverage two or more numbers.
The average of the numbers 1,2,3,4 = {{average 1 2 3 4}}
Result: (1+2+3+4) / 4 = 2.5
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
currentDateReturn the current date and time in the date format and timezone of the survey owner.
Today is {{currentDate}}.
Result: Today is 08/17/2000 4:14 PM.
.isoAdd to any date to get the date in ISO format. This format is machine readable. Use for prefilling.
Today is {{currentDate.iso}}.
Result: Today is 2000-08-17 16:14.
.utcAdd to any date to get the date in ISO 8601 format in the UTC timezone. This format is machine readable. Use when sending a date to a database or API.
Today is {{currentDate.utc}}.
Result: Today is 2000-08-17T14:14Z.
.dateAdd to any date to get only get the date portion of a date excluding the time.
Today is {{currentDate.date}}.
Result: Today is 08/17/2000.
.timeAdd to any date to get only get the time portion of a date excluding the date.
The time now is {{currentDate.time}}.
Result: The time now is 4:14 PM.
.year
.month
.day
.hour
Add to any date to get only that portion of the date.
You were born in {{contact.dateOfBirth.year}}.
Result: You were born in 1970.
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 before {{dateFormat (dateAdd respondent.dateResponded 3 "day") "D"}}.
Result: We'll reply 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.

dateDiffCalculate the difference between two dates.
Specify the start and end date, along with the unit. The unit can be year, month, day, hour, minute or second.
We've invited you {{dateDiff contact.dateInvited currentDate "day"}} days ago.
Result: We've invited you 3 days ago.

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 modals and popovers to display extra information when the respondent clicks a link. Use modals for longer text or images, use popovers for small bits of information or to explain a word.

Note: these operators are only supported in the survey interface and reports.

OperatorDescription
iconDisplay a small icon. Specify an identifier from Font Awesome.
{{icon "far fa-star"}}

Result:

modalDisplay a link to open a modal.
Click {{modal "here" "This text is inside the modal."}} for more info.
Result: Click here for more info. 
Result inside modal: This text is inside the modal.

Adding an icon is also possible.

Click {{modal "here" "This text is inside the modal." "fas fa-info-circle"}}!
tooltipDisplay a tooltip or text balloon when moving your mouse over something.
This is a {{tooltip "NPS" "Net Promotor Score"}} question. 
Result: This is a NPS question.
Result inside tooltip: Net Promotor Score

Note: since there’s no mouse on mobile, it’s activated by clicking.

By default tooltips are displayed above the link. You can override this position by specifying “left” “right” or “bottom”.

{{tooltip "Click here" "Displayed on the right" "right"}}

Adding an icon is also possible. Add the FontAwesome class of the icon that you want to use as the last parameter.

{{tooltip "Click here" "Some text" "top" "fas fa-info-circle"}}
popoverThe same as a tooltip, but only activated by clicking, not by moving your mouse over it.
This is a {{popover "NPS" "Net Promotor Score"}} question. 
Result: This is a NPS question.
Result inside popover: Net Promotor Score

See the following article for more examples and information:
Tooltips, popovers and modal windows

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. We have a page with useful snippets of CSL code that you can use in your surveys. They are a great starting off point. Even if you do not find code that does exactly what you want, there is often something there, that you can change slightly to achieve what you want.

Survey CSL snippets

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.