CheckMarket offers a powerful scripting language to enhance your surveys and reports called the CheckMarket Scripting Language or CSL for short.
You can use it in your emails, surveys and reports.
Our scripting language gives you tremendous freedom to use variables (placeholders), make calculations, show or hide certain blocks of text and much more. So put on your computational thinking cap and let’s dig in…
Variables
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:
- Questions in survey: {{survey.questions}}
- The text of the 1st question in survey: {{survey.questions.1.text}}
- Text of the second answer choice in question 1: {{survey.questions.1.answerChoices.2.text}}
- …
Where to find
Survey variables: can be found in the ‘variables’ dropdown 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 
in the properties pane under ‘Comment’ on the right. Here you’ll find the ‘Variables’ menu:
Where can CSL be used?
CSL can be used almost everywhere. In surveys, reports and emails. You can even use it in the subject line or ‘from’ field or ‘to’ field of emails. And by emails, we mean all emails: invitations, reminders, thank-you emails, and notifications. You just type the CSL code directly in your text. A good way to start is to copy and paste an example and then adjust it to meet your needs.
Operators
Our scripting language, CSL, supports more than just variables. Using special operators you can implement your own logic.
In CSL the operator comes first!
To write 1=1 in CSL is:
{{eq 1 1}}The ‘eq’ stands for ‘equals’. behind it we place the two arguments to be checked, separated by a space. All CSL operators work this way!
The ‘eq’ operator expects two arguments. If you need to first do some additional operations, you need to use parentheses to group the arguments like this:
{{eq (add 1 1) 2}}When you have parentheses, the contents inside them are done first. So in this case the ‘add’ is done first and then the result is evaluated by the ‘eq’ operator.
Here is an example using an ‘if’ statement:
{{#if (eq contact.customFields.department 'HR')}}
You work in HR!
{{/if}}In the example above, we check if the custom field called ‘Department’ of the current contact equals ‘HR’. If so, we display a text. If not, nothing is shown.
List of operators
You can use block operators to show/hide content depending on your own logic.
| Operator | Description |
|---|---|
| if | Use the if helper to conditionally display a block. If its argument returns false, null, “”, 0 or [], the block will not be visible. |
| if + else | Specify an else block to be displayed if the first condition is not met. |
| else if | Combine 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. |
| unless | Use 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 []) |
| each | Iterate 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. |
| each + else | Together with an each operator, you can optionally provide an else section which will display only when the list is empty. |
| comments | Use a comment block to add an internal remark, or temporarily prevent some CSL from executing.
|
Using logical operators you can check and compare variables. These operators are most often used inside block operators like #if or in display logic.
A CSL condition is a statement that is either true or false.
Here is a simple example that will return true:
{{eq 1 1}}Translation: The ‘eq’ stands for ‘equals’. In CSL, the operator is always placed first. The other two items are what is being compared so it says ‘1 is equal to 1’. This is true.
Here is an example that will return false:
{{eq 1 2}}It says ‘1 is equal to 2’. This is false.
| Operator | Description |
|---|---|
| eq | Returns true if two arguments are equal. |
| ne | Return true if two arguments are not equal. |
| lt | Returns true if the first argument is less than the second. |
| gt | Returns true if the first argument is greater than the second. |
| le | Returns true if the first argument is less than or equal to the second. |
| ge | Returns true if the first argument is greater than or equal to the second. |
| contains | Returns true if the text of the first argument contains the second argument. |
| and | Returns true if all arguments are true. |
| or | Returns true if any of the arguments are true. |
| not | Reverses the result. Returns true if the inner condition is false and false if the inner condition is true. For example check if a respondent is a contact. This will return true, if they are not a contact. |
Use math operators to work with numbers. You can perform calculations or control how numbers are presented.
| Operator | Description |
|---|---|
| add | Add two or more numbers. |
| subtract | Subtract two or more numbers. |
| multiply | Multiply two or more numbers. |
| divide | Divide two or more numbers. |
| average | Average two or more numbers. |
| sqrt | Calculate the square root of a number. |
| pow | Calculate the first argument raised to the power of the second argument. |
| mod | Calculate the remainder after dividing the first argument by the second. |
| abs | Return the absolute value of a number. |
| round | Round a number to the amount of digits specified. If no digits are specified, the number is rounded to 0 digits. |
| floor | Round a number downward to its nearest whole number. |
| ceiling | Round a number upward to the next whole number. |
| random | Generate a random number between the numbers specified. |
| random + exclude | Generate a random number, excluding certain values. You can add as many excluded values as you like. |
| count | Get a count of the number of items in a list/array. |
| k | Format a number to the K notation. |
| dec | Explicitly choose the decimal separator. |
Use date operators to display or manipulate dates and times.
| Operator | Description |
|---|---|
| currentDate | Return the current date and time in the date format and timezone of the survey owner. |
| .iso | Add to any date to get the date in ISO format. This format is machine readable. Use for prefilling and post-filling. |
| .utc | Add 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. |
| .date | Add to any date to get only get the date portion of a date excluding the time. |
| .time | Add to any date to get only get the time portion of a date excluding the date. |
| .relative | Add to any date to get the relative date, described in words.Tip: use .relative.styled to get the relative date, with the original date as a tooltip. |
| .year .month .month.text .day .dayOfWeek .dayOfWeek.text .hour … | Add to any date to get only that portion of the date. |
| regionalSettings.timezoneOffsetHours | Get the time difference between the survey owner’s local timezone and UTC (Coordinated Universal Time). This is based on the user profile of the survey owner. |
| dateFormat | Display a date using a specified format.Some examples of the formats you can use: |
| dateAdd | Add 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. Note: the date is always returned in the ISO 8601 format. Use dateFormat if you’d like to render it in a pretty way. |
| dateDiff | Calculate 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. |
| dateInTimeZone | Show a date in a specific time zone.Tip: to show the date in a format that is easier to read, also use a dateFormat operator: All supported time zones can be found in our list of time zones. |
Use text operators to change how text is rendered.
| Operator | Description |
|---|---|
| upperCase | Convert the text to upper case letters. |
| lowerCase | Convert the text to lower case letters. |
| trim | Remove whitespace at the start and end of text. |
| replace | Replace a sequence of characters in a string with another set of characters. This operator accepts three terms: The text to be searched, the text to find, and the replacement text: {{replace textToSearch textToFind replaceWith}}This operator is case insensitive and will replace all occurrences of the search term. |
| split | Split text based on a character and returns one part. This operator accepts three terms: The text to split, the character to split the text by (delimiter), index of the part to return: {{split textToSplit characterToSplitOn index}} Here is an example of a comma-delimited string for which we extract a second item: |
| left | Extract the first characters of a piece of text. |
| right | Extract the last characters of a piece of text. |
| substring | Extract characters from a piece of text. This operator accepts three arguments: the text, the index of the first character and the number of characters to extract. Omit the last argument to extract the rest of the text. |
| .unformatted | Remove formatting from text.Place this at the end of a variable to strip the HTML formatting and display everything as plain text |
| urlEncode | Make text suitable for URLs.This should be used when using variables in URLs that may contain spaces, slashes or other special characters. Numbers do not need to be url encoded. |
| jsonEncode | Make text suitable for JSON.This should be used when creating JSON, and the text might contain backslashes, double quotes or other special characters. You can also add ‘.jsonEncoded’ to the end of a variable. For example: |
| hash | Convert text to a 64 character hash code.This operator generates a 64 character hash using the SHA-256 hashing algorithm. |
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.
| Operator | Description |
|---|---|
| icon | Display a small icon. Specify an identifier from Font Awesome. |
| modal | Display a link to open a modal window.Adding an icon is also possible. If your text inside the modal window is long, you can also use the #modal variant: |
| tooltip | Display a tooltip or text balloon when moving your mouse over something.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”. Adding an icon is also possible. Add the FontAwesome class of the icon that you want to use as the last parameter. If your text inside the tooltip is long, you can also use the #tooltip variant: |
| popover | The same as a tooltip, but only activated by clicking, not by moving your mouse over it. |
| lightbox | Show a small version of an image. When it is clicked on, a large version of the image is displayed by filling the screen, and dimming out the rest of the page.{{#lightbox}} Add {{#lightbox}} before and {{/lightbox}} after the image to make it clickable. When clicked, the image is shown full screen. Optionally add multiple images inside the same lightbox to create a gallery. You can also show an image inside a lightbox without using an image, but using text instead: |
| qrCode | Show a QR code of a URL or text snippet. You can optionally provide the size in pixels. The max size is 270.Result: You can also use variables. For instance, if you have a coupon code, in a contact custom field called ‘coupon’, use:
|
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.
| Operator | Description |
|---|---|
| set | Save a temporary value. You need to specify a name and the value.To save a large piece of text, you can also use the #set variant: You can combine text by passing multiple values like this: Note: no result is returned at this time. Use the function below to retrieve this variable. |
| get | Retrieve a temporary value using the name you specified with the set operator. |
Look up information from a contact list as if it was a database and return that information to surveys, notifications, reports.
| Operator | Description |
|---|---|
| contactListLookup | Many users want to look something up in a database. This function lets you use contact lists as a sort of database. For instance, an employee enters their employee number and their department, level and manager are retrieved from a contact list. The contactListLookup function has 4 terms:
You can optionally specify an extra term “contains” to look for a partial match instead of an exact match. For example, “ACME” would also match “ACME Corporation”. But it can go further than contacts (people). Think more abstractly and you can lookup anything. For instance, place a list of stores in a contact list and when someone enters their city, you return the address of the location in that city or someone selects their store and the email address of the store manager is placed in the ‘to’ field for a notification of an unhappy customer. Any kind of lookup becomes possible! |
| queryStringLookup | Extract a querystring parameter from a URL. |
| USStateToAbbreviation | Get the abbreviation for a given US state. |
| USStateFromAbbreviation | Get the name of a US state from its abbreviation. |
You can combine all these operators to create more advanced logic. The most common example, is combining ‘and’, ‘or’ and ‘not’. To do that, you really have to think in terms of true or false. Each item is evaluated and then compared using the operators.
For example:
{{eq 1 1}}This is true. 1 equals 1.
Using and:
{{and (eq 1 1) (eq 2 2)}}This is true. 1 equals 1 and 2 equals 2.
Using or:
{{or (eq 1 2) (eq 2 2)}}This is true. 1 does not equal 1, but 2 does equal 2. ‘or’ is true if any of the terms are true.
Using not:
{{not ( or(eq 1 3) (eq 2 2))}}This is false. 1 does not equals 3 but 2 does equal 2. the ‘not’ reverses the result. Simplified, the code can then be seen as:
{{not (or false true)}}The or is true since one of the terms is true, so you get:
{{not (true)}}‘Not’ makes the true become false:
{{false}}Examples
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.
2 comments
Join the conversationallan cheung - April, 2019
Is there example of how to use the checkmarket scripting language in the survey?
Pieter De Witte - April, 2019
Yes, there’s a page about using CSL in surveys.
You can use these variables in questions, text/media, notifications, etc.