Практические примеры ExpressionScript

Краткий обзор предыдущих разделов

Если вы последовательно изучали структуру руководства по LimeSurvey, то вы уже знакомы с терминологией LimeSurvey. Затем мы рассмотрели выражения и переменные, чтобы научиться улучшать свои опросы. В следующей части мы перешли к типам и значениям подсветки синтаксиса, чтобы научиться исправлять синтаксические ошибки.

Разобравшись с этими основными понятиями, мы можем перейти к примерам и объяснению того, как выражения работают в LimeSurvey.

Подсветка синтаксиса

Приведенные ниже снимки экрана служат примерами, но не показывают содержимое подсказок. Подсказка — это информационное окно, которое появляется, когда вы наводите указатель мыши на любое выделенное цветом полужирное слово.

Благодаря подсветке синтаксиса очень легко составлять правильные выражения, даже сложные. Хотя команда LimeSurvey планирует создать графический конструктор выражений, вы уже сейчас можете использовать имеющуюся подсветку синтаксиса, чтобы быстро находить и исправлять опечатки. Подсказки также помогают проверить корректность выражений (например, подтвердить, что вы выбрали нужные переменные).

В каждом из примеров есть три столбца:

1. Источник — это исходный текст, который вы вводите в поле вопроса LimeSurvey
2. Pretty Print — это эквивалент введенного вами текста с подсветкой синтаксиса
   • Обратите внимание, что выражения отображаются на бежевом фоне, но без фигурных скобок.
   • Поскольку EM поддерживает рекурсивную подстановку, отображение фигурных скобок в подсветке приводило бы к синтаксическим ошибкам
3. Результат — это вывод, который генерируется, когда EM обрабатывает исходный текст
   • Подставляется все, что может быть корректно подставлено
   • Выражения с ошибками отображаются в тексте с подсветкой синтаксиса. Ошибки обведены красной рамкой.

Правильный синтаксис

Ниже приведены примеры правильного синтаксиса:

1. Значения: показывает, что известные переменные выделяются цветом в зависимости от того, заданы ли они на текущей странице.
2. Атрибуты вопросов: показывает, что с помощью точечной нотации можно получить доступ к некоторым свойствам вопросов
3. Математика: показывает, что поддерживаются простые и сложные вычисления
4. Обработка текста: показывает некоторые из доступных функций обработки текста
5. Даты: показывает две из доступных функций для работы с датами
6. Условие: показывает использование функции if(). Условия можно вкладывать друг в друга.
7. Персонализированный абзац: вы можете полностью настроить отчет на основе ранее введенных значений
8. EM обрабатывает выражения внутри строк: показывает, что подстановки возможны внутри строк. В этом примере генерируется персонализированное имя изображения.
9. EM не обрабатывает такие фигурные скобки: показывает, что если фигурные скобки экранированы или между выражением и фигурными скобками есть пробел, ES игнорирует выражение.

Синтаксис EM с ошибками

Ниже приведены примеры типичных ошибок при вводе выражений ES. Обратите внимание, что подсказки содержат дополнительную информацию.

1. Встроенный JavaScript, в котором забыли добавить пробелы после фигурной скобки
   • Поскольку "document.write" стоит сразу после фигурной скобки, EM считает это выражением и выделяет красной рамкой "document" и "write", так как это соответственно неопределенная переменная и неопределенная функция
2. Неизвестные или написанные с ошибками переменные, функции и операторы
   • Здесь мы забыли, что используем имя переменной "gender" вместо "sex", но EM обнаруживает эту ошибку. Он также выделяет красной рамкой '++', так как этот оператор не поддерживается.
3. Предупреждение, если используется = вместо eq или выполняется присваивание значений
   • Обратите внимание, что '=' и '+=' выделены красным цветом вместо черного. Если навести на них указатель мыши, вы увидите предупреждения о том, что происходит присваивание значения.
4. Неверное количество аргументов функций
   • if() принимает 3 аргумента, но ей передано 4, поэтому при наведении указателя на выделенное красной рамкой "if" будет показано описание ошибки и поддерживаемый синтаксис
   • sum() принимает неограниченное количество аргументов, но перед закрывающей скобкой стоит лишняя запятая, поэтому она выделена красной рамкой
5. Несоответствие скобок
   • Это одна из самых распространенных ошибок при написании выражений.
   • Здесь показаны два примера пропущенных закрывающих скобок и один пример лишней закрывающей скобки.
6. Неподдерживаемый синтаксис
   • Если вы используете оператор или знак препинания, которые ES не поддерживает, он будет выделен красной рамкой.
7. Недопустимые присваивания
   • Некоторые переменные доступны для чтения и записи, и их значения можно изменять. Другие доступны только для чтения.
   • Если попытаться изменить значение переменной, доступной только для чтения, ничего не получится. EM выделит эту попытку красной рамкой.
   • Если попытаться присвоить значение уравнению или строке, вы также получите ошибку

Живые примеры подсветки синтаксиса с активными подсказками

Источник	Pretty Print	Результат
Пример корректного синтаксиса с подсказками Здравствуйте, {if(gender=='M','Mr.','Mrs.')} {surname}, сейчас {date('g:i a',time())}. Знаете ли вы, где сейчас ваши {sum(numPets,numKids)} детей и питомцев?	Пример корректного синтаксиса с подсказками Здравствуйте, if(gender == 'M','Mr.','Mrs.') surname, сейчас date('g:i a',time()). Знаете ли вы, где сейчас ваши sum(numPets,numKids) детей и питомцев?	Пример корректного синтаксиса с подсказками Здравствуйте, Mr. Smith, сейчас 6:07 am. Знаете ли вы, где сейчас ваши 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) Неизвестная переменная: 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) Неизвестная переменная: 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))
Вот некоторые примеры неподдерживаемого синтаксиса Не поддерживаются '++', '--', '%',';': {min(++age, --age,age % 2);} Также не поддерживаются '|', '&', '^': {(sum(2 | 3,3 & 4,5 ^ 6)}} Массивы тоже не поддерживаются: {name[2], name['mine']}	Вот некоторые примеры неподдерживаемого синтаксиса Не поддерживаются '++', '--', '%',';': min( ++ age, -- age,age % 2) ; Также не поддерживаются '|', '&', '^': (sum(2 | 3,3 & 4,5 ^ 6)} Массивы тоже не поддерживаются: name [ 2 ] ,name [ 'mine' ]	Вот некоторые примеры неподдерживаемого синтаксиса Не поддерживаются '++', '--', '%',';': min( ++ age, -- age,age % 2) ; Также не поддерживаются '|', '&', '^': (sum(2 | 3,3 & 4,5 ^ 6)} Массивы тоже не поддерживаются: name [ 2 ] ,name [ 'mine' ]

Примеры персонализации

"Уважаемый(ая) {Mr}/{Mrs} Smith..."

Используйте функцию if(), чтобы в зависимости от условия отображать 'Mr.' или 'Mrs.'.

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

#	Код	Вопрос	Тип
1	gender	Укажите ваш пол	Пол
2	example1	Уважаемый(ая) {if(gender=='M','Mr.','Mrs.')} Smith, ...	Длинный произвольный текст

Как видно ниже, «Mr» и «Mrs» подстраиваются под ответ, который респондент выбирает на вопрос «gender».

"Уважаемый(ая) {Mr}/{Mrs} Smith..." в сообщении с приглашением

Приведённый выше пример можно использовать в сообщении с приглашением, применяя атрибуты из таблицы участников. Используйте функцию if(), чтобы выбрать, какое обращение — 'Mr.' или 'Mrs.' — должно использоваться в сообщении.

Синтаксис: "if(test,do_if_true,do_if_false)".

#	атрибут	значение
1	Фамилия	Smith
2	Адрес E-mail	test@test.com
3	ATTRIBUTE_2	M

Текст в сообщении с приглашением:

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

you have been invited to participate in a survey:

https:/...

Просмотр e-mail:

Примеры вычислений и оценки ответов

Расчёт значений оценки ответов во время выполнения и сохранение результатов в данных опроса

В этом примере используются все возможности EM, включая условие, персонализацию и тип вопроса «Уравнение».

Он также показывает, что все эти возможности работают на JavaScript, поэтому если они используются на странице, она будет динамически меняться по мере того, как участники вводят и изменяют свои ответы.

#	Код	Вопрос	Тип	Условие
1	numKids	Сколько у вас детей?	Числовой ввод	1
2	kid1	Сколько лет вашему первому ребёнку?	Числовой ввод	numKids >= 1
3	kid2	Сколько лет вашему второму ребёнку?	Числовой ввод	numKids >= 2
4	kid3	Сколько лет вашему третьему ребёнку?	Числовой ввод	numKids >= 3
5	kid4	Сколько лет вашему четвёртому ребёнку?	Числовой ввод	numKids >= 4
6	sumKidAges	{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK)}	Уравнение	1
7	kidSummary	Вы сказали, что у вас {numKids}. {if(numKids==1,'child','children')}. {if(numKids>1,implode(' ','The sum of ages of your first ',min(numKids,4),' kids is ',sumKidAges,'.'),' ')}	Отображение текста	1

Чтобы скачать этот пример, нажмите на следующую ссылку: Пример опроса с оценкой ответов.

Ниже приведены снимки экрана типичных вопросов. Как видите, EM подсвечивает синтаксис во всех полях, которые могут содержать персонализацию. Здесь показаны примеры подсветки синтаксиса для поля «Условие», типа вопроса «Уравнение» и подстановок внутри вопроса. Подстановки также можно использовать в справке, заголовке группы, приветственном сообщении и сообщении по окончании.

В следующем примере условие имеет вид {numKids >= 2), поэтому вопрос будет виден только в том случае, если респондент укажет, что у него как минимум двое детей.

Ниже видно, что к каждой переменной добавлен суффикс .NAOK. Это связано с тем, как EM поддерживает каскадные условия. Без .NAOK сумма вычислялась бы только в том случае, если бы респондент указал, что у него 4 детей (то есть если бы все переменные были актуальны). Использование .NAOK означает, что мы хотим вычислить сумму, даже если все или некоторые переменные не актуальны (т. е. «Неприменимо» (Not Applicable, NA) — это нормально (OK)).

Однако атрибут .NAOK влияет только на то, передаются ли переменные в EM. Если респондент сначала указывает, что у него 3 детей, вводит возраст каждого, а затем меняет решение и указывает, что у него 2 детей, мы не хотим видеть сумму трёх введённых значений, так как третий ребёнок в нашем случае больше «не применим»:

Каждое отдельное выражение выделено цветом на бежевом фоне. Как видите, здесь три отдельных выражения. Последнее содержит сообщение, которое отображается по условию, только если у респондента больше одного ребёнка.

Теперь посмотрим снимки экрана опроса в действии.

При первом открытии страницы вы увидите следующее. Обратите внимание, что отображается «You have 0 children», а не «You have 0 child».

Если изменить значение количества детей на 1, отображение мгновенно изменится, хотя мы остаёмся на той же странице:

Обратите внимание, что грамматика теперь верна: «You have 1 child».

Теперь я меняю значение количества детей на 3, и отображение мгновенно меняется следующим образом.

Обратите внимание, что внизу появилось условное сообщение: «The sum of ages of your first 3 kids is 0.».

Теперь я ввожу возраст своих воображаемых детей и получаю следующее отображение с суммой их возрастов:

Опять же, результат и отображение обновляются мгновенно по мере ввода значений, поэтому так можно показывать текущую сумму баллов оценки ответов.

Теперь я меняю значение количества детей на 2. Отображение изменилось следующим образом:

Обратите внимание: хотя для третьего ребёнка я ввёл значение 5.5, в отчёте теперь суммируются значения только первых двух детей.

Причина в том, что третье значение теперь не актуально, а неактуальные значения EM намеренно игнорирует.

Если вернуть количество детей к 3, я снова увижу введённое ранее значение 5.5. Таким образом, введённая на странице информация не теряется.

Однако если перейти на следующую или предыдущую страницу, все неактуальные значения будут обнулены (NULL) в сессии и в базе данных. Поэтому, если оставить значение 2, перейти на следующую страницу, затем вернуться и указать, что у меня на самом деле 3 детей, значение 5.5 я уже не увижу.

Ввод данных и динамически изменяющийся отчёт о введённых данных на той же странице

Этот пример демонстрирует процесс персонализации в LimeSurvey.

Чтобы скачать этот пример, перейдите по следующей ссылке: пример опроса с динамическими изменениями.

Так страница выглядит изначально. Вы видите только вопрос о том, в каком городе вы живёте:

Как только вы начнёте вводить ответ, также начнётся процесс адаптации (tailoring):

По мере ввода ответов таблица внизу страницы обновляется и показывает коды ответов и значения ваших ответов.

Типичные примеры отладки

Вложенные операторы if() (условная логика)

EM поддерживает функцию "if(test,do_if_true,do_if_false)", что позволяет реализовать условную логику или адаптацию текста. Эту функцию можно вкладывать друг в друга, получая эквивалент конструкции "if { } else if { } else { }". EM сообщит вам, если скобки не сбалансированы (например, пропущена закрывающая правая скобка) или если есть лишние правые скобки. При составлении длинных вложенных операторов if старайтесь считать скобки, затем сохраните изменения, проверьте наличие синтаксических ошибок и исправьте их, если они найдены. Давайте вместе рассмотрим пример ниже.

Группу вопросов, использованную ниже, можно скачать здесь: Пример опроса с адаптацией текста.lsg

Сначала, пока ничего не введено, вы видите только «Здравствуйте!»

Если вы введёте имя, отобразится: «Здравствуйте, {name}!»

Если вы введёте возраст, вы получите адаптированное сообщение в зависимости от того, относитесь ли вы к дошкольному возрасту:

Школьный возраст, подросток или взрослый. Вот подросток, который хочет остаться анонимным:

Вот файл логики этой группы. Как видно в вопросе «if-based», здесь используются вложенные операторы if, зависящие от возраста человека.

Когда вы впервые редактируете этот вопрос, вполне вероятно, что в какой-то момент количество скобок окажется неверным. Вот что произойдёт, если скобок слишком мало:

Если навести указатель мыши на слово "if", выделенное красной рамкой, появится сообщение «Parentheses not balanced» (скобки не сбалансированы). В данном случае после "already an adult!" должно быть четыре закрывающие скобки, но их только три.

Если же, напротив, у вас есть лишняя правая скобка, она будет выделена красной рамкой, как здесь:

Во время редактирования вопрос выглядит так: