Практичні поради з ExpressionScript
From LimeSurvey Manual
Огляд попередньо поясненого матеріалу
Якщо ви досі слідували структурі посібника LimeSurvey, це означає, що ви вже знайомі з термінологією LimeSurvey. Далі ми розглянули вирази та змінні, щоб навчитися покращувати наші опитування. У наступній частині ми перейшли до типів і значень підсвічування синтаксису, щоб навчитися виправляти синтаксичні помилки.
Засвоївши ці базові поняття, ми можемо перейти до прикладів і пояснення того, як вирази працюють у LimeSurvey.
Підсвічування синтаксису
Наведені нижче знімки екрана містять приклади, але не показують вміст підказок. Підказка — це інформаційне вікно, яке з’являється, коли ви наводите вказівник миші на будь-яке виділене жирним кольорове слово.
Завдяки підсвічуванню синтаксису дуже легко складати правильні вирази, навіть складні. Хоча команда LimeSurvey планує спробувати створити графічний конструктор виразів, ви вже можете використовувати наявне підсвічування синтаксису, щоб швидко знаходити й виправляти помилки друку. Також можна використовувати підказки, щоб перевірити правильність виразів (наприклад, переконатися, що вибрано потрібні змінні).
У кожному з прикладів є три стовпці:
- Source (Джерело) — це необроблений текст, який ви вводите в поле питання LimeSurvey
- Pretty Print (Форматований вигляд) — це еквівалент введеного вами тексту з підсвіченим синтаксисом
- Зверніть увагу: вирази показано з бежевим фоном, але без фігурних дужок.
- Оскільки EM підтримує рекурсивну підстановку, показ фігурних дужок у підсвічуванні призвів би до синтаксичних помилок
- Result (Результат) — це вивід, який створюється, коли EM обробляє джерело
- Усе, що можна коректно підставити, підставляється
- Вирази з помилками показуються в тексті з підсвіченим синтаксисом. Помилки обведені червоною рамкою.
Правильний синтаксис
Нижче наведено приклади правильного синтаксису:
- Values (Значення): показує, що відомі змінні виділяються кольором залежно від того, чи встановлені вони на поточній сторінці.
- Question Attributes (Атрибути питання): показує, що за допомогою крапкової нотації можна отримати доступ до деяких властивостей питань
- Math (Математика): показує, що підтримуються прості та складні обчислення
- TextProcessing (Обробка тексту): показує деякі з доступних функцій обробки тексту
- Dates (Дати): показує дві з доступних функцій для роботи з датами
- Conditional (Умовні вирази): показує використання функції if(). Варіанти можна вкладати один в один.
- Tailored paragraph (Персоналізований абзац): ви можете повністю налаштувати звіт на основі попередніх значень
- EM processes within strings (EM обробляє всередині рядків): показує, що підстановки можливі всередині рядків. Цей приклад створює персоналізовану назву зображення.
- EM doesn't process curly braces like these (EM не обробляє такі фігурні дужки): показує, що якщо фігурні дужки екрановано або між виразом і фігурними дужками є пробіл, ES ігнорує вираз.
Синтаксис EM із помилками
Нижче наведено приклади поширених помилок під час введення виразів ES. Зверніть увагу, що підказки містять додаткову інформацію.
- Вбудований Javascript, у якому забули додати пробіли після фігурної дужки
- Оскільки «document.write» стоїть одразу після фігурної дужки, EM вважає це виразом і виділяє червоною рамкою «document» і «write», бо це невизначені змінна та функція відповідно
- Невідомі або написані з помилками змінні, функції та оператори
- Тут ми забули, що використовуємо ім’я змінної «gender» замість «sex», але EM виявляє цю помилку. Також він виділяє червоною рамкою '++', оскільки цей оператор не підтримується.
- Попередження, якщо використано = замість eq або виконується присвоєння значень
- Зверніть увагу, що '=' і '+=' показано червоним, а не чорним кольором. Якщо навести на них вказівник миші, ви побачите попередження про те, що ви присвоюєте значення.
- Неправильна кількість аргументів функцій
- if() приймає 3 аргументи, але їй передано 4, тому наведення вказівника на виділене червоною рамкою «if» пояснить помилку та покаже підтримуваний синтаксис
- sum() приймає необмежену кількість аргументів, але перед закривальною дужкою є зайва кома, тому її виділено червоною рамкою
- Невідповідність дужок
- Це одна з найпоширеніших помилок під час написання виразів.
- Тут показано два приклади відсутніх закривальних дужок і один приклад зайвої закривальної дужки.
- Непідтримуваний синтаксис
- Якщо ви використовуєте оператор або розділовий знак, які ES не підтримує, він буде виділений червоною рамкою.
- Недійсні присвоєння
- Деякі змінні мають доступ readWrite, і їхні значення можна змінювати. Інші доступні лише для читання.
- Якщо ви спробуєте змінити значення змінної, доступної лише для читання, це не вдасться. EM виділить спробу червоною рамкою.
- Якщо ви спробуєте присвоїти значення рівнянню або рядку, ви також отримаєте помилку
«Живі» приклади підсвічування синтаксису з активними підказками
| Source | Pretty Print | Result |
|---|---|---|
| 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 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))} | Ось поширені помилки, щоб ви могли побачити підказки Змінні, використані до їх оголошення: 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)) |
| 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' ] |
Приклади адаптації тексту
"Шановний {Mr}/{Mrs} Smith..."
Використовуйте функцію if(), щоб умовно вибрати, що відображати: 'Mr.' чи 'Mrs.'.
Синтаксис: if(test,do_if_true,do_if_false).
| # | Код | Питання | Тип |
| 1 | gender | Яка Ваша стать? | Стать |
| 2 | example1 | Dear {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 | Email адреса | 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:/...
Перегляд листа:
Приклади обчислень / оцінювання
Обчислення значень оцінювання під час виконання та збереження результатів у даних опитування
У цьому прикладі використано всі можливості 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 означає, що ми хочемо обчислити суму, навіть якщо всі або деякі змінні нерелевантні (тобто «Не застосовується» (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.
Введення даних і перегляд динамічно змінюваного звіту про введене на тій самій сторінці
Цей приклад демонструє процес персоналізації (Tailoring) у 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!" має бути чотири закривальні дужки, але є лише три.
Якщо ж, навпаки, є зайва права дужка, вона буде обведена червоною рамкою ось так:
Під час безпосереднього редагування питання воно виглядає так:
