IGS Universiteit Twente
Datalab

Tailoring

Tailoring

There are many places where it can be desirable to tailor a question to the respondent. From a simple “Hello [first name]” or mr./ms. Prefix to more complicated scenarios. LimeSurvey uses an Expression Manager to implement this, the expression manager is powerful and flexible, but can be a bit daunting to start with. This manual will explain some tailoring examples, from easy to more complicated and get you started. For more in-depth information, consult the LimeSurvey Expression Manager manual pages here.

The basics

Tailoring is done through the expression manager, in the ‘normal’ question fields. For LimeSurvey to be able to know what information should be parsed through the expression manager, any tailoring needs to be surrounded by ‘{‘ ‘}’. A very simple tailored welcome message would look like;

The portion of text between brackets; “TOKEN:FIRSTNAME tells LimeSurvey to insert the value for the token FIRSTNAME. Obviously, this can only be used when you have actually set the token. Other token attributes can be inserted by using LASTNAME, EMAIL, and ATTRIBUTE_1, ATTRIBUTE_2, etc, if you have set additional custom attributes.

Tailoring can be used in questions, but also in question groups and e-mail templates. Note that while LimeSurvey uses the same Expression Manager for tailoring as it does for relevance equations, the relevance field of a question is always interpreted as an expression, and you should not use curly brackets to surround it. In question text, this is not the case, and you need to surround any expressions with curly brackets in order for LimeSurvey to properly parse them.

If statements

But there’s more; we can also tailoring based on earlier questions. Let’s say we have a question asking the respondent’s gender, we can then use the answer to use either Mr. or Mrs. Prefixes like so;

There are two expression blocks in this example, the second simply tells LimeSurvey to insert the respondents lastname token, like in the above example. The first checks for the answer of an earlier question with the code ‘gender’, and inserts the appropriate prefix. If statements work as follows;

The if statement has three variables, the first is the actual test, in this case ‘gender equals male’. The second tells LimeSurvey what action to take if the test is true, in this case it’s a simple string; ‘Mr.’, which LimeSurvey will insert into the question text (or wherever else you have used this expression). The third, optional, variable, tells LimeSurvey what to do if the test is not true, in this case insert the ‘Mrs.’ Prefix. If you do not set a third variable, LimeSurvey will simply do nothing if the test is false.

You can nest multiple if statements if required, for example;

This nested if statement first checks if the respondent’s BMI is lower or equal to 25, and if so returns ‘underweight’, if BMI is higher, the false condition triggers, and another if statement is done, this time testing if the respondent has a BMI lower than 30, if this statement is true, the statement returns ‘normal weight’. This behavior continues all the way to the final test to see if a respondent’s BMI is lower than 40, and if this statement is still not true, there are no further if statements, and the nested if statement returns the value ‘morbidly obese’. If the first if statements tests true (e.g. If the respondent’s BMI was 22), the true condition triggers, and the if statement closes. Since all the other if statements are nested in the false condition, they are never even considered, and only one value is ever returned.

(Note, in computer languages, it is common to use tabs to keep track of nested statements. This is by no means required, but makes it a lot easier to understand complicated nested statements.)

Equations and functions

We can also use mathematical equations; multiplication, division, addition and subtraction are done with the ‘normal’ symbols; ‘*’, ‘/’, ‘+’ and ‘-‘. More complex equations are handled with functions; for example you can use sqrt(x) to calculate the square root of x, and stdev(x, y, z, …) to calculate the standard deviation of any number of values. A complete list of functions can be found here. You can always use parenthesis ‘()’ to group functions and equations and fine-tune the order they execute in.

A special type of question, the equation question, never shows to the participant, but instead allows you to store a calculated variable to the database. For example, in an earlier example we used the variable BMI. Before we can use that, we do actually have to create it and store it. To do this, we would create a question coded BMI, set the type to equation, and then enter the formula for BMI in the question text.

Troubleshooting

When you save a question, you are taken back to the question overview. This shows a marked-up view of the question text and relevance equation, which uses syntax highlighting. Any errors will be marked in red.

The above image shows the basic syntax highlighter, the below images show some errors.

There is a series of mistakes in this expression. First of all, there is a typo in the ‘if’ statement (which is technically a function). There is no ‘iff()’ function, so LimeSurvey throws an error. Notice that gender is also in red. In the next image we have fixed the typo in the if() function, and gender is now highlighted.

There are two problems with the variable gender. First off, we use it too early; the gender question has not been asked yet (in fact it is this very question). Second, the gender question actually has the code SEX (as can be seen above). This is thus an unknown variable, and LimeSurvey throws an error.

We could solve this by moving the gender question to appear before this question, or by setting a custom token attribute (assuming we use tokens). In the next image we have replaced the ‘gender’ variable with the ‘TOKEN:ATTRIBUTE_1’ variable, a custom token attribute we have set up to have M and F values for male and female respondents. Since this token is predefined by us before a user starts a survey (or by the user in the registration process if you have allowed public registration), it is always a valid variable.

There is still an error in this expression; we have forgot to close the if() function. This is something you will likely run into often, especially when you use nested if statements. Thankfully, it is a quick fix; the next image shows no more errors.

However, there are some limits to what the syntax highlighter can do, and we should probably do a test run of the survey.

Turns out there was still one last problem, token attribute 2 does not exist. When we fix this, the question should work like it is supposed to.

Final notes

·

Use the syntax highlighter to your advantage, save often and check for errors in your expressions.

·

Always do manual testruns of your surveys before you put them live, preferably with as many different answer combinations as you can think of.

·

More detailed information can always be found at the LimeSurvey web site. They also have an active forum and IRC channel with helpful people who can point you in the right direction. Alternatively, the DataLab team (see contact information) can also help you out.