API на приложение
AppAPI позволява на потребителите да зареждат системни метаданни от приложението, използвайки различни методи в FormEngine и DMView. Осигурява достъп до различни ключове на данни за извличане на специфична информация от приложението.
В xlsform можете да използвате функцията pulldata() със следния синтаксис:
'app-api': Тази ключова дума информира FormEngine да зареди данните от App API.'data-key': Това е ключът на данните, които искате да заредите от App API.- Ако ключът на данни е невалиден или неподдържан, изчислението ще върне “n/a”.
Ето поддържаните ключове на данни, които можете да използвате с App-API:
osPlatform: Връща текущото наименование на ОС (Android или iOS) и версията на ОС. Уеб платформите ще върнат празна стойност.
appPlatform: Връща наименованието на платформата на приложението, което е rtSurvey.
appVersion: Връща наименованието на версията на приложението.
getDisplayWidth: Връща ширината на екрана на устройството в пиксели.
getDisplayHeight: Връща височината на екрана на устройството в пиксели.
getScreenSize: Връща размера на екрана на устройството в инчове.
projectCode: Връща текущия код на проекта на сайта, в който влиза потребителят.
projectURL: Връща текущия URL адрес на проекта на сайта, в който влиза потребителят. Стойността по подразбиране/резервна стойност е празен текст ("").
startingPoint: Връща пътя на точката, стартираща формуляра. Вижте “Начална точка на формуляр” за повече детайли.
serverTime: Връща най-добрата налична approximация на датата и часа на сървъра.
user.[attribute]: Връща атрибутите на текущия потребител въз основа на зададения ключ на атрибута. Вижте таблицата “Атрибути на потребители” за налични ключове на атрибути.
Комбинирайте долните ключове на атрибути с “user.” в параметрите на pulldata(), за да извлечете информацията за текущия потребител. Например използвайте user.username, user.email и т.н.
| Ключ на атрибут | Описание |
|---|---|
| username | Потребителско наименование на потребителя |
| name | Пълно наименование на потребителя |
| staffCode | Код на персонала на потребителя |
| phone | Телефонен номер на потребителя |
| Имейл адрес на потребителя | |
| description | Описателен текст в информацията за потребителя |
| organization_id | ID на организацията, към която принадлежи потребителят |
| organization_name | Наименование на организацията, към която принадлежи потребителят |
| team_id | ID на екипа, към който принадлежи потребителят |
| supervisor_id | ID на ръководителя на потребителя |
| is_supervisor | 1 ако потребителят е ръководител, 0 ако не е |
instancePath: Връща текущия път на папката на инстанцията.
appLanguage: Връща текущия език на приложението, зададен в настройките (например vi, en).
openArgs.[attribute]: Връща аргумента за отваряне на формуляр, предаден от ActionButton (act_fill_form, act_get_instance). Стойността по подразбиране/резервна стойност е празен текст ("").
primaryAppColor: Извлича основния цвят на приложението.
Примери за употреба
Съхранение на потребителското наименование и организацията на анкетьора
| type | name | label | calculation |
|---|---|---|---|
| calculate | enumerator_name | pulldata('app-api', 'user.name') | |
| calculate | enumerator_org | pulldata('app-api', 'user.organization_name') | |
| calculate | enumerator_email | pulldata('app-api', 'user.email') |
Използвайте ги в заглавия на бележки за одитни цели:
note | interviewer_info | Интервюиращ: ${enumerator_name} (${enumerator_org})
Информация за устройство и екран
| type | name | label | calculation |
|---|---|---|---|
| calculate | device_platform | pulldata('app-api', 'osPlatform') | |
| calculate | app_ver | pulldata('app-api', 'appVersion') | |
| calculate | screen_w | pulldata('app-api', 'getDisplayWidth') |
Полезно за отстраняване на неизправности: експортирайте device_platform и app_ver заедно с данните, за да идентифицирате коя версия на устройство е използвана за всяко подаване.
Час от сървъра вместо час от устройството
Часовниците на устройствата могат да бъдат неточни. Използвайте serverTime за по-надеждна времева марка:
| type | name | label | calculation |
|---|---|---|---|
| calculate | server_ts | pulldata('app-api', 'serverTime') |
Условна логика въз основа на потребителска роля
Показване на раздел само за ръководители само за ръководители:
| type | name | label | relevant |
|---|---|---|---|
| calculate | is_supervisor | pulldata('app-api', 'user.is_supervisor') | |
| begin_group | supervisor_section | Преглед от ръководител | ${is_supervisor} = '1' |
| text | supervisor_notes | Бележки на ръководителя | |
| end_group |
Предаване на аргументи от бутон за действие
Когато формулярът е стартиран от бутон act_fill_form с персонализирани аргументи:
| type | name | label | calculation |
|---|---|---|---|
| calculate | passed_hh_id | pulldata('app-api', 'openArgs.household_id') | |
| calculate | passed_task | pulldata('app-api', 'openArgs.task_code') |
Бутонът за действие трябва да предава аргументите с съответстващи ключове (например household_id, task_code).
Използване на информация за проект
| type | name | label | calculation |
|---|---|---|---|
| calculate | project | pulldata('app-api', 'projectCode') | |
| calculate | project_url | pulldata('app-api', 'projectURL') |
Бележки
- Всички извиквания на
pulldata('app-api', ...)се оценяват при отваряне на формуляра и не се преоценяват динамично по време на сесията (с изключение наserverTimeиnow()). - Ако ключът не се поддържа или данните не са налични, функцията връща
'n/a'(не празен низ — тествайте с!= 'n/a'вместо!= ''). - Стойностите на
openArgsса налични само когато формулярът е стартиран от бутон за действие; в противен случай връщат празен низ.