Функції

Рядкові функції link

rtSurvey підтримує різні функції, включаючи:

1. string(field): Перетворює поле на рядок.

   • Приклад: string(34.8) буде перетворено на '34.8'.

2. string-length(field): Повертає довжину рядкового поля.

   • Приклад: string-length(.) > 3 and string-length(.) < 10 можна використовувати для забезпечення, що поточне поле містить від 3 до 10 символів.

3. substr(fieldorstring, startindex, endindex): Повертає підрядок, починаючи з startindex та закінчуючи безпосередньо перед endindex. Індекси починаються з 0 для першого символу рядка.

   • Приклад: substr(${phone}, 0, 3) поверне перші три цифри номера телефону.

4. concat(a, b, c, ...): Об’єднує поля (та/або рядки) разом.

   • Приклад: concat(${firstname}, ' ', ${lastname}) поверне повне ім’я, об’єднуючи значення полів firstname та lastname.

5. linebreak(): Повертає символ розриву рядка.

   • Приклад: concat(${field1}, linebreak(), ${field2}, linebreak(), ${field3}) поверне список трьох значень полів з розривами рядків між ними.

6. lower(): Перетворює рядок на всі малі літери.

   • Приклад: lower('Street Name') поверне “street name”.

7. upper(): Перетворює рядок на всі великі літери.

   • Приклад: upper('Street Name') поверне “STREET NAME”.

Функції select_one та select_multiple link

1. count-selected(field): Повертає кількість елементів, обраних у полі select_multiple.

   • Приклад: count-selected(.) = 3 можна використовувати як вираз обмеження, щоб забезпечити вибір рівно трьох варіантів.

2. selected(field, value): Повертає true або false залежно від того, чи було обрано вказане значення у полі select_one або select_multiple.

   • Приклад: selected(${color}, 'Blue') можна використовувати як вираз актуальності для показу групи або поля лише якщо респондент обрав “Blue” як свій улюблений колір.
   • Примітка: Другий параметр завжди повинен вказувати значення варіанту, а не мітку варіанту. Використовуйте значення зі стовпця value в таблиці choices визначення форми.

3. selected-at(field, number): Повертає обраний елемент на вказаній позиції у полі select_multiple. Коли переданий номер дорівнює 0, повертає перший обраний елемент; коли номер дорівнює 1, повертає другий обраний елемент, і так далі.

   • Приклад: selected-at(${fruits}, 0) = 'Apple' можна використовувати як вираз актуальності для показу групи або поля лише якщо першим обраним варіантом є “Apple”.
   • Примітка: Повернуте значення буде значенням варіанту, а не міткою варіанту. Використовуйте значення зі стовпця value в таблиці choices визначення форми.

4. choice-label(field, value): Повертає мітку для варіанту поля select_one або select_multiple, як визначено в таблиці choices визначення форми.

   • Приклад 1: choice-label(${country}, ${country}) поверне мітку варіанту для поточного обраного варіанту в полі з назвою country.
   • Приклад 2: choice-label(${languages}, selected-at(${languages}, 0)) поверне мітку для першого обраного варіанту в полі з назвою languages.
   • Примітка: Ця функція отримує мітку варіанту, а не значення. Вона використовує стовпець label з таблиці choices визначення форми.

Функції полів повторів link

У rtSurvey, якщо ви хочете задавати одне й те саме питання кілька разів, ви можете помістити поле всередині групи повторів. Це призводить до кількох екземплярів одного поля. Наступні функції можуть допомогти вам працювати з цими повторюваними полями та даними, які вони виробляють.

1. join(string, repeatedfield): Для поля у групі повторів генерує список значень, розділений рядком. Перший параметр вказує роздільник для відокремлення значень.

   • Приклад: join(', ', ${member_name}) генерує єдиний список, розділений комами, з усіх введених імен.

2. join-if(string, repeatedfield, expression): Функціонує точно як join(), за винятком того, що перевіряє кожен екземпляр у групі повторів за допомогою наданого виразу. Якщо вираз оцінюється як false, елемент буде виключено з виводу.

   • Приклад: join-if(', ', ${member_name}, ${age} >= 18) генерує список імен, розділений комами, лише для дорослих членів (тих, кому 18 і більше).

3. count(repeatgroup): Повертає поточну кількість повторень групи повторів.

   • Приклад: count(${groupname}) поверне кількість екземплярів групи.

4. count-if(repeatgroup, expression): Функціонує точно як count(), за винятком того, що перевіряє кожен екземпляр у групі повторів за допомогою наданого виразу. Якщо вираз оцінюється як false, елемент буде виключено з виводу.

   • Приклад: count-if(${members}, ${age} >= 18) поверне кількість дорослих членів на основі поля age у групі повторів “members”.

5. sum(repeatedfield): Для поля у групі повторів обчислює суму всіх значень.

   • Приклад: sum(${loan_amount}) поверне загальну суму всіх позик.

6. sum-if(repeatedfield, expression): Функціонує точно як sum(), за винятком того, що перевіряє кожен екземпляр у групі повторів за допомогою наданого виразу. Якщо вираз оцінюється як false, елемент буде виключено з виводу.

   • Приклад: sum-if(${loan_amount}, ${loan_amount} > 500) поверне загальну суму всіх позик, що перевищують 500. Менші позики будуть ігноруватися.

7. min(repeatedfield): Для поля у групі повторів обчислює мінімум усіх значень.

   • Приклад: min(${member_age}) поверне вік наймолодшого члена в групі.

8. min-if(repeatedfield, expression): Функціонує точно як min(), за винятком того, що перевіряє кожен екземпляр у групі повторів за допомогою наданого виразу. Якщо вираз оцінюється як false, елемент буде виключено з виводу.

   • Приклад: min-if(${member_age}, ${member_age} >= 18) поверне вік наймолодшого дорослого в групі. Ті, кому менше 18, будуть ігноруватися.

9. max(repeatedfield): Для поля у групі повторів обчислює максимум усіх значень.

   • Приклад: max(${member_age}) поверне вік найстаршого члена в групі.

10. max-if(repeatedfield, expression): Функціонує точно як max(), за винятком того, що перевіряє кожен екземпляр у групі повторів за допомогою наданого виразу. Якщо вираз оцінюється як false, елемент буде виключено з виводу.

    • Приклад: max-if(${member_age}, ${member_age} >= 18) поверне вік найстаршого дорослого в групі. Ті, кому менше 18, будуть ігноруватися.

11. index(): Викликається у групі повторів, повертає порядковий номер для поточної групи або екземпляру.

    • Приклад: index() при використанні у групі повторів поверне 1 для першого екземпляру, 2 для другого і так далі.

12. indexed-repeat(repeatedfield, repeatgroup, index): Посилається на поле або групу всередині групи повторів ззовні цієї групи повторів. Перший параметр вказує потрібне поле повтору або групу, другий — групу повторів, в якій знаходиться поле або група, а третій — номер екземпляру в групі повторів для використання.

    • Приклад 1: indexed-repeat(${name}, ${names}, 1) поверне перше доступне ім’я, коли поле name знаходиться у попередній групі повторів з назвою “names”.
    • Приклад 2: indexed-repeat(${name}, ${names}, index()) витягне ім’я, що відповідає номеру екземпляру поточної групи повторів.

13. rank-index(index, repeatedfield): Ця функція обчислює порядковий ранг вказаного екземпляру повторюваного поля для використання поза групою повторів. Ранг 1 присвоюється екземпляру з найвищим значенням, ранг 2 — екземпляру з наступним найвищим значенням, і так далі. Якщо ви передаєте недійсний індекс або індекс до екземпляру з нечисловим значенням, буде повернуто ранг 999.

    • Приклад: rank-index(1, ${random_draw}) обчислює ранг першого екземпляру на основі значення його поля random_draw порівняно з значеннями інших екземплярів.

14. rank-index-if(index, repeatedfield, expression): Ця функція працює аналогічно до rank-index(), але перевіряє кожен екземпляр у групі повторів повторюваного поля за допомогою наданого виразу. Якщо вираз оцінюється як false, елемент буде виключено з обчислення. Індекс, що використовується, базується на повному наборі екземплярів перед оцінкою виразу для кожного екземпляру. Якщо ви передаєте індекс для екземпляру, який був ігнорований через те, що він не відповідає виразу, він вважається недійсним індексом, і буде повернуто ранг 999.

    • Приклад: rank-index-if(1, ${age}, ${age} >= 18) обчислює ранг віку в наборі дорослих, враховуючи лише екземпляри, де вік більший або рівний 18.

Числові функції link

rtSurvey підтримує числові функції, включаючи:

• number(field): Перетворює значення поля на число.

  • Приклад: number('34.8') = 34.8

• int(field): Перетворює значення поля на ціле число.

  • Приклад: int('39.2') = 39

• min(field1, ..., fieldx): Повертає мінімальне значення серед переданих полів.

  • Приклад: min(${father_age}, ${mother_age}) поверне вік батька або матері, залежно від того, який менший.

• max(field1, ..., fieldx): Повертає максимальне значення серед переданих полів.

  • Приклад: max(${father_age}, ${mother_age}) поверне вік батька або матері, залежно від того, який більший.

• format-number(field): Форматує значення цілочисельного або десяткового поля відповідно до налаштувань локалі користувача.

  • Приклад: format-number(${income}) може форматувати “120000” як “120,000”.

• round(field, digits): Округляє числове значення поля до вказаної кількості знаків після десяткової крапки.

  • Приклад: round(${interest_rate}, 2)

• abs(number): Повертає абсолютне значення числа.

• pow(base, exponent): Повертає значення першого параметру, піднесеного до степеня другого параметру.

  • Кожен параметр може бути полем, числом або виразом.

• log10(fieldorvalue): Повертає логарифм за основою десять переданого поля або значення.

• sin(fieldorvalue): Повертає синус переданого поля або значення, виражений у радіанах.

• cos(fieldorvalue): Повертає косинус переданого поля або значення, виражений у радіанах.

• tan(fieldorvalue): Повертає тангенс переданого поля або значення, виражений у радіанах.

• asin(fieldorvalue): Повертає арксинус переданого поля або значення, виражений у радіанах.

• acos(fieldorvalue): Повертає арккосинус переданого поля або значення, виражений у радіанах.

• atan(fieldorvalue): Повертає арктангенс переданого поля або значення, виражений у радіанах.

• atan2(x, y): Повертає кут у радіанах між точкою з координатами (x, y) та позитивною вісью x. Результат знаходиться в діапазоні від -pi() до pi().

• sqrt(fieldorvalue): Повертає невід’ємний квадратний корінь переданого поля або значення.

• exp(x): Повертає значення e^x.

• pi(): Повертає значення числа пі.

Функції дати та часу link

1. today(): Повертає сьогоднішню дату як рядок у форматі YYYY-MM-DD. Оцінюється один раз при відкритті форми.

   • Приклад: today() → '2024-03-15'
   • Поширене використання: стовпець default для попереднього заповнення сьогоднішньою датою, або в relevant/constraint для порівняння з полем дати.

2. now(): Повертає поточну дату та час як рядок ISO 8601. Оцінюється кожного разу, коли обчислюється вираз.

   • Приклад: now() → '2024-03-15T14:32:00.000+03:00'
   • Поширене використання: Запис точної позначки часу конкретної події під час опитування.

3. date(value): Перетворює значення (рядок або число) на рядок дати. Корисно для приведення обчислених значень до типу дати.

   • Приклад: date('2024-03-15') → '2024-03-15'

4. date-time(value): Перетворює значення на рядок datetime.

   • Приклад: date-time(${event_timestamp})

5. decimal-date-time(value): Перетворює рядок дати або datetime на десяткове число, що представляє мілісекунди з початку епохи Unix, поділені на 86400000 (тобто дробові дні з 1970-01-01). Використовуйте це для виконання арифметики з датами.

   • Приклад: Тривалість у днях між двома датами: decimal-date-time(${end_date}) - decimal-date-time(${start_date})
   • Приклад: Тривалість у хвилинах між двома datetime: (decimal-date-time(${end_time}) - decimal-date-time(${start_time})) * 1440

6. format-date(date, format): Форматує значення дати за допомогою рядка шаблону.

   • Токени формату: %Y (4-значний рік), %y (2-значний рік), %m (місяць 01–12), %d (день 01–31), %a (скорочений день тижня), %b (скорочена назва місяця)
   • Приклад: format-date(today(), '%d/%m/%Y') → '15/03/2024'
   • Приклад: format-date(${dob}, '%B %d, %Y') → 'March 15, 1990'

7. format-date-time(datetime, format): Форматує значення datetime за допомогою рядка шаблону. Приймає всі токени format-date плюс:

   • %H (година 00–23), %h (година 01–12), %M (хвилини 00–59), %S (секунди 00–59), %3 (мілісекунди), %P (AM/PM)
   • Приклад: format-date-time(now(), '%d/%m/%Y %H:%M') → '15/03/2024 14:32'
   • Приклад: format-date-time(${event_time}, '%I:%M %p') → '02:32 PM'

Boolean функції link

1. boolean(value): Перетворює будь-яке значення на boolean. Повертає true для непорожніх рядків, ненульових чисел та true; повертає false для порожніх рядків, 0 та false.

   • Приклад: boolean(${name}) повертає true, якщо name не порожнє.

2. boolean-from-string(string): Повертає true, якщо рядок — '1' або 'true' (без урахування регістру); повертає false в іншому випадку.

   • Приклад: boolean-from-string(${enabled_flag}) — корисно, коли поле зберігає 'true'/'false' як текст.

3. true(): Повертає boolean значення true.

   • Приклад: У стовпці required true() еквівалентно yes.

4. false(): Повертає boolean значення false.

   • Приклад: if(${skip_section} = 'yes', false(), true()) — динамічне встановлення обов’язковості.

5. not(expression): Повертає логічне заперечення виразу. Повертає true, якщо вираз хибний, і навпаки.

   • Приклад: not(${consent} = 'yes') — показати попередження, коли згода НЕ надана.
   • Приклад: not(selected(${issues}, 'none')) — вимагати деталі, лише якщо “none” не обрано.

Додаткові рядкові функції link

1. starts-with(string, prefix): Повертає true, якщо string починається з prefix.

   • Приклад: starts-with(${phone}, '+254') перевіряє, чи номер телефону починається з коду країни Кенії.

2. contains(string, substring): Повертає true, якщо string містить substring.

   • Приклад: contains(${email}, '@') перевіряє, що адреса електронної пошти має знак @.
   • Приклад: contains(${notes}, 'urgent') запускає подальше питання, якщо примітки згадують “urgent”.

3. substring-before(string, needle): Повертає частину string, що з’являється перед першим входженням needle.

   • Приклад: substring-before(${full_name}, ' ') витягує перше слово (ім’я).

4. substring-after(string, needle): Повертає частину string, що з’являється після першого входження needle.

   • Приклад: substring-after(${email}, '@') витягує доменну частину адреси електронної пошти.

5. normalize-space(string): Видаляє початкові та кінцеві пробіли та згортає всі внутрішні послідовності пробілів до одного пробілу.

   • Приклад: normalize-space(${name}) — очищає ім’я, яке може бути набрано з зайвими пробілами.

6. translate(string, search_chars, replace_chars): Замінює кожен символ у string, що з’являється у search_chars, відповідним символом у replace_chars. Символи у search_chars без відповідного символу у replace_chars видаляються.

   • Приклад: translate(${code}, 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') перетворює на верхній регістр (еквівалентно upper()).
   • Приклад: translate(${phone}, ' -()', '') видаляє пробіли, тире та дужки з номера телефону.

Додаткові математичні функції link

1. floor(number): Повертає найбільше ціле число, менше або рівне number (округлює у бік від’ємної нескінченності).

   • Приклад: floor(4.9) = 4, floor(-2.1) = -3

2. ceiling(number): Повертає найменше ціле число, більше або рівне number (округлює у бік позитивної нескінченності).

   • Приклад: ceiling(4.1) = 5, ceiling(-2.9) = -2

3. random(): Повертає випадкове десяткове число від 0.0 (включно) до 1.0 (виключно). Зазвичай використовується в полях calculate для присвоєння випадкових значень або рандомізації порядку питань.

   • Приклад: random() → наприклад, 0.7341
   • Приклад: int(random() * 6) + 1 → випадкове число 1–6 (кидок кубика)

4. coalesce(a, b): Повертає a, якщо a не порожнє; в іншому випадку повертає b. Корисно як запасний варіант, коли поле може бути порожнім.

   • Приклад: coalesce(${preferred_name}, ${full_name}) — використовувати переважне ім’я, якщо встановлено, інакше повертатися до повного імені.

5. once(value): Оцінює value та зберігає його, але лише якщо поточне поле порожнє. Якщо поле вже має значення (наприклад, було раніше встановлено), once() повертає наявне значення незмінним. Це запобігає перезапису введення користувача повторним обчисленням.

   • Приклад: once(today()) у стовпці default встановлює сьогоднішню дату один раз і не оновлює, якщо анкетер повторно відкриває форму.
   • Приклад: once(uuid()) генерує UUID один раз і зберігає його стабільним при повторному редагуванні.

Геофункції link

1. area(geoshape_value): Обчислює площу у квадратних метрах, обмежену значенням geoshape (полігону).

   • Параметр — значення geoshape у форматі lat1 lon1 0 0; lat2 lon2 0 0; ...
   • Приклад: area(${field_boundary}) — обчислити площу обстеженого поля у м².
   • Приклад: round(area(${field_boundary}) div 10000, 2) — конвертувати в гектари.

2. distance(coordinates): Обчислює загальну довжину шляху у метрах geotrace (лінії) або відстань між двома точками geopoint.

   • Для geotrace: distance(${route}) повертає загальну довжину шляху у метрах.
   • Для двох geopoint: distance(concat(${point_a}, ' ', ${point_b})) повертає відстань між ними.
   • Приклад: round(distance(${road_trace}) div 1000, 3) — довжина дороги у кілометрах.

Функції валідації link

1. regex(value, pattern): Повертає true, якщо value відповідає регулярному виразу pattern. Використовуйте у стовпці constraint для валідації за шаблоном.

   • Шаблон використовує стандартний синтаксис regex (підмножина POSIX ERE).
   • Приклад: regex(., '^[0-9]{10}$') — перевірка 10-значного числа.
   • Приклад: regex(., '^[A-Z]{2}[0-9]{6}$') — перевірка формату номера паспорта (2 великі літери та 6 цифр).
   • Приклад: regex(., '^[^@]+@[^@]+\.[^@]{2,}$') — базова перевірка формату електронної пошти.

2. checklist(min, max, v1, v2, ...): Оцінює список boolean виразів та повертає true, якщо кількість значень true знаходиться між min та max (включно). Передайте -1 для min або max, щоб пропустити цю межу.

   • Приклад: checklist(2, 3, ${q1} = 'yes', ${q2} = 'yes', ${q3} = 'yes') — проходить, якщо рівно 2 або 3 з трьох умов є істинними.
   • Приклад: checklist(1, -1, ${smoke_alarm}, ${fire_ext}, ${emergency_plan}) — принаймні один захід безпеки повинен бути істинним.

3. weighted-checklist(min, max, v1, w1, v2, w2, ...): Як checklist(), але кожне значення має вагу. Сума ваг для значень true повинна бути між min та max.

   • Приклад: weighted-checklist(10, -1, ${has_toilet}, 4, ${has_sink}, 3, ${has_shower}, 5) — сума ваг для наявних зручностей повинна бути не менше 10.

Службові функції link

1. uuid(): Генерує випадковий UUID (формат RFC 4122 v4) як рядок.

   • Приклад: uuid() → 'a3f8b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c'
   • Зазвичай використовується з once() для генерації стабільного унікального ідентифікатора: once(uuid())

2. version(): Повертає значення атрибуту version форми, встановленого в таблиці settings.

   • Приклад: version() → '3.1'
   • Корисно в полях calculate для вбудовування версії форми в експортовані дані.

3. position(): При виклику всередині групи повторів повертає 1-базований індекс поточного екземпляру повтору.

   • Приклад: position() у першому екземплярі повертає 1, у другому — 2, і так далі.
   • Дивіться також: index() (псевдонім), indexed-repeat() для посилання на значення повторів ззовні групи.

4. thousandsep(length, separator, value): Форматує число з роздільником тисяч. length — мінімальна загальна довжина рядка (доповнюється пробілами, якщо коротший), separator — символ для використання (наприклад, ','), value — число для форматування.

   • Приклад: thousandsep(0, ',', 1234567) → '1,234,567'
   • Приклад: thousandsep(0, '.', ${income}) → форматує дохід з крапкою як роздільником тисяч.

5. substr-jsonpath(value, jsonpath): Витягує підрядок з рядка JSON за допомогою виразу JSONPath.

   • Приклад: substr-jsonpath(${api_response}, '$.data.name') — витягти поле name з рядка JSON, збереженого в api_response.
   • Зазвичай використовується разом з callapi() для витягування конкретних значень з відповідей API.