Tipe pertanyaan dinamis
Tipe pertanyaan dinamis memungkinkan tipe pertanyaan dan widget bidang ditentukan saat runtime berdasarkan respons API atau nilai yang dihitung.
Fitur Tipe Pertanyaan Dinamis memungkinkan widget input bidang dan perilaku validasi ditentukan saat runtime daripada saat desain formulir. Ini adalah ekstensi rtSurvey lanjutan yang digunakan ketika tipe data yang dikumpulkan bergantung pada konfigurasi sisi server, respons API, atau nilai bidang sebelumnya.
Kasus penggunaan umum adalah daftar periksa inspeksi yang dapat dikonfigurasi di mana server mendefinisikan bidang mana yang diperlukan, tipenya (teks, integer, select, dll.), dan opsi apa yang tersedia — tanpa membangun ulang formulir untuk setiap konfigurasi.
Cara kerjanya
Bidang yang ditandai sebagai tipe pertanyaan dinamis menggunakan callapi() untuk mengambil konfigurasinya dari API. Respons API mendefinisikan:
- Tipe input yang akan dirender (text, integer, select_one, dll.)
- Pilihan yang tersedia (untuk tipe select)
- Aturan validasi
Bidang ditandai dengan specialFeature: isDynamicQuestionType secara internal, yang memberi tahu mesin formulir untuk menggunakan respons API untuk membuat widget daripada definisi formulir statis.
Pengaturan
Langkah 1: Ambil konfigurasi bidang
Gunakan bidang calculate dengan callapi() untuk mengambil konfigurasi dinamis:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| calculate | field_config | callapi | callapi('POST', 'https://api.example.com/field-config', 1, 2, 0, '$.config', 10000, 0, '', '', '{"form_id": "##form_id##", "field_id": "inspection_result"}') |
Langkah 2: Referensikan konfigurasi dalam bidang dinamis
Bidang dinamis menggunakan callapi-verify() dalam appearance atau constraint untuk menghubungkan ke konfigurasi yang diambil:
| type | name | label | appearance |
|---|---|---|---|
| text | inspection_result | Hasil inspeksi | callapi-verify(dynamicParams) |
Mesin formulir membaca field_config dan secara dinamis menentukan apakah akan merender inspection_result sebagai bidang text, integer, atau select_one.
Format respons API
API harus mengembalikan objek JSON yang mendeskripsikan konfigurasi bidang. Respons tipikal:
{
"config": {
"type": "select_one",
"choices": [
{"value": "pass", "label": "Lulus"},
{"value": "fail", "label": "Gagal"},
{"value": "na", "label": "N/A"}
],
"required": true,
"constraint": ". != ''"
}
}
Contoh: Formulir inspeksi yang dapat dikonfigurasi
Formulir inspeksi di mana item daftar periksa dan tipe jawaban mereka diambil dari server berdasarkan kategori inspeksi:
| type | name | label | appearance | calculation |
|---|---|---|---|---|
| select_one inspection_type | insp_type | Tipe inspeksi | ||
| calculate | checklist_config | callapi | callapi('POST', 'https://api.example.com/checklist', 1, 2, 0, '$.items', 10000, 0, '', '', '{"type": "##insp_type##"}') | |
| text | item_1 | Item 1 | callapi-verify(dynamicParams) | |
| text | item_2 | Item 2 | callapi-verify(dynamicParams) | |
| text | item_3 | Item 3 | callapi-verify(dynamicParams) |
Server mengembalikan tipe widget, label, pilihan, dan validasi yang benar untuk setiap item berdasarkan insp_type.
Praktik Terbaik
- Gunakan tipe pertanyaan dinamis hanya ketika struktur bidang benar-benar bervariasi saat runtime — untuk formulir statis, gunakan tipe pertanyaan standar.
- Pastikan API konfigurasi merespons dengan cepat (di bawah 2 detik) dan tersedia di jaringan lapangan.
- Selalu definisikan fallback yang masuk akal dalam formulir untuk kasus API tidak terjangkau — bidang
textbiasa dengan catatan lebih baik daripada widget yang rusak. - Versi skema respons API Anda — perubahan pada format respons akan mempengaruhi semua formulir aktif yang menggunakan endpoint tersebut.
- Uji setiap kombinasi tipe bidang yang mungkin dikembalikan API sebelum penerapan.
Keterbatasan
- Tipe pertanyaan dinamis memerlukan konektivitas jaringan untuk mengambil konfigurasi.
- Rentang penuh tipe widget yang tersedia secara dinamis bergantung pada versi klien rtSurvey — uji versi target Anda.
- Ini adalah ekstensi rtSurvey lanjutan tanpa padanan dalam spesifikasi XLSForm standar.
- Kesalahan debug lebih sulit dilacak karena definisi bidang sebagian berada dalam formulir dan sebagian dalam respons API.