Guide pratique pour ExpressionScript

Aperçu de ce qui a été expliqué précédemment

Si vous avez suivi jusqu'à présent la structure du manuel LimeSurvey, cela signifie que vous maîtrisez déjà la Terminologie LimeSurvey. Ensuite, nous avons abordé les expressions et les variables afin d'apprendre comment améliorer nos enquêtes. Dans la partie suivante, nous sommes passés aux types et significations de syntax highlighting pour apprendre à corriger les erreurs de syntaxe.

Une fois ces notions de base couvertes, nous pourrions passer à des exemples et expliquer le fonctionnement des expressions dans LimeSurvey.

Surlignage de la syntaxe

Les captures d'écran suivantes donnent des exemples, mais n'affichent pas les valeurs des info-bulles. Une info-bulle est une boîte informative qui s’affiche chaque fois que vous passez la souris sur des mots en gras.

Grâce à cette coloration syntaxique, il est très facile de composer des expressions correctes, même celles qui sont compliquées. Bien que l'équipe LimeSurvey envisage d'essayer de créer une interface graphique pour Expression Builder, vous pouvez utiliser la coloration syntaxique existante pour identifier et corriger rapidement les fautes de frappe. Vous pouvez également utiliser les info-bulles pour valider l'exactitude de vos expressions (par exemple, confirmer que vous avez sélectionné la ou les variables souhaitées).

Dans chacun des exemples, il y a trois colonnes :

1. Source - c'est le texte brut que vous entreriez dans le champ de question de LimeSurvey
2. Pretty Print - c'est l'équivalent en surbrillance syntaxique de ce que vous avez entré
   • Notez que les expressions sont affichées sur un fond beige, mais ne sont pas entourées d'accolades dans cette mise en évidence.
   • Étant donné qu'EM prend en charge la substitution récursive, l'affichage d'accolades dans la mise en évidence entraînerait des erreurs de syntaxe
3. Résultat - c'est la sortie générée lorsque EM traite la source
   • Tout ce qui peut être correctement substitué est
   • Les expressions contenant des erreurs sont affichées en ligne, avec une coloration syntaxique. Les erreurs sont entourées d’un cadre bordé de rouge.

Syntaxe appropriée

Vous trouverez ci-dessous des exemples de syntaxe appropriée : 

1. Values : indique que les variables connues sont codées par couleur selon qu'elles sont définies sur la page en cours. INSERTANS:xxxx à l'ancienne obtient son propre style de codage couleur
2. Attributs de la question : indique que la notation par points peut accéder à certaines propriétés des questions 
3. Math : indique que les calculs de base et complexes sont pris en charge 
4. TextProcessing : affiche certaines des fonctions de traitement de texte disponibles
5. Dates : affiche deux des fonctions disponibles liées aux dates
6. Conditional : affiche l'utilisation de la fonction if(). Les choix peuvent être imbriqués.
7. Paragraphe personnalisé : vous pouvez entièrement personnaliser un rapport en fonction des valeurs précédentes
8. EM processus dans les chaînes : montre qu'il peut effectuer des substitutions dans les chaînes. Cet exemple génère un nom d'image personnalisé.
9. EM ne traite pas les accolades comme celles-ci : montre que si les accolades sont échappées ou s'il y a un espace blanc entre l'expression et les accolades, ES ignore l'expression.

Syntaxe EM contenant des erreurs

Voici des exemples d’erreurs courantes lors de la saisie d’expressions ES. Notez que les info-bulles fournissent des informations supplémentaires.

1. Javascript en ligne qui a oublié d'ajouter des espaces après l'accolade
   • Puisque "document.write" apparaît juste après une accolade, EM pense que c'est une expression, et rouge- cases "document" et "write" puisqu'il s'agit respectivement de variables et de fonctions non définies
2. Variables, fonctions et opérateurs inconnus/mal orthographiés
   • Ici, nous avons oublié que nous utilisons le nom de variable "sexe" au lieu de " sex", mais EM détecte cette erreur. Il met également en rouge '++', car ce n'est pas un opérateur pris en charge.
3. Avertit si vous utilisez = au lieu de eq, ou effectuez des affectations de valeurs
   • Notez que '=' et '+=' sont en texte rouge au lieu de noir. Si vous passez la souris dessus, vous verrez des avertissements indiquant que vous attribuez une valeur.
4. Mauvais nombre d'arguments pour les fonctions
   • if() prend 3 arguments, mais on lui en a donné 4, donc en survolant sur le "if" encadré en rouge expliquera l'erreur et affichera la syntaxe prise en charge
   • sum() prend un nombre illimité d'arguments, mais nous avions une virgule de fin avant les parenthèses fermantes, donc c'est encadré en rouge
5. Parenthèses incompatibles
   • C'est l'une des erreurs les plus courantes lors de l'écriture d'expressions.
   • Cela montre deux exemples de parenthèses fermantes manquantes et un exemple d'avoir une parenthèse fermante de trop.

#Syntaxe non prise en charge

1. • Si vous utilisez un opérateur ou une ponctuation que ES ne prend pas en charge, il le mettra en boîte rouge.
2. Affectations invalides
   • Certaines variables sont en lectureécriture et leurs valeurs peuvent être modifiées. D'autres sont en lecture seule.
   • Si vous essayez de modifier la valeur d'une variable en lecture seule, vous ne pouvez pas. EM encadrera la tentative en rouge.
   • Si vous essayez d'attribuer une valeur à une équation ou une chaîne, vous obtiendrez également une erreur

"Live" exemples de mise en évidence de la syntaxe avec des info-bulles actives

Source	Jolie impression	Résultat
Voici un exemple de syntaxe OK avec des info-bulles Bonjour {if(gender=='M','Mr.','Mrs.')} {nom}, il est maintenant {date('g:i a',time())}. Savez-vous où se trouvent vos {sum(numPets,numKids)} enfants et animaux de compagnie ?	Voici un exemple de syntaxe OK avec des info-bulles Bonjour , si ( genre == 'M' , 'Mr.' , 'Mrs.' ) nom de famille , il s'agit maintenant de la date ( 'g:i a' , time ()) . Savez-vous où se trouvent vos enfants et animaux de compagnie total ( numPets , numKids ) ?	Voici un exemple de syntaxe OK avec des info-bulles Bonjour M. Smith , il est maintenant 6h07. Savez-vous où sont vos 3 enfants et animaux de compagnie ?
Voici les erreurs courantes afin que vous puissiez voir les info-bulles Variables utilisées avant d'être déclarées : {notSetYet} Fonction inconnue : {iff(numPets>numKids,1,2)} Variable inconnue : {sum(age,num_pets,numKids)} Mauvais # paramètres : {sprintf()},{if(1,2)},{date()} Attribuer des variables en lecture seule :{TOKEN:ATTRIBUTE_1+=10},{name='Sally'} Parenthèses déséquilibrées : {pow(3,4},{(pow(3,4)},{pow(3,4))}	Voici les erreurs courantes afin que vous puissiez voir les info-bulles Variables utilisées avant d'être déclarées : notSetYet Fonction inconnue : iff ( numPets > numKids ,1,2) Variable inconnue : somme ( age , num_pets , numKids ) Mauvais # paramètres : sprintf () , if (1,2) , date () Attribuer des variables en lecture seule : TOKEN:ATTRIBUTE_1 += 10 , name = 'Sally' Parenthèses déséquilibrées : pow (3,4 , ( pow (3,4) , pow (3,4) )	Voici les erreurs courantes afin que vous puissiez voir les info-bulles Variables utilisées avant d'être déclarées : notSetYet Fonction inconnue : iff ( numPets > numKids ,1,2) Variable inconnue : somme ( age , num_pets , numKids ) Mauvais # paramètres : sprintf () , if (1,2) , date () Attribuer des variables en lecture seule : TOKEN:ATTRIBUTE_1 += 10 , name = 'Sally' Parenthèses déséquilibrées : pow (3,4 , ( pow (3,4) , pow (3,4) )
Voici une partie de la syntaxe non prise en charge Aucune prise en charge de '++', '--', '%',';' : {min(++age, --age,age % 2);} Ni '|', '&', '^' : {(sum(2 | 3,3 & 4,5 ^ 6)}} Ni les tableaux : {name[2], name['mine']}	Voici une partie de la syntaxe non prise en charge Pas de support pour '++', '--', '%',';' : min ( ++ age , -- age , age % 2) ; Ni '|', '&', '^' : ( sum (2 | 3,3 & 4,5 ^ 6) } Ni les tableaux : nom [ 2 ] , nom [ 'le mien' ]	Voici une partie de la syntaxe non prise en charge Pas de support pour '++', '--', '%',';' : min ( ++ age , -- age , age % 2) ; Ni '|', '&', '^' : ( sum (2 | 3,3 & 4,5 ^ 6) } Ni les tableaux : nom [ 2 ] , nom [ 'le mien' ]

Exemples d'adaptation (par exemple, extension de {INSERTANS:xxx})

"Cher {M.}/{Mme} Smith..."

Utilisez la fonction if() pour choisir conditionnellement si vous souhaitez afficher « M. ». ou 'Madame'.

La syntaxe est if(test,do_if_true,do_if_false).

#	Code	Question	Type
1	sexe	Quel est votre sexe ?	Sexe
|exemple1	Cher {if(gender=='M','Mr.','Mrs.')} Smith, ...	Long texte libre

Comme on peut le constater ci-dessous, « M. » et « Mme » sont adaptés à ce que le répondant choisit comme réponse à la question « genre ».

"Cher {M.}/{Mme} Smith..." dans l'e-mail d'invitation

Vous pouvez utiliser l'exemple ci-dessus dans l'e-mail d'invitation en utilisant les attributs de la table des jetons. Utilisez la fonction if() pour choisir si « M. » ou 'Mme.' doit être utilisé dans l’e-mail.

La syntaxe est "if(test,do_if_true,do_if_false)".

#	attribute	value
1	Last name	Smith
2	Email address	test@test.com
3	ATTRIBUTE_2	M

Text in invitation email:

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

you have been invited to participate in a survey:

https:/...

email View:

Calculation / Assessment Examples

Calculate assessment values at runtime and store the results in the survey data

This example uses all of EM's features, including Relevance, Tailoring, and the Equation question type.

It also shows that all of them are JavaScript-enabled, so if you have these features on a page, it will dynamically change as people set and change their answers.

#	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

To download this example, please click on the following link: Assessments_survey_example.

You may find below screenshots of representative questions. As you can see, EM syntax-highlights all fields that might contain tailoring. Here, you see examples of syntax-highlighting Relevance, the Equation question type, and substitutions within a question. You can also use substitutions within Help, Group header display, Welcome message, and End message.

In the next example, since the relevance is {numKids >= 2), the question will only be visible if the respondent reports that she has at least two children.

Below, you may observe that each variable has the .NAOK suffix attached to it. This is because of how EM supports cascading relevance. If you did not have .NAOK, then the sum would only be computed if the person said she has 4 children (e.g., if all of the variables are relevant). The usage of .NAOK means that we want to compute the sum even if all or some of the variables are irrelevant (e.g., "Not Applicable" (NA) is alright (OK)).

However, the .NAOK attribute only affects whether variables are passed into EM. If the respondent initially says she has 3 children, and enters ages for each, then changes her mind and says she has 2, we don't want to see the sum of the 3 entered values - since the third child is "not applicable" in our case anymore:

Each separate Expression is color coded with a tan background. As you can see, there are three separate Expressions here. The last one contains a message that is conditionally shown only if the person has more than one child.

Now, here are screenshots of the survey in action.

When you first visit the page, you see this. Note that is says "You have 0 children" instead of "You have 0 child".

If I change the value for number of children to 1, the display instantly changes to this, even though it is on the same page:

Now notice that the grammar is correct: "You have 1 child".

Now I change the value for number of children to 3, and the display instantly changes to this.

Notice that you now see the conditional message at the bottom:  "The sum of ages of your first 3 kids is 0.".

Now I'll enter ages for my imaginary children, and I get this display, summing up their ages:

Again, the score and display updates instantly as I enter the values, so you can use this to show a running total of an Assessment Score.

Now, I change the value for the number of children to 2. The display has changed to this:

Notice that although I had entered a value of 5.5 for the third child, the report now only sums the values of my first 2 children.

The reason for this is that the 3rd value is now irrelevant, and irrelevant values are actively ignored by EM.

If I were to change the number of kids back to 3, I would see the value of 5.5 I entered again. So, I don't lose any information I enter on the page.

However, if I navigate to the Next or Previous page, all irrelevant values will be NULLed out in the session and in the database. So, if I were to keep the value at 2, go to the next page, and then come back and state that I actually have 3 kids, I would no longer see the age of 5.5.

Enter data and see a dynamically changing report of what was entered on the same page

This example presents the Tailoring process within LimeSurvey.

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.

When you are originally editing this question, it is likely that at some point, you will have the wrong number of parentheses. Here's what happens if you have too few:

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: