ExpressionScript Hoe te gebruiken

Samenvatting van eerdere uitleg

Als je de index van de LimeSurvey-handleiding tot nu toe hebt gevolgd, betekent dit dat je de LimeSurvey-terminologie al kent. We hebben expressies en variabelen behandeld om te laten zien hoe we onze enquêtes kunnen verbeteren. Daarna zijn we overgegaan op de manieren en betekenissen van syntax highlighting om te laten zien hoe je syntaxisfouten kunt verbeteren.

Met dit als kennis kunnen we naar de voorbeelden gaan en laten zien hoe je in LimeSurvey met expressies kunt werken.

Syntax markeren

De volgende screenshots geven voorbeelden zonder de tooltips. Een tooltip is een informatieve box die wordt weergegeven wanneer je de muisaanwijzer op een vetgedrukt woord plaatst.

Door de markering van de syntaxis is het eenvoudig om correcte gecompliceerde expressies samen te stellen. Hoewel het LimeSurvey-team van plan is om een ​​grafische gebruikersinterface te maken, kun je de bestaande highlighting gebruiken om fouten snel te zien en op te lossen. Je kunt ook de tooltips gebruiken om de nauwkeurigheid van de expressies te valideren (bijv. bevestig dat je de gewenste variabele(n) hebt geselecteerd).

In each of the examples, there are three columns:

1. Source - this is the raw text that you would enter into the LimeSurvey question field
2. Pretty Print - this is the syntax-highlighted equivalent of what you entered
   • Note that Expressions are shown with a tan background, but not surrounded by curly braces in this highlighting.
   • Since EM supports recursive substitution, showing curly braces in the highlighting would cause syntax errors
3. Result - this is the output generated when EM processes the source
   • Everything that can be properly substituted is
   • Expressions with errors are shown in-line, with syntax highlighting. Errors are surrounded by a red-lined box.

Juiste syntaxis

You may find below examples of proper syntax:

1. Values: shows that known variables are color coded according to whether are set on the current page. Old-style INSERTANS:xxxx gets its own color-coding style
2. Question Attributes: shows that dot notation can access some properties of questions
3. Math: shows that basic and complex calculations are supported
4. TextProcessing: shows some of the available text-processing functions
5. Dates: shows two of the available date-related functions
6. Conditional: shows the usage of the if() function. The choices can be nested.
7. Tailored paragraph: you can completely customize a report based upon prior values
8. EM processes within strings: shows that it can do substitutions within strings. This example generates a tailored image name.
9. EM doesn't process curly braces like these: shows that if the curly braces are escaped, or there is a white space between the expression and the curly braces, EM ignores the expression.

Syntaxis met fouten

Here are examples of common errors when typing EM expressions. Note that the tooltips provide additional information.

1. Inline Javascript that forgot to add spaces after curly brace
   • Since "document.write" appears right after a curly brace, EM thinks it is an expression, and red-boxes "document" and "write" since they are undefined variable and functions, respectively
2. Unknown/Misspelled variables, functions and operators
   • Here we forgot that we are using the variable name "gender" instead of "sex", but EM catches that error. It also red-boxes '++', since that is not a supported operator.
3. Warns if use = instead of eq, or perform value assignments
   • Note that the '=' and '+=' are in red text instead of black. If you hover the mouse over them, you will see warnings that you are assigning a value.
4. Wrong number of arguments for functions
   • if() takes 3 arguments, but it has been given 4, so hovering over the red-boxed "if" will explain the error and show the supported syntax
   • sum() takes an unlimited number of arguments, but we had a trailing comma before the closing parentheses, so that is red-boxed
5. Mismatched parentheses
   • This is one of the most common errors when writing expressions.
   • This shows two examples of missing closing parentheses, and one example of having one too many closing parentheses.
6. Unsuported syntax
   • If you use an operator or punctuation that EM does not support, it will red-box it.
7. Invalid assignments
   • Some variables are readWrite and can have their values changed. Others are read-only.
   • If you try to change the value of a read-only variable, you can't. EM will red-box the attempt.
   • If you try to assign a value to an equation or a string, you will also get an error

"Live" voorbeelden van syntaxis markering met actieve tooltips

Bron	Opmaak	Resultaat
Hier is een voorbeeld van OK syntaxis met tooltips Hallo {if (geslacht == 'M', 'Mr.', 'Mevr.')} {achternaam}, het is nu {date ('g: i a', time ())}. Weet je waar je {sum (numPets, numKids)} kinderen en huisdieren zijn?	Here is an example of OK syntax with tooltips Hello if(gender == 'M','Mr.','Mrs.') surname, it is now date('g:i a',time()). Do you know where your sum(numPets,numKids) children and pets are?	Here is an example of OK syntax with tooltips Hello Mr. Smith, it is now 6:07 am. Do you know where your 3 children and pets are?
Here are common errors so you can see the tooltips Variables used before they are declared: {notSetYet} Unknown Function: {iff(numPets>numKids,1,2)} Unknown Variable: {sum(age,num_pets,numKids)} Wrong # parameters: {sprintf()},{if(1,2)},{date()} Assign read-only-vars:{TOKEN:ATTRIBUTE_1+=10},{name='Sally'} Unbalanced parentheses: {pow(3,4},{(pow(3,4)},{pow(3,4))}	Here are common errors so you can see the tooltips Variables used before they are declared: notSetYet Unknown Function: iff(numPets > numKids,1,2) Unknown Variable: sum(age,num_pets,numKids) Wrong # parameters: sprintf(),if(1,2),date() Assign read-only-vars:TOKEN:ATTRIBUTE_1+=10,name='Sally' Unbalanced parentheses: pow(3,4,(pow(3,4),pow(3,4))	Here are common errors so you can see the tooltips Variables used before they are declared: notSetYet Unknown Function: iff(numPets > numKids,1,2) Unknown Variable: sum(age,num_pets,numKids) Wrong # parameters: sprintf(),if(1,2),date() Assign read-only-vars:TOKEN:ATTRIBUTE_1+=10,name='Sally' Unbalanced parentheses: pow(3,4,(pow(3,4),pow(3,4))
Here is some of the unsupported syntax No support for '++', '--', '%',';': {min(++age, --age,age % 2);} Nor '|', '&', '^': {(sum(2 | 3,3 & 4,5 ^ 6)}} Nor arrays: {name[2], name['mine']}	Here is some of the unsupported syntax No support for '++', '--', '%',';': min( ++ age, -- age,age % 2) ; Nor '|', '&', '^': (sum(2 | 3,3 & 4,5 ^ 6)} Nor arrays: name [ 2 ] ,name [ 'mine' ]	Here is some of the unsupported syntax No support for '++', '--', '%',';': min( ++ age, -- age,age % 2) ; Nor '|', '&', '^': (sum(2 | 3,3 & 4,5 ^ 6)} Nor arrays: name [ 2 ] ,name [ 'mine' ]

Voorbeelden maatwerk (bijv.uitbreiding {INSERTANS:xxx})

Aanhef

Gebruik de if-functie om voorwaardelijk te kiezen of 'Mr.' wordt weergegeven of 'Mrs.'.

The syntaxis is if(test,do_if_true,do_if_false).

#	Code	Vraag	Type
1	geslacht	What is your gender?	Gender
2	voorbeeld1	Dear {if (gender == 'M', 'Mr.', 'Mrs.')} Smith, ...	Lange vrije tekst

Zoals hier kan worden opgemerkt, zijn "Mr" en "Mrs" afgestemd op wat de deelnemer als antwoord op vraag "gender" selecteert.

Aanhef in e-mail uitnodiging

U kunt het bovenstaande voorbeeld in de uitnodiging gebruiken met behulp van attributen uit de token-tabel. Gebruik de if-functie om te kiezen of 'Mr.' of 'Mrs.' in de tekst van de e-mail moet worden gebruikt.

De syntaxis is "if(test,do_if_true,do_if_false)".

#	attribuut	waarde
1	Achternaam	Smith
2	E-mailadres	test@test.com
3	ATTRIBUTE_2	M

Tekst in uitnodiging:

Dear {if(ATTRIBUTE_2=='M','Mr','Mrs')} {LASTNAME},

you have been invited to participate in a survey:

https:/...

E-mail:

Voorbeelden berekening /beoordeling

Berekenen beoordelingswaarden bij uitvoering en opslaan van de resultaten

In dit voorbeeld worden alle functies van Expressiebeheer gebruikt, waaronder Relevantie, Maatwerk en het vraagtype Vergelijking.

Het laat ook zien dat ze allemaal JavaScript-enabled zijn, dus als je deze functies op een pagina hebt, zal deze dynamisch veranderen als de deelnemer het antwoord invult of aanpast.

#	Code	Question	Type	Relevance
1	numKids	How many children do you have?	Numerical input	1
2	kid1	How old is your first child?	Numerical input	numKids >= 1
3	kid2	How old is your second child?	Numerical input	numKids >= 2
4	kid3	How old is your third child?	Numerical input	numKids >= 3
5	kid4	How old is your fourth child?	Numerical input	numKids >= 4
6	sumKidAges	{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK)}	Equation	1
7	kidSummary	You said that you have {numKids}. {if(numKids==1,'child','children')}. {if(numKids>1,implode(' ','The sum of ages of your first ',min(numKids,4),' kids is ',sumKidAges,'.'),' ')}	Text display	1

Voorbeeld downloaden.

Hieronder staan schermafbeeldingen van representatieve vragen. Zoals je kunt zien, markeert Expressiebeheer alle velden die mogelijk maatwerk bevatten. Hier ziet u voorbeelden van accentuering van de relevantie, het vraagtype Vergelijking en vervangingen binnen een vraag. U kunt ook vervangingen gebruiken in Help, Groepskoptekstweergave, Welkomsttekst en Afsluittekst.

In het volgende voorbeeld is, omdat de relevantie {numKids> = 2) is, de vraag alleen zichtbaar als de deelnemer aangeeft minstens 2 kinderen te hebben.

Hieronder zie je dat aan elke variabele het .NAOK-achtervoegsel wordt gebruikt. Dit komt door de manier waarop cascade-relevantie wordt ondersteunt. Als u geen .NAOK had, dan zou de som alleen worden berekend als de persoon 4 kinderen heeft (bijv. Als alle variabelen relevant zijn). Het gebruik van .NAOK betekent dat we de som willen berekenen, zelfs als alle of sommige variabelen irrelevant zijn (bijv. "Niet van toepassing" (NA) is goed (OK)).

Het attribuut .NAOK heeft echter alleen invloed op de vraag of variabelen worden doorgegeven aan Expressiebeheer. Als de deelnemer aanvankelijk zegt 3 kinderen te hebben maar dat later aanpast in twee, dan willen we niet de som van de 3 ingevoerde waarden zien, aangezien het derde kind "niet van toepassing is":

Elke afzonderlijke expressie heeft een kleurcode met een lichtbruine achtergrond. Zoals je kunt zien, zijn er hier drie afzonderlijke expressies. De laatste bevat een bericht dat alleen wordt weergegeven als de persoon meer dan één kind heeft.

Eindelijk, de screenshots.

Wanneer de pagina voor het eerst wordt getoond, staat er: "You have 0 children" in plaats van "You have 0 child".

Als ik de waarde voor het aantal kinderen in 1 verander, dan wordt dit direct aangepast, ook al staat het op dezelfde pagina.

Merk op dat de grammatica correct is: "You have 1 child".

Nu verander ik de waarde voor het aantal kinderen in 3 en het resultaat wordt direct:

Let op het voorwaardelijke bericht onderaan: "The sum of ages of your first 3 kids is 0.".

Nu voer ik leeftijden in voor mijn 'kinderen', en ik krijg dit scherm, waarin hun leeftijden worden opgeteld:

Nogmaals, de score en het display worden onmiddellijk bijgewerkt terwijl ik de waarden invoeg, zodat je dit kunt gebruiken om een ​​lopend totaal van een beoordelingsscore te laten zien.

Nu verander ik de waarde voor het aantal kinderen in 2 en de pagina wordt:

Merk op dat hoewel ik een waarde van 5.5 had ingevoerd voor het derde kind, het overzicht nu alleen de waarden van de eerste 2 kinderen optelt.

De reden hiervoor is dat de 3e waarde nu irrelevant is, en irrelevante waarden worden actief genegeerd door Expressiebeheer.

Als ik het aantal kinderen weer op 3 zou zetten, zou ik de eerder ingevulde waarde van 5.5 weer zien. Dus ik verlies geen informatie die ik op de pagina heb ingevuld.

Als ik echter naar een andere pagina blader, worden alle irrelevante waarden NULLED in de sessie en in de database. Dus, als ik de waarde op 2 zou houden, naar de volgende pagina ga en weer terug ga en vervolgens het aantal kinderen op 3 zet, dan ben je de waarde 5,5 kwijt.

Gegevens invullen en zien dat de gegevens dynamisch op dezelfde pagina worden bijgewerkt

Dit voorbeeld toont het maatwerk.

To download this example, click on the following link: Dynamic changes survey example.

Here is what the page looks like initially. You only see the question asking what city you live in:

Once you start to enter an answer, the tailoring process is also starting:

As you enter answers, the table at the bottom of the page is updated to show the answer codes and values of your responses.

Common Debugging Examples

Nested if() Statements (Conditional Logic)

EM supports the function "if(test,do_if_true,do_if_false)" so that you can perform conditional logic or tailoring. This function can be nested to do the equivalent of "if { } else if { } else {  }". EM will let you know if the parentheses are not balanced (e.g., you are missing a closing right parenthesis), or if you have any extra right parentheses. You should try to count the parentheses as you compose long nested if statements, save it, check for syntax errors, and fix them if any are found. Let's check together the below example.

The group of questions used below can be accessed from here: Tailoring survey example.lsg

First, with nothing entered, you just see "Hello."

If you enter a name, it says, "Hello {name}."

If you enter an age, you get a tailored message, depending upon whether you are a pre-school-age child or not:

School aged, teenager, or adult. Here is a  teenager who wants to be anonymous:

Here is the logic file of the group. As you can see in the "if-based" question, there are nested if statements based upon the person's age.

Als je een naam invoert, staat er: "Hello {naam}."

If you hover over the word "if", which is surrounded by a red box, it says "Parentheses not balanced". In this case, there should be four closing parentheses after "already an adult!", but there are only three.

If, on the other hand, you have an extra right parenthesis, it will be surrounded by a red box, like this:

When you are actually editing the question, the question looks like this: