Инструкции за ExpressionScript

Общ преглед на обясненото по-рано

Ако досега сте следвали структурата на ръководството на LimeSurvey, това означава, че вече използвате терминологията на LimeSurvey. След това разгледахме изрази и променливи, за да научим как да подобрим нашите проучвания. В следващата част преминахме към типовете и значенията на маркиране на синтаксис, за да научим как да коригираме синтактични грешки.

След като обхванем тези основни понятия, можем да преминем към примери и обяснение как работят изразите в LimeSurvey.

Осветяване на синтаксиса

Следните екранни снимки дават примери, но не показват стойностите на подсказките. Подсказката е информативно поле, което се показва всеки път, когато задържите курсора на мишката върху произволни думи с получер цвят.

Благодарение на това подчертаване на синтаксиса е много лесно да се съставят правилни изрази, дори и тези, които са сложни. Въпреки че екипът на LimeSurvey планира да се опита да изгради GUI на Expression Builder, можете да използвате съществуващото осветяване на синтаксиса, за да идентифицирате бързо и коригирате правописни грешки. Можете също така да използвате подсказките, за да потвърдите точността на вашите изрази (напр. да потвърдите, че сте избрали желаната променлива(и)).

Във всеки от примерите има три колони:

1. Източник - това е необработеният текст, който бихте въвели в полето за въпроси на LimeSurvey
2. Красив печат - това е синтаксисно подчертаният еквивалент на въведеното от вас
   • Обърнете внимание, че изразите се показват с кафяв фон, но не са заобиколени от къдрави скоби при това осветяване.
   • Тъй като EM поддържа рекурсивно заместване, показването на къдрави скоби в осветяването би причинило синтактични грешки
3. Резултат - това е изходът, генериран, когато EM обработва източника
   • Всичко, което може да бъде правилно заменено, е
   • Изразите с грешки се показват на линия, с подчертаване на синтаксиса. Грешките са заобиколени от поле с червена линия.

Правилен синтаксис

Можете да намерите по-долу примери за правилен синтаксис:

1. Стойности: показва, че известните променливи са цветно кодирани според това дали са зададени на текущата страница. INSERTANS в стар стил: xxxx получава свой собствен стил на цветно кодиране
2. Атрибути на въпроси: показва, че нотацията с точки има достъп до някои свойства на въпросите
3. Math: показва, че се поддържат основни и сложни изчисления
4. TextProcessing: показва някои от наличните функции за обработка на текст
5. Дати: показва две от наличните функции, свързани с дата
6. Условно: показва използването на функцията if(). Изборите могат да бъдат вложени.
7. Специализиран параграф: можете напълно да персонализирате отчет въз основа на предишни стойности
8. EM процеси в рамките на низове: показва, че може да прави замествания в рамките на низове. Този пример генерира персонализирано име на изображение.
9. EM не обработва фигурни скоби като тези: показва, че ако фигурните скоби са екранирани или има бяло пространство между израза и фигурните скоби, ES игнорира израза.

Синтаксисът на EM съдържа грешки

Ето примери за често срещани грешки при въвеждане на ES изрази. Обърнете внимание, че подсказките предоставят допълнителна информация.

1. Вграден Javascript, който е забравил да добави интервали след къдрава скоба
   • Тъй като "document.write" се появява точно след къдрава скоба, EM смята, че това е израз, а червено- кутии "document" и "write", тъй като те са съответно недефинирана променлива и функции
2. Неизвестни/Грешно изписани променливи, функции и оператори
   • Тук забравихме, че използваме името на променливата "gender" вместо " секс", но ЕМ улавя тази грешка. Освен това маркира в червено '++', тъй като това не е поддържан оператор.
3. Предупреждава, ако използвате = вместо eq или изпълнявате присвояване на стойност
   • Обърнете внимание, че '=' и '+=' са в червен текст вместо черен. Ако задържите курсора на мишката върху тях, ще видите предупреждения, че присвоявате стойност.
4. Грешен брой аргументи за функции
   • if() приема 3 аргумента, но са му дадени 4, така че задържането върху "if" в червено, ще обясни грешката и ще покаже поддържания синтаксис
   • sum() приема неограничен брой аргументи, но имахме запетая в края преди затварящите скоби, така че това е в червено! N!#Несъответстващи скоби
   • Това е една от най-честите грешки при писане на изрази.
   • Това показва два примера за липсващи затварящи скоби и един пример за твърде много затварящи скоби.

#Неподдържан синтаксис

1. • Ако използвате оператор или пунктуация, които ES не поддържа, той ще го постави в червено.
2. Невалидни присвоявания
   • Някои променливи се четат и записват и стойностите им могат да се променят. Други са само за четене.
   • Ако се опитате да промените стойността на променлива само за четене, не можете. EM ще постави в червена кутия опита.
   • Ако се опитате да присвоите стойност на уравнение или низ, вие също ще получите грешка

"На живо" примери за подчертаване на синтаксиса с активни подсказки

!Н! !Н!!Н!

Източник	Красив печат	Резултат
Ето пример за ОК синтаксис с подсказки Здравейте {if(gender=='M','Mr.','Mrs.')} {фамилия}, сега е {date('g:i a',time())}. Знаете ли къде са вашите {sum(numPets,numKids)} деца и домашни любимци?	Ето пример за ОК синтаксис с подсказки Здравейте , ако ( пол == 'M' , 'Mr.' , 'Mrs.' ) фамилия , сега е дата ( 'g:i a' , час ()) . Знаете ли къде са вашите ( numPets , numKids ) деца и домашни любимци?	Ето пример за ОК синтаксис с подсказки Здравейте , г-н Смит , сега е 6:07 сутринта. Знаете ли къде са вашите 3 деца и домашни любимци?
Ето често срещани грешки, за да можете да видите подсказките Променливи, използвани преди да бъдат декларирани: {notSetYet} Неизвестна функция: {iff(numPets>numKids,1,2)} Неизвестна променлива: {sum(age,num_pets,numKids)} Грешен # параметър: {sprintf()},{if(1,2)},{date()} Присвояване на променливи само за четене:{TOKEN:ATTRIBUTE_1+=10},{name='Sally'} Небалансирани скоби: {pow(3,4},{(pow(3,4)},{pow(3,4))}	Ето често срещани грешки, за да можете да видите подсказките Променливи, използвани преди да бъдат декларирани: notSetYet Неизвестна функция: iff ( numPets > numKids ,1,2) Неизвестна променлива: сума ( възраст , num_pets , numKids ) Грешни # параметри: sprintf () , if (1,2) , date () Присвояване на променливи само за четене: TOKEN:ATTRIBUTE_1 += 10 , име = 'Сали' Небалансирани скоби: pow (3,4 , ( pow (3,4) , pow (3,4) )	Ето често срещани грешки, за да можете да видите подсказките Променливи, използвани преди да бъдат декларирани: notSetYet Неизвестна функция: iff ( numPets > numKids ,1,2) Неизвестна променлива: сума ( възраст , num_pets , numKids ) Грешни # параметри: sprintf () , if (1,2) , date () Присвояване на променливи само за четене: TOKEN:ATTRIBUTE_1 += 10 , име = 'Сали' Небалансирани скоби: pow (3,4 , ( pow (3,4) , pow (3,4) )
Ето част от неподдържания синтаксис Няма поддръжка за '++', '--', '%',';': {min(++age, --age,age % 2);} Нито '|', '&', '^': {(sum(2 | 3,3 & 4,5 ^ 6)}} Нито масиви: {име[2], име['мое']}	Ето част от неподдържания синтаксис Няма поддръжка за '++', '--', '%',';': мин. ( ++ възраст , -- възраст , възраст % 2) ; Нито '|', '&', '^': ( сума (2 | 3,3 & 4,5 ^ 6) } Нито масиви: име [ 2 ] , име [ 'мое' ]	Ето част от неподдържания синтаксис Няма поддръжка за '++', '--', '%',';': мин. ( ++ възраст , -- възраст , възраст % 2) ; Нито '|', '&', '^': ( сума (2 | 3,3 & 4,5 ^ 6) } Нито масиви: име [ 2 ] , име [ 'мое' ]

Примери за адаптиране (напр. разширяване на {INSERTANS:xxx})

"Уважаеми {г-н}/{г-жо} Смит..."

Използвайте функцията if(), за да изберете условно дали да се покаже „Mr.“ или „г-жа“.

Синтаксисът е if(test,do_if_true,do_if_false).

#	Код	Въпрос	Тип
1	пол	Какъв е вашият пол?	Пол
|example1	Уважаеми {if(gender=='M','Mr.','Mrs.')} Смит, ...	Дълъг свободен текст

Както може да се види по-долу, „г-н“ и „г-жа“ са съобразени с това, което респондентът избира като отговор на въпроса „пол“.

Файл:em-tailoring-q-ex1-usage.jpg Файл:em-tailoring-q-ex2-usage.jpg

"Уважаеми {Mr}/{Mrs} Smith..." в имейла за покана

Можете да използвате примера по-горе в имейла с поканата, като използвате атрибути от таблицата с токени. Използвайте функцията if(), за да изберете дали „Mr.“ или „г-жа“ трябва да се използва в имейла.

Синтаксисът е "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: