ExpressionScript Engine - Snelstartgids

Snelstartgids

Within LimeSurvey, you can further customize your surveys via the usage of the ExpressionScript (short: ES). Sidenote: "ExpressionScript was named Expression Manager (EM) in earlier version. If you read Expression Manager somewhere, it is just the old name of ES."

ES can be used to specify the following:

1. Navigatie/Vertakking : door de antwoorden van de deelnemer kan de volgorde van de vragen worden gewijzigd.
2. Maatwerk : je kunt de vraag opmaken. Bijvoorbeeld antwoorden op eerdere vragen gebruiken, of zinnen opbouwen met een vervoeging van gegevens van de deelnemer (bijvoorbeeld leeftijd of sekse) of bepalen hoe een rapport (beoordelingsscore of maatadvies) wordt samengesteld.
3. Validatie : ervoor zorgen dat de antwoorden aan gestelde voorwaarden voldoen, zoals een minimum of een maximum of voldoen aan een patroon.

In ES wordt een eenvoudige manier gebruikt om deze functies te specificeren. Bijna alles wat je kunt schrijven als een standaard mathematische vergelijking is een geldige expressie.

ES ondersteunt op dit moment 70 functies, bovendien kunnen er eenvoudig meer functies ondersteunt worden. Je hebt ook toegang tot variabelen met leesbare namen (anders dan bij SGQA-identifiers).

Hieronder beschrijven we waar ES meestal voor wordt gebruikt.

Relevantie (Controle Navigatie/Vertakking)

Bij sommige enquête-systemen wordt een "Goto Logic" gebruikt, als de deelnemer bij Vraag1 optie C kiest, ga dan naar Vraag5. Het controleren van een dergelijke enquête is lastig. Ook bij het verplaatsen van vragen kan er gemakkelijk iets verkeerd gaan waardoor de enquête niet meer werkt. In LimeSurvey wordt ES gebruikt waardoor er gebruikt gemaakt wordt van Booleanse algebra om de condities te specificeren wanneer een vraag getoond moet worden. Alleen als de vraag relevant is wordt de vraag getoond. Als de vraag niet relevant is, dan wordt die niet getoond en wordt de waarde "NULL" vastgelegd in de database.

NB: Dit kan op een vergelijkbare manier in de Conditie-editor worden gedaan, maar in ES kun je gemakkelijk meer complexe en krachtige criteria gebruiken (en dan met een variabele-naam in plaats van een SGQA-identifier).

---

Om het begrip relevantie beter te begrijpen, gebruiken we een voorbeeld met een enquête waarin de BMI (Body Mass Index) wordt bepaald van de deelnemer. Voorbeeld downloaden.

The relevance equation is shown below in the Relevance column after the variable name. The relevance values of weight, weight_units, height, and height_units are all 1 (default value), meaning that those questions are always displayed. However, the relevance for BMI is {!is_empty(height) and !is_empty(weight)}, which means that BMI will only be computed if the subject enters a value for both height and weight (thereby avoiding the risk of getting a zero error). Also, question "Report" is only shown if the respondent answers all four main questions (height, heightunits, weight, weightunits).

NB: Het bovenstaand plaatje staat in het enquête logica-bestand, de functie om de enquête op syntaxfouten te controleren voor het activeren.

De relevantievergelijking wordt getoond en kan gewijzigd worden:

• op vraagniveau
• op vraaggroepniveau

Bekijken / Wijzigen relevantie op vraagniveau

Deze vergelijking bepaalt de index voor het lichaamsgewicht (BMI). De vraag wordt alleen getoond als de deelnemer eerst het gewicht en de lengte heeft ingevuld.

Het wijzigscherm voor de vraag over het BMI.

De accolades worden niet gebruikt als je een relevantie-vergelijking invult.

Bekijken / Wijzigen relevantie op groepsniveau

We gebruiken nu een voorbeeld met een eenvoudige telling. Voorbeeld downloaden.

Op de beginpagina vragen we met hoeveel mensen je, de deelnemer, samenleeft, hiervoor we gebruiken we de variabele cohabs. De volgende pagina wordt alleen getoond als je met iemand samenleeft. De velden p2name, p2age. p2sum worden ook alleen dan getoond als er een respons is.

De groep heeft dus ook relevantie-criteria op vraagniveau. Een vraag wordt soms alleen gesteld als je een bepaalde voorgaande vraag hebt beantwoordt (zie vraag p2age, als vraag p2name is beantwoord). De relevantie voor de groep en de vraag worden vanzelf gecombineerd. Een vraag in de groep wordt alleen gesteld als de groep relevant is.  Binnen de groep worden alleen de relevante vragen gesteld.

Het scherm voor het wijzigen van de relevantie op groepsniveau van Cohabitant 2:

Note that you do not use the curly braces when you enter a relevance equation.

Tailoring/Piping

ES lets you easily do simple and complex conditional tailoring. Sometimes you just need a simple substitution, like saying, "You said you purchased [Product]. What did you like best about it?". Sometimes you need conditional substitution like "[Mr./Mrs.] [LastName], would you be willing to complete our survey?". In this case, you want to use "Mr. or Mrs." based on the person's gender. Other times you need even more complex substitution (such as based upon a mathematical computation). ES supports each of these types of tailoring/piping.

Conditional Equations

The Body Mass Index example shows the ability to compute a person's BMI, even while letting them enter their height and weight in two different units (cms vs inches and kgs vs lbs):

In this case, weightkg is {if(weightunits == "kg", weight, weight * 0.453592)}. This "if()" function means that if the subject enters the weight using kilograms, use that value, otherwise multiply the entered value (pounds is the alternative) by 0.453592 to convert it to kilograms. The heightm variable uses a similar approach to compute the person's height in meters (height in cms/100), even if he has entered his height in inches (1 meter=3.28084 inches).

BMI is computed as: {weightkg / (heightm * heightm)}.

Lastly, the report conditionally tailors the message for the subject, telling her what he entered. (e.g., "You said you are 2 meters tall and weight 70 kg.")

In the below image, weightstatus uses nested "if()" statements to categorize the person as underweight to severely obese. You can see its equation by checking its logic:

From the edit window for this question, you can see two things:

1. Tailoring must surround expressions with curly braces
2. Expressions can span multiple lines if, as in this case, you want to make it easier to read the nested conditional logic.

Tailored Questions, Answers, and Reports

Note: Dynamic tailoring may not work if answer options are made available in select boxes on the same question page. This results from the fact that tailoring inserts a <span> tag which is not valid inside select options.

The BMI report looks like this:

Here is the edit window for the same question.

Anything within curly braces is treated as an expression, being syntax-highlighted (color coded) in the prior image. If you have any typos (such as misspelled or undefined variable names or functions), ES would show an error. In our below example:

• heightunit.shown is an undefined variable name (it is actually heightunits.shown) and
• "rnd()" is an undefined function (the proper function name is "round()").

In both cases, the errors are located within a red box to make it easier to spot and fix them.

You can also see that you can quickly create complex reports, such as a table of entered values or tailored advice.

Please remember that all tailoring must surround expressions with curly braces so that LimeSurvey knows which parts of the question are free text and which should be parsed by the ExpressionScript engine.

Validation

ES controls how most of the advanced question options work. These control aspects like min/max numbers of answers, min/max individual values, min/max sum values, and checking that entered values match specified string patterns. Any value in one of those fields is considered an expression, so you can have min/max criteria with complex conditional relationships to other questions.

In all of these cases, since the advanced question attribute is always considered an expression, you do not use curly braces when specifying it.

The sample surveys page shows many working examples containing a variety of validation expressions.

Expression Manager - presentation

To find out more about the Expression Manager and how you can use different expressions to enhance your survey, please click on the following link.