ExpressionScript: quick start

About ExpressionScript

ExpressionScript is the logic of LimeSurvey. An expression is a short formula, such as Q001 == "A002" or sum(Q024_SQ001, Q024_SQ002). LimeSurvey uses expressions to show a question only when it applies, to put earlier answers into texts, to check answers and to calculate values. Expressions name questions by their question codes. Older texts call ExpressionScript by its former name, Expression Manager.

Where you use expressions

Where	What it does	Curly brackets
Condition designer in Question settings, and Condition in Group settings	Shows a question or a group only when the expression is true	No
Texts: question text, help text, welcome screen and end screen	Shows an answer or a calculated value in the text	Yes
Question validation equation (Advanced > Logic)	Accepts the answer only when the expression is true	No
An Equation question	Calculates a value and stores it with the response	Yes

In a text, curly brackets mark the expression: You said {homehours} hours. A field that only holds an expression, such as a condition, takes it without brackets: Q001 == "A002".

Write an expression

Name a question by its code, for example homehours. For a subquestion, add its code: Q024_SQ001. Codes are case-sensitive. See Question and answer codes.
Answer code or answer text: Q001 is the code of the chosen answer, for example A002. Q001.shown is the text the participant saw, for example Laptop.
Compare with ==, !=, <, <=, > and >=, or with the words eq, ne, lt, le, gt and ge. Put text in quotes: Q001 == "A002".
Combine with and and or, and use ! for not: !is_empty(Q010) and Q011 > 0.
Calculate with +, -, *, / and brackets: (Q010 + Q011) / 2.

Note: In question texts, write comparisons as words: ge instead of >=, lt instead of <. The text editor saves < and > as HTML code, and the expression then fails in the survey. In the Expression script of a condition, < and > work as usual.

Add a condition as an expression

Select the question.
In Question settings, under Condition designer, click the field Enter expression... or the square icon next to it. The Expression script editor opens.
Type the expression, for example !is_empty(homehours) and totalhours > 0, and click Apply.

LimeSurvey confirms with Condition applied successfully, and the question gets a C badge.

The editor with three areas numbered 1 to 3, expressions in a question text, the C badge and the condition field of the Condition designer

In the picture: 1 expressions in a question text, highlighted in the editor, 2 the C badge of a question with a condition, 3 the condition field. The condition designer with + New logic builds the same expression for you. See Conditions: show a question only when it applies.

Functions you'll use most

Function	What it returns	Example
`if(test, a, b)`	`a` when the test is true, otherwise `b`	`if(Q001 == "A002", "laptop", "phone")`
`is_empty(x)`	True when the question has no answer	`!is_empty(Q010)`
`sum(a, b, ...)`	The total	`sum(Q024_SQ001, Q024_SQ002)`
`count(a, b, ...)`	How many of them are answered	`count(Q024_SQ001, Q024_SQ002)`
`round(x)`	`x` rounded to a whole number	`round(Q010 / Q011 * 100)`
`strlen(x)`	The number of characters	`strlen(Q002) >= 20`
`rand(a, b)`	A random whole number from `a` to `b`	`rand(1, 3)`

The full list is in the ExpressionScript reference of the LimeSurvey manual.

Example: calculate a share and comment on it

This page asks for two numbers, calculates a share and shows a sentence that depends on it.

Add a Numerical input question with the code homehours: "How many hours per week do you work from home?"
Add a Numerical input question with the code totalhours: "How many hours do you work per week in total?"
Add an Equation question with the code share and the text {round(homehours / totalhours * 100)}. Set Always hide this question (Advanced > Display) to Yes.
Add a Text display question with this text: You work {share}% of your hours from home. {if(share ge 50, "Most of your work happens at home.", "Most of your work happens elsewhere.")}
Give the Text display question the condition !is_empty(homehours) and totalhours > 0, so it appears only when both numbers are there.

The survey preview with three areas numbered 1 to 3, the two answers and the sentence with the calculated share

In the preview: 1 and 2 the answers, 3 the sentence with the calculated share. The sentence updates while participants type.

Tip: Conditions, validation and calculations work in the running survey, not in the editor. Test them with the eye icon in the top bar.

Next steps

FAQ

Do I use curly brackets in a condition?

No. A condition or a validation equation is an expression as a whole, so you type it without brackets. Curly brackets are only for expressions inside texts.

My survey shows an expression with an error instead of the result. What do I check?

Check the question codes: they must exist, match upper and lower case, and belong to questions before the text. If the expression compares with < or >, write lt, le, gt or ge instead.

Can an expression use an answer from the same page?

Yes. Texts and conditions update while participants answer, as long as the question with the answer comes first.

My JavaScript in a question text stops working. Why?

ExpressionScript reads text in curly brackets as an expression. Leave a space or a line break after every { and before every } in your script. See Add JavaScript to your survey.

ExpressionScript quick start | LimeSurvey