Expression Manager Examples

From LimeSurvey Manual
Jump to: navigation, search

Contents


Please help extending this article by adding your own examples. This will help others getting started using the Expression Manager.

Thanks!

Structure of this article

The first part of the article will describe what Expressions can be used for an where to find/add the expression. So if you are not sure where to add an expression it might be a good idea to check this part if the article.

The second part will give examples on how to use Expression.

Categories of Expressions

Since LimeSurvey 1.92 you can use Expressions for the following purposes.

Relevance

Purpose: Hiding question groups/questions

Relevance controls whether a question group or question is shown or hidden. If the result of the Expression is "true" (i.e. 1), the element will be shown. Otherwise (if the result of the Expression is "false" (i.e. 0)) the element will be hidden.

Type Shows/hides Where to find Screenshot
Question group Relevance question group Create/Edit question group -> "Relevance equation:" to be added
Question Relevance question Create/Edit question -> "Relevance equation:" to be added

Validation

Purpose: Validate input/actions on questions/subquestions/answers

Validation controls whether an input into a question or action is valid or not. If the result of the Expression is "true" (i.e. 1), the "good" class will be apllied to the element and validation message. Otherwise (if the result of the Expression is "false" (i.e. 0)) the "error" class will be apllied to the element and validation message. You can declare a style for these cases in the template.css file of your used design template.

Type Validates Where to find Screenshot
Question Validation question Create/Edit question -> "Show advanced settings" -> "Question validation equation" to be added
Subquestion Validation subquestions Create/Edit question -> "Show advanced settings" -> "Sub-question validation equation" to be added

Text output

Purposes: (Do something) and write out some text

An Expression can be used to write out some text. You can for example test or calculate something and specify the output depending on the result of the test or calculation. It can also be used to insert the question text, answers, question type, ... of a question used before the Expression is used. Text output can be used everywhere where a text is shown and can return every kind of results thought you may check if the result is really the one you are looking for.

Use Case Description
Micro tailoring Adjust a text, e.g. write "Mr" or "Mrs" depending on a gender question asked before
Calculation Calculate a value and write it out, e.g. "Your family income is xxx"
Reference Insert a text from an element, e.g. "Your name is xxx. How old are you?"

Equation Question Type

Purposes: (Do something,) (write out some text) and store something in the database

The Equation Question Type can be used to store something in the database. You can do something with an Expression, show the Equation Question (which is similar to a text display) and store the result of the Expression in the database. Link answers the result can be used in the statistic und export feature.

Examples for Expressions

Insert an answer from a previous question

Purpose Insert an answer from a previous question
Type Reference
Example Question one: question code "name"
Question two: question text "NAME, how old are you?"
To do: The answer from question one should be used instead of "NAME"
Expression {name}
Description -
Steps Create/edit question two
Insert "{name}, how old are you?" into "Question"
Screenshot to be added

Create a summary page using placeholders

This tutorial demonstrates how you can create an overview at the end of the survey listing all questions and answers via Expression Manager placeholders. It also shows how to limit such an overview to answered questions only.

A Limesurvey 2.05 test survey can be downloaded here: Media:Limesurvey_Expression_Manager_Placeholder_Demo_Survey.lss

Question types being used here:

1. Single choice questions / single text/numeric questions

  • List (dropdown)
  • List (radio) [L]
  • Yes/No [Y]
  • Long free text [T]
  • Short free text [S]
  • Numerical input [N]
  • Equation [*]


2. Question with subquestions

  • Multiple short text [Q]
  • Multiple choice [M]
  • Array [F]
  • Array (Yes/No/Uncertain) [C]
  • Array (10 point choice) [B]


4. Questions with 2 scales

  • Array dual scale [1]


5. Questions with X and Y scales

  • Array (Numbers) [:]


6. Mask questions

  • Text display [X]


At this simple example our overview will be a simple list with:

- Question text: User's answer

Single choice questions / single text/numeric questions

For all these question types Limesurvey will store a single response:

  • List (dropdown)
  • List (radio)
  • List with comment
  • 5 point choice
  • Yes/No
  • Short free text
  • Long free text
  • Huge free text
  • Numerical input
  • Equation
  • Date
  • Gender

Assuming the question code of the question is q1 we can reference the question text and answer using:

- {q1.question}: {q1.shown}

Example:

- How old are you?: 25


If you want to check whether that question was answered you can put an IF statement around your output:

{if(!is_empty(q1),join("- ",q1.question,": ",q1.shown),"")}

This "translates" to: IF question with code q1 is not empty, output "- " AND the question text AND ": " AND the answer text (the join() function joins elements as a new string; ELSE: output nothing ("" means empty string).

Question with subquestions

For all these question types Limesurvey uses subquestions:

  • Multiple short text
  • Multiple choice
  • Multiple choice with comments
  • Array
  • Array (5 point choice)
  • Array (10 point choice)
  • Array (Yes/No/Uncertain)
  • Array (Increase/Same/Decrease)
  • Array by column

Assuming the question code of the question is q2 and the subquestions are numbered SQ001, SQ002, ..., SQ010, ..., SQ100 (mind the number of zeros, this example is based on sub-question auto-numbering by Limesurvey) we can reference the question text and answer using:

- {q2_SQ001.question}: {q2_SQ001.shown}

- {q2_SQ002.question}: {q2_SQ002.shown}

For multiple choice questions it makes sense to now show the text of the ticked subquestion but to show a Y for each selected option:

- {q2_SQ001.question}: {q2_SQ001}

- {q2_SQ002.question}: {q2_SQ002}

...

Note that currently it is not possible to output the question text of questions with subquestions, see this feature request.

Example 1 (assuming question type is multiple choice)

- Do you know these car brands?

-- Mercedes: Y

-- Audi: N


If you want to output checked items only you can put an IF statement around your output and check for the checkbox value:

{if(q2_SQ001=="Y",join("- ",q2_SQ001.question,": ",q2_SQ001.shown),"")}


Example 2 (assuming question type is Array (10 point choice))

- Please rate the quality of the car brands below on a scale from 1=very bad to 10=very good?

-- Mercedes: 7

-- Audi: 9


If you want to output rated items only you can put an IF statement around your output and check if the current sub question was answered by using:

{if(!is_empty(q3_SQ001),join("- ",q3_SQ001.question,": ",q3_SQ001.shown),"")}

Question with two scales

This applies to the dual scale question type only


Assumed codes used:

  • Question code: q4
  • Subquestion codes: SQ001, SQ002, ...
  • Answer codes scale 1: A1, A2, ...
  • Answer codes scale 2: B1, B2, ...


To refer to the result of a certain subquestion at a certain scale you need to use QuestionCode . '_' . SubQuestionCode . '_' . ScaleID. Note that "ScaleID" is 0 for the first and 1 for the second scale! Example for referring to the answer of the third subquestion and second scale: q4_SQ003_1


Let's output the results for both scales and the first two subquestions

- {q4_SQ001_0.question}: {q4_SQ001_0.shown} / {q4_SQ001_1.shown}

- {q4_SQ002_0.question}: {q4_SQ002_0.shown} / {q4_SQ002_1.shown}

Note that for outputting the subquestion text you need to add the scale ID to the placeholder (though the texts are the same for both scales). So instead of {q4_SQ001.question} we have to use {q4_SQ001_0.question} or {q4_SQ001_1.question}. This was reported as a bug in March 2014 and might change later.


If you want to out results of subquestions with at least one answer only, use this syntax for each subquestion:

{if(count(q4_SQ001_0,q4_SQ001_1)>0,join("- ",q4_SQ001_0.question,": ",q4_SQ001_0.shown," / ",q4_SQ001_1.shown),"")}

Question with X and Y scales

This applies to all matrix questions which allow an answer for every cell (not just every row as shown previously):

  • Array Texts
  • Array Numbers


Assumed codes used:

  • Question code: q5
  • Subquestion codes: SQ001, SQ002, ...
  • Answer codes: A1, A2, ...


To refer to the result of a certain subquestion at a certain column you need to use QuestionCode . '_' . SubQuestionCode . '_' . AnswerCode. Example for referring to the answer of the third subquestion and second column: q5_SQ003_A2


Let's output the results for columns 1-3 of the first two subquestions

- {q5_SQ001_A1.question}: {q5_SQ001_A1.shown} | {q5_SQ001_A2.shown} | {q5_SQ001_A3.shown}

- {q5_SQ002_A1.question}: {q5_SQ002_A1.shown} | {q5_SQ002_A2.shown} | {q5_SQ002_A3.shown}


Since at these question types each cell (combination of X axes and Y axes) equals one answer option, a test for existing data needs to be done for each cell, example:

{if(!is_empty(q5_SQ001_A1),join("- ",q5_SQ001_A1.question,": ",q5_SQ001_A1.shown),"")}


Note that for outputting the subquestion text you need to add the answer code to the placeholder (though the texts are the same for all answer options). So instead of {q5_SQ001.question} we have to use {q5_SQ001_A1.question} or {q5_SQ001_A2.question}. This was reported as a bug in March 2014 and might change later.

Hide question if answer from previous question is empty

_ _
Purpose Hide question if answer from previous question is empty
Type Question Relevance
Example Question one: question code "name", question text "What's your name?"
Question two: question text "{name}, how old are you?"
To do: Hide question two if the textfield of question one is empty
Expression !is_empty(name)
Description is_empty() determines whether a variable is considered to be empty. The "!" negates the result. So if the variable is not empty the Expression will be true and the question is shown
Steps Create/edit question two
Insert "!is_empty(name)" into "Relevance equation:"
Screenshot to be added

Hide question group if answer from previous question is Yes or No

_ _
Purpose Hide question group if answer from previous question is Yes or No
Type Question group Relevance
Example Page one, Question Group one, Question one: question code "PET", question text "Do you have a pet?" -Yes -No
Page two, Question Group two: Title "About your pet(s)"
To do: Show/Hide question group two if answer from question one is Yes/No
Expression PET == "Y"
Description PET is the question code for the question you want to check the answer. If you don't use a suffix EM will use "Qcode.code". So you compare the answer code from the PET question to the value "Y". If the participant answers "Yes" the Expression is true and the question group "About your pet(s)" will be shown.
Steps Create/edit question group two
Insert "PET == "Y"" into "Relevance equation:"
Screenshot to be added

Display value of a mutliple answer input question field

_ _
Purpose Display value of a mutliple answer input question field
Type Reference
Example Question one: question code "AskChildAge", question text "How old are your children?". Subquestions codes -Child1 -Child2 -Child3 - ChildXXX
Question two: question code "ReportChildAge" question text "About your first child: - CHILD1 is AGE1."
Expression {AskChildAge_Child1.question}, {AskChildAge_Child1.value}
Description You want to use the value of a subquestion in a following question. You can access the subquestion value with this kind of expression: QcodeQuestion_QcodeSubquestion.value
Steps Create/edit the second question
Insert this text in the description: "About your first child: - {AskChildAge_Child1.question} is {AskChildAge_Child1.value}."
Screenshot to be added

Validate number of boxes ticked per row at an "Array (Numbers) Checkbox" question

Screenshots Question as shown in survey
Question design
Logic -
_ _
Purpose Validate number of boxes ticked per row
Type Validation
Example Question of type "Array Numbers (Checkbox Layout)"
Expression sum(...)
Description (sum(Test_A_1, Test_A_2, Test_A_3, Test_A_4, Test_A_5) <= X)
determines whether at least X checkboxes in row A are checked.
If you want to check all three rows (A, B, C), you can connect the expression using "&&":
(sum(Test_A_1, Test_A_2, Test_A_3, Test_A_4, Test_A_5) <= X)
&& (sum(Test_B_1, Test_B_2, Test_B_3, Test_B_4, Test_B_5) <= X)
&& (sum(Test_C_1, Test_C_2, Test_C_3, Test_C_4, Test_C_5) <= X)
Steps Create/edit question of type "Array Numbers (Checkbox Layout)"
Insert the above expression into "Question validation equation" at the advanced question settings (you might have to adjust variable namings!)
Sample File limesurvey_survey_53654.lss

Calculate difference between two dates

Purpose Calculate difference between two dates
Type Relevance / Equation question type / Validation
Example Question one (date/time, code: DOB): What is your date of birth?
Question two (date/time, code: datetoday): What is the date today?
Question three (boilerplate): You are XXXX days old.
To do: Calculate and display the number of days between the date given in question 1 and the question 2.
Expression {(strtotime(datetoday)-strtotime(DOB))/60/60/24}
Description strtotime calculates the number of seconds between the 1st of January 1970 and the given date. The above expression calculates the number of seconds between the two given dates. The term "/60/60/24" just calculates the number of days from the number of seconds.

Instead of asking for the "datetoday", you can also use strtotime('now') or simply time(), which directly returns the number of seconds from January 1970 until now (i.e. the time the survey was taken). Thus you could quickly figure out the age of a person in years with the equation {(time() - strtotime(DOB)) / 60 / 60 / 24 / 365.25} In any of these cases, it is critical that the date is entered in a proper format, otherwise the strtotime() function will not work right.

Steps Create two date questions (for the date of birth and for today's date) and a boilerplate question.
In the question text of the boilerplate question insert: "On {datetoday} you were {(strtotime(today)-strtotime(dob))/60/60/24} days days old."

Please note: The function strtotime can work with MANY but not all date formats. If you run into problems set your survey's date format to mm/dd/yyyy or yyyy-mm-dd or dd.mm.yyyy"
Sample File Date_difference.lss
Screenshot to be added

Using Expression Manager for Assessments

Here comes another example on how to use the Expression Manager with Array type questions and assessments: Lets say you have 2 array questions and you want to save the results of the calculation data to your database. It is actually simple, you will need to create and test your arrays and submit a dummy response to see if it works and gives you the results in the completed page.

Implementation details:

  • add a question of type equation
  • add this equation exactly at is it:
    • assume Q1 is your array question code
    • and Q2 is your second array question code
    • equation: {sum(Q1_SQ001.value,Q2_SQ001.value)}

Note that SQ001 is the default the internal code for array subquestions. If you change the subquestion code, adjust the equation above accordingly.