Alkalmazás API
Az AppAPI lehetővé teszi a rendszer metaadatainak betöltését az alkalmazásból különböző módszerekkel a FormEngine-ben és a DMView-ban. Hozzáférést biztosít különböző adatkulcsokhoz az alkalmazásból történő konkrét információk lekéréséhez.
Az xlsform-ban a pulldata() függvényt használhatja a következő szintaxissal:
'app-api': Ez a kulcsszó tájékoztatja a FormEngine-t, hogy az adatokat az App API-ból kell betölteni.'adat-kulcs': Ez a kulcs az App API-ból betölteni kívánt adathoz.- Ha az adatkulcs érvénytelen vagy nem támogatott, a számítás “n/a” értéket ad vissza.
Az alábbi adatkulcsok támogatottak az App-API-val:
osPlatform: Visszaadja az aktuális operációs rendszer nevét (Android vagy iOS) és verziószámát. A webes platformok üres értéket adnak vissza.
appPlatform: Visszaadja az alkalmazásplatform nevét, ami rtSurvey.
appVersion: Visszaadja az alkalmazás verziószámát.
getDisplayWidth: Visszaadja az eszköz képernyőszélességét pixelekben.
getDisplayHeight: Visszaadja az eszköz képernyőmagasságát pixelekben.
getScreenSize: Visszaadja az eszköz képernyőméretét hüvelykben.
projectCode: Visszaadja a felhasználó által bejelentkezett oldal aktuális projektkódját.
projectURL: Visszaadja a felhasználó által bejelentkezett oldal aktuális projekt URL-jét. Az alapértelmezett/tartalék érték üres szöveg ("").
startingPoint: Visszaadja az űrlapot indító pont elérési útját. További részletekért lásd az “Űrlap kiindulópontja” részt.
serverTime: Visszaadja a szerveren lévő dátum és időpont legjobb elérhető közelítését.
user.[attribútum]: Visszaadja a jelenlegi felhasználói attribútumokat a megadott attribútumkulcs alapján. Az elérhető attribútumkulcsokat lásd a “Felhasználói attribútumok” táblázatban.
Az alábbi attribútumkulcsokat kombinálhatja a pulldata() paraméterekben a “user.” előtaggal az aktuális felhasználói adatok lekéréséhez. Például: user.username, user.email stb.
| Attribútumkulcs | Leírás |
|---|---|
| username | Felhasználó neve |
| name | Felhasználó teljes neve |
| staffCode | Felhasználó munkatársi kódja |
| phone | Felhasználó telefonszáma |
| Felhasználó e-mail-címe | |
| description | Leírás szövege a felhasználói adatokban |
| organization_id | A felhasználó szervezetének azonosítója |
| organization_name | A felhasználó szervezetének neve |
| team_id | A felhasználó csapatának azonosítója |
| supervisor_id | A felhasználó felügyelőjének azonosítója |
| is_supervisor | 1 ha felügyelő, 0 ha nem |
instancePath: Visszaadja az aktuális példány mappájának elérési útját.
appLanguage: Visszaadja az alkalmazás beállításaiban beállított aktuális alkalmazásnyelvet (pl. vi, en).
openArgs.[attribútum]: Visszaadja az ActionButton-ból (act_fill_form, act_get_instance) átadott nyitó-form-argumentumot. Az alapértelmezett/tartalék érték üres szöveg ("").
primaryAppColor: Lekéri az alkalmazás elsődleges színét.
Használati példák
A kérdező neve és szervezete tárolása
| 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') |
Használja ezeket a megjegyzés feliratokban auditálási célokra:
note | interviewer_info | Kérdező: ${enumerator_name} (${enumerator_org})
Eszköz- és képernyőadatok
| 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') |
Hibaelhárításhoz hasznos: exportálja a device_platform és az app_ver értéket az adatok mellett, hogy azonosítani lehessen, melyik eszközverziót használták az egyes beküldéseknél.
Szerver ideje az eszközidő helyett
Az eszközórák hibásak lehetnek. Megbízhatóbb időbélyeghez használja a serverTime értéket:
| type | name | label | calculation |
|---|---|---|---|
| calculate | server_ts | pulldata('app-api', 'serverTime') |
Feltételes logika felhasználói szerepkör alapján
Csak felügyelőknek szóló szakasz megjelenítése:
| type | name | label | relevant |
|---|---|---|---|
| calculate | is_supervisor | pulldata('app-api', 'user.is_supervisor') | |
| begin_group | supervisor_section | Felügyelői felülvizsgálat | ${is_supervisor} = '1' |
| text | supervisor_notes | Felügyelői megjegyzések | |
| end_group |
Argumentumok átadása műveletgombból
Ha az űrlapot egy egyedi argumentumokkal rendelkező act_fill_form műveletgombból indítják el:
| type | name | label | calculation |
|---|---|---|---|
| calculate | passed_hh_id | pulldata('app-api', 'openArgs.household_id') | |
| calculate | passed_task | pulldata('app-api', 'openArgs.task_code') |
A műveletgombnak egyező kulcsokkal kell átadnia az argumentumokat (pl. household_id, task_code).
Projektinformációk használata
| type | name | label | calculation |
|---|---|---|---|
| calculate | project | pulldata('app-api', 'projectCode') | |
| calculate | project_url | pulldata('app-api', 'projectURL') |
Megjegyzések
- Az összes
pulldata('app-api', ...)hívás az űrlap megnyitásakor kerül kiértékelésre, és a munkamenet során nem értékeli újra dinamikusan (kivéve aserverTimeés anow()értékeket). - Ha egy kulcs nem támogatott, vagy az adat nem érhető el, a függvény
'n/a'értéket ad vissza (nem üres string – tesztelje!= 'n/a'feltétellel, ne!= ''feltétellel). - Az
openArgsértékek csak akkor érhetők el, ha az űrlapot egy műveletgombból indítják el; egyébként üres stringet adnak vissza.