Fungsi

Fungsi string link

rtSurvey mendukung berbagai fungsi, termasuk:

1. string(field): Mengonversi bidang menjadi string.

   • Contoh: string(34.8) akan dikonversi menjadi '34.8'.

2. string-length(field): Mengembalikan panjang bidang string.

   • Contoh: string-length(.) > 3 and string-length(.) < 10 dapat digunakan untuk memastikan bidang saat ini antara 3 dan 10 karakter.

3. substr(fieldorstring, startindex, endindex): Mengembalikan substring yang dimulai dari startindex dan berakhir tepat sebelum endindex. Indeks dimulai dari 0 untuk karakter pertama dalam string.

   • Contoh: substr(${phone}, 0, 3) akan mengembalikan tiga digit pertama nomor telepon.

4. concat(a, b, c, ...): Menggabungkan bidang (dan/atau string) bersama.

   • Contoh: concat(${firstname}, ' ', ${lastname}) akan mengembalikan nama lengkap dengan menggabungkan nilai dalam bidang firstname dan lastname.

5. linebreak(): Mengembalikan karakter baris baru.

   • Contoh: concat(${field1}, linebreak(), ${field2}, linebreak(), ${field3}) akan mengembalikan daftar tiga nilai bidang dengan baris baru di antara keduanya.

6. lower(): Mengonversi string menjadi semua huruf kecil.

   • Contoh: lower('Street Name') akan mengembalikan “street name”.

7. upper(): Mengonversi string menjadi semua huruf besar.

   • Contoh: upper('Street Name') akan mengembalikan “STREET NAME”.

Fungsi select_one dan select_multiple link

1. count-selected(field): Mengembalikan jumlah item yang dipilih dalam bidang select_multiple.

   • Contoh: count-selected(.) = 3 dapat digunakan sebagai ekspresi constraint untuk memastikan tepat tiga pilihan dipilih.

2. selected(field, value): Mengembalikan true atau false tergantung apakah nilai yang ditentukan dipilih dalam bidang select_one atau select_multiple.

   • Contoh: selected(${color}, 'Blue') dapat digunakan sebagai ekspresi relevansi untuk menampilkan grup atau bidang hanya jika responden memilih “Blue” sebagai warna favorit mereka.
   • Catatan: Parameter kedua harus selalu menentukan nilai pilihan, bukan label pilihan. Gunakan nilai dari kolom nilai dalam lembar kerja pilihan dari definisi formulir.

3. selected-at(field, number): Mengembalikan item yang dipilih pada posisi yang ditentukan dalam bidang select_multiple. Ketika angka yang diberikan adalah 0, ia mengembalikan item pertama yang dipilih; ketika angkanya 1, ia mengembalikan item kedua yang dipilih, dan seterusnya.

   • Contoh: selected-at(${fruits}, 0) = 'Apple' dapat digunakan sebagai ekspresi relevansi untuk menampilkan grup atau bidang hanya jika pilihan pertama yang dipilih adalah “Apple”.
   • Catatan: Nilai yang dikembalikan akan berupa nilai pilihan, bukan label pilihan.

4. choice-label(field, value): Mengembalikan label untuk pilihan bidang select_one atau select_multiple, seperti yang didefinisikan dalam lembar kerja pilihan dari definisi formulir.

   • Contoh 1: choice-label(${country}, ${country}) akan mengembalikan label pilihan untuk pilihan yang saat ini dipilih dalam bidang bernama country.
   • Contoh 2: choice-label(${languages}, selected-at(${languages}, 0)) akan mengembalikan label untuk pilihan pertama yang dipilih dalam bidang bernama languages.
   • Catatan: Fungsi ini mengambil label pilihan, bukan nilainya.

Fungsi bidang berulang link

Di rtSurvey, jika Anda ingin mengajukan pertanyaan yang sama beberapa kali, Anda dapat menempatkan bidang dalam grup pengulangan. Ini menghasilkan beberapa instans bidang yang sama. Fungsi-fungsi berikut dapat membantu Anda menangani bidang berulang ini dan data berulang yang mereka hasilkan. Lihat topik bantuan tentang bidang berulang untuk detail lebih lanjut.

1. join(string, repeatedfield): Untuk bidang dalam grup pengulangan, menghasilkan daftar nilai yang dipisahkan string. Parameter pertama menentukan pemisah yang digunakan untuk memisahkan nilai.

   • Contoh: join(', ', ${member_name}) akan menghasilkan daftar tunggal yang dipisahkan koma dari semua nama yang dimasukkan.

2. join-if(string, repeatedfield, expression): Berfungsi persis seperti join(), kecuali ia memeriksa setiap instans dalam grup pengulangan menggunakan ekspresi yang diberikan. Jika ekspresi dievaluasi menjadi false, item akan dihilangkan dari output.

   • Contoh: join-if(', ', ${member_name}, ${age} >= 18) akan menghasilkan daftar nama yang dipisahkan koma hanya dari anggota dewasa (mereka yang berusia 18 tahun ke atas).

3. count(repeatgroup): Mengembalikan jumlah saat ini berapa kali grup pengulangan telah berulang.

   • Contoh: count(${groupname}) akan mengembalikan jumlah instans grup.

4. count-if(repeatgroup, expression): Berfungsi persis seperti count(), kecuali ia memeriksa setiap instans dalam grup pengulangan menggunakan ekspresi yang diberikan. Jika ekspresi dievaluasi menjadi false, item akan dihilangkan dari output.

   • Contoh: count-if(${members}, ${age} >= 18) akan mengembalikan jumlah anggota dewasa berdasarkan bidang usia dalam grup pengulangan “members”.

5. sum(repeatedfield): Untuk bidang dalam grup pengulangan, menghitung jumlah semua nilai.

   • Contoh: sum(${loan_amount}) akan mengembalikan total nilai semua pinjaman.

6. sum-if(repeatedfield, expression): Berfungsi persis seperti sum(), kecuali ia memeriksa setiap instans dalam grup pengulangan menggunakan ekspresi yang diberikan. Jika ekspresi dievaluasi menjadi false, item akan dihilangkan dari output.

   • Contoh: sum-if(${loan_amount}, ${loan_amount} > 500) akan mengembalikan total nilai semua pinjaman yang melebihi 500. Pinjaman yang lebih kecil akan diabaikan.

7. min(repeatedfield): Untuk bidang dalam grup pengulangan, menghitung minimum dari semua nilai.

   • Contoh: min(${member_age}) akan mengembalikan usia anggota termuda dalam grup.

8. min-if(repeatedfield, expression): Berfungsi persis seperti min(), kecuali ia memeriksa setiap instans dalam grup pengulangan menggunakan ekspresi yang diberikan. Jika ekspresi dievaluasi menjadi false, item akan dihilangkan dari output.

   • Contoh: min-if(${member_age}, ${member_age} >= 18) akan mengembalikan usia dewasa termuda dalam grup. Mereka yang berusia di bawah 18 tahun akan diabaikan.

9. max(repeatedfield): Untuk bidang dalam grup pengulangan, menghitung maksimum dari semua nilai.

   • Contoh: max(${member_age}) akan mengembalikan usia anggota tertua dalam grup.

10. max-if(repeatedfield, expression): Berfungsi persis seperti max(), kecuali ia memeriksa setiap instans dalam grup pengulangan menggunakan ekspresi yang diberikan. Jika ekspresi dievaluasi menjadi false, item akan dihilangkan dari output.

    • Contoh: max-if(${member_age}, ${member_age} >= 18) akan mengembalikan usia dewasa tertua dalam grup. Mereka yang berusia di bawah 18 tahun akan diabaikan.

11. index(): Dipanggil dalam grup pengulangan, mengembalikan nomor indeks untuk grup atau instans saat ini.

    • Contoh: index() ketika digunakan dalam grup pengulangan akan mengembalikan 1 untuk instans pertama, 2 untuk instans kedua, dan seterusnya.

12. indexed-repeat(repeatedfield, repeatgroup, index): Mereferensikan bidang atau grup yang berada dalam grup pengulangan dari luar grup pengulangan tersebut. Parameter pertama menentukan bidang atau grup berulang yang diminati, parameter kedua menentukan grup pengulangan di mana bidang atau grup berada, dan parameter ketiga menentukan nomor instans dalam grup pengulangan yang digunakan.

    • Contoh 1: indexed-repeat(${name}, ${names}, 1) akan mengembalikan nama pertama yang tersedia ketika bidang name berada di dalam grup pengulangan sebelumnya bernama “names”.
    • Contoh 2: indexed-repeat(${name}, ${names}, index()) akan mengambil nama yang sesuai dengan nomor instans grup pengulangan saat ini.

13. rank-index(index, repeatedfield): Fungsi ini menghitung peringkat ordinal dari instans yang ditentukan dari bidang berulang untuk digunakan di luar grup pengulangan. Peringkat 1 diberikan kepada instans dengan nilai tertinggi, peringkat 2 kepada instans dengan nilai tertinggi berikutnya, dan seterusnya. Jika Anda memasukkan indeks yang tidak valid atau indeks ke instans dengan nilai non-numerik, peringkat 999 akan dikembalikan.

    • Contoh: rank-index(1, ${random_draw}) menghitung peringkat instans pertama berdasarkan nilai bidang random_draw-nya dibandingkan dengan nilai instans lainnya.

14. rank-index-if(index, repeatedfield, expression): Fungsi ini bekerja mirip dengan rank-index(), tetapi ia memeriksa setiap instans dalam grup pengulangan bidang berulang menggunakan ekspresi yang diberikan. Jika ekspresi dievaluasi menjadi false, item akan dihilangkan dari perhitungan. Indeks yang digunakan didasarkan pada kumpulan lengkap instans sebelum mengevaluasi ekspresi untuk setiap instans.

    • Contoh: rank-index-if(1, ${age}, ${age} >= 18) menghitung peringkat usia dalam kumpulan orang dewasa, hanya mempertimbangkan instans di mana usia lebih besar dari atau sama dengan 18.

Fungsi angka link

rtSurvey mendukung fungsi angka, termasuk:

• number(field): Mengonversi nilai bidang menjadi angka.

  • Contoh: number('34.8') = 34.8

• int(field): Mengonversi nilai bidang menjadi bilangan bulat.

  • Contoh: int('39.2') = 39

• min(field1, ..., fieldx): Mengembalikan nilai minimum di antara bidang yang diberikan.

  • Contoh: min(${father_age}, ${mother_age}) akan mengembalikan usia ayah atau ibu, mana yang lebih kecil.

• max(field1, ..., fieldx): Mengembalikan nilai maksimum di antara bidang yang diberikan.

  • Contoh: max(${father_age}, ${mother_age}) akan mengembalikan usia ayah atau ibu, mana yang lebih besar.

• format-number(field): Memformat nilai bidang integer atau desimal sesuai dengan pengaturan lokal pengguna.

  • Contoh: format-number(${income}) Ekspresi ini mungkin memformat “120000” menjadi “120,000”.

• round(field, digits): Membulatkan nilai bidang numerik ke jumlah digit yang ditentukan setelah titik desimal.

  • Contoh: round(${interest_rate}, 2)

• abs(number): Mengembalikan nilai absolut dari sebuah angka.

• pow(base, exponent): Mengembalikan nilai parameter pertama dipangkatkan dengan parameter kedua.

  • Setiap parameter dapat berupa bidang, angka, atau ekspresi.

• log10(fieldorvalue): Mengembalikan logaritma basis sepuluh dari bidang atau nilai yang diberikan.

• sin(fieldorvalue): Mengembalikan sinus dari bidang atau nilai yang diberikan, dinyatakan dalam radian.

• cos(fieldorvalue): Mengembalikan kosinus dari bidang atau nilai yang diberikan, dinyatakan dalam radian.

• tan(fieldorvalue): Mengembalikan tangen dari bidang atau nilai yang diberikan, dinyatakan dalam radian.

• asin(fieldorvalue): Mengembalikan arcsinus dari bidang atau nilai yang diberikan, dinyatakan dalam radian.

• acos(fieldorvalue): Mengembalikan arccosinus dari bidang atau nilai yang diberikan, dinyatakan dalam radian.

• atan(fieldorvalue): Mengembalikan arctangen dari bidang atau nilai yang diberikan, dinyatakan dalam radian.

• atan2(x, y): Mengembalikan sudut dalam radian yang dibentuk di origin oleh titik dengan koordinat (x, y) dan sumbu x positif. Hasilnya berada dalam rentang -pi() hingga pi().

• sqrt(fieldorvalue): Mengembalikan akar kuadrat non-negatif dari bidang atau nilai yang diberikan.

• exp(x): Mengembalikan nilai e^x.

• pi(): Mengembalikan nilai pi.

Fungsi tanggal dan waktu link

1. today(): Mengembalikan tanggal hari ini sebagai string dalam format YYYY-MM-DD. Dievaluasi sekali ketika formulir dibuka.

   • Contoh: today() → '2024-03-15'
   • Penggunaan umum: kolom default untuk mengisi tanggal hari ini secara otomatis, atau dalam relevant/constraint untuk membandingkan dengan bidang tanggal.

2. now(): Mengembalikan tanggal dan waktu saat ini sebagai string ISO 8601. Dievaluasi setiap kali ekspresi dihitung.

   • Contoh: now() → '2024-03-15T14:32:00.000+03:00'
   • Penggunaan umum: Merekam cap waktu tepat dari suatu peristiwa tertentu selama survei.

3. date(value): Mengonversi nilai (string atau angka) menjadi string tanggal. Berguna untuk memaksa nilai yang dihitung ke dalam tipe tanggal.

   • Contoh: date('2024-03-15') → '2024-03-15'

4. date-time(value): Mengonversi nilai menjadi string datetime.

   • Contoh: date-time(${event_timestamp})

5. decimal-date-time(value): Mengonversi string tanggal atau datetime menjadi angka desimal yang mewakili milidetik sejak Unix epoch dibagi 86400000 (yaitu, hari fraksional sejak 1970-01-01). Gunakan ini untuk melakukan aritmatika pada tanggal.

   • Contoh: Durasi dalam hari antara dua tanggal: decimal-date-time(${end_date}) - decimal-date-time(${start_date})
   • Contoh: Durasi dalam menit antara dua datetime: (decimal-date-time(${end_time}) - decimal-date-time(${start_time})) * 1440

6. format-date(date, format): Memformat nilai tanggal menggunakan string pola.

   • Token format: %Y (tahun 4 digit), %y (tahun 2 digit), %m (bulan 01–12), %d (hari 01–31), %a (singkatan nama hari), %b (singkatan nama bulan)
   • Contoh: format-date(today(), '%d/%m/%Y') → '15/03/2024'
   • Contoh: format-date(${dob}, '%B %d, %Y') → 'March 15, 1990'

7. format-date-time(datetime, format): Memformat nilai datetime menggunakan string pola. Menerima semua token format-date ditambah:

   • %H (jam 00–23), %h (jam 01–12), %M (menit 00–59), %S (detik 00–59), %3 (milidetik), %P (AM/PM)
   • Contoh: format-date-time(now(), '%d/%m/%Y %H:%M') → '15/03/2024 14:32'
   • Contoh: format-date-time(${event_time}, '%I:%M %p') → '02:32 PM'

Fungsi boolean link

1. boolean(value): Mengonversi nilai apa pun menjadi boolean. Mengembalikan true untuk string non-kosong, angka non-nol, dan true; mengembalikan false untuk string kosong, 0, dan false.

   • Contoh: boolean(${name}) mengembalikan true jika name tidak kosong.

2. boolean-from-string(string): Mengembalikan true jika string adalah '1' atau 'true' (tidak peka huruf besar-kecil); mengembalikan false sebaliknya.

   • Contoh: boolean-from-string(${enabled_flag}) — berguna ketika bidang menyimpan 'true'/'false' sebagai teks.

3. true(): Mengembalikan nilai boolean true.

   • Contoh: Dalam kolom required, true() setara dengan yes.

4. false(): Mengembalikan nilai boolean false.

   • Contoh: if(${skip_section} = 'yes', false(), true()) — secara dinamis mengatur required.

5. not(expression): Mengembalikan negasi logis dari ekspresi. Mengembalikan true jika ekspresi adalah false, dan sebaliknya.

   • Contoh: not(${consent} = 'yes') — tampilkan peringatan ketika persetujuan TIDAK diberikan.
   • Contoh: not(selected(${issues}, 'none')) — wajibkan detail hanya jika “none” tidak dipilih.

Fungsi string tambahan link

1. starts-with(string, prefix): Mengembalikan true jika string dimulai dengan prefix.

   • Contoh: starts-with(${phone}, '+254') memeriksa apakah nomor telepon dimulai dengan kode negara Kenya.

2. contains(string, substring): Mengembalikan true jika string mengandung substring.

   • Contoh: contains(${email}, '@') memeriksa bahwa alamat email memiliki tanda @.
   • Contoh: contains(${notes}, 'urgent') memicu pertanyaan tindak lanjut jika catatan menyebutkan “urgent”.

3. substring-before(string, needle): Mengembalikan bagian dari string yang muncul sebelum kemunculan pertama needle.

   • Contoh: substring-before(${full_name}, ' ') mengekstrak kata pertama (nama depan).

4. substring-after(string, needle): Mengembalikan bagian dari string yang muncul setelah kemunculan pertama needle.

   • Contoh: substring-after(${email}, '@') mengekstrak bagian domain dari alamat email.

5. normalize-space(string): Menghapus spasi di awal dan akhir serta menciutkan semua urutan spasi internal menjadi satu spasi.

   • Contoh: normalize-space(${name}) — membersihkan nama yang mungkin telah diketik dengan spasi ekstra.

6. translate(string, search_chars, replace_chars): Mengganti setiap karakter dalam string yang muncul di search_chars dengan karakter yang sesuai di replace_chars. Karakter dalam search_chars tanpa karakter yang sesuai di replace_chars akan dihapus.

   • Contoh: translate(${code}, 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') mengonversi ke huruf besar (setara dengan upper()).
   • Contoh: translate(${phone}, ' -()', '') menghapus spasi, tanda hubung, dan tanda kurung dari nomor telepon.

Fungsi matematika tambahan link

1. floor(number): Mengembalikan bilangan bulat terbesar yang kurang dari atau sama dengan number (membulatkan ke arah negatif tak terhingga).

   • Contoh: floor(4.9) = 4, floor(-2.1) = -3

2. ceiling(number): Mengembalikan bilangan bulat terkecil yang lebih besar dari atau sama dengan number (membulatkan ke arah positif tak terhingga).

   • Contoh: ceiling(4.1) = 5, ceiling(-2.9) = -2

3. random(): Mengembalikan angka desimal acak antara 0,0 (inklusif) dan 1,0 (eksklusif). Biasanya digunakan dalam bidang calculate untuk menetapkan nilai acak atau mengacak urutan pertanyaan.

   • Contoh: random() → misalnya, 0.7341
   • Contoh: int(random() * 6) + 1 → angka acak 1–6 (lemparan dadu)

4. coalesce(a, b): Mengembalikan a jika a tidak kosong; jika tidak mengembalikan b. Berguna sebagai cadangan ketika bidang mungkin kosong.

   • Contoh: coalesce(${preferred_name}, ${full_name}) — gunakan nama yang disukai jika diatur, jika tidak kembali ke nama lengkap.

5. once(value): Mengevaluasi value dan menyimpannya, tetapi hanya jika bidang saat ini kosong. Jika bidang sudah memiliki nilai (misalnya, sebelumnya telah diatur), once() mengembalikan nilai yang ada tanpa perubahan. Ini mencegah penghitungan ulang menimpa input pengguna.

   • Contoh: once(today()) dalam kolom default mengatur tanggal hari ini sekali dan tidak memperbarui jika enumerator membuka kembali formulir.
   • Contoh: once(uuid()) menghasilkan UUID sekali dan mempertahankannya stabil di seluruh pengeditan ulang.

Fungsi geo link

1. area(geoshape_value): Menghitung luas dalam meter persegi yang dilingkupi oleh nilai geoshape (poligon).

   • Parameternya adalah nilai bidang geoshape dalam format lat1 lon1 0 0; lat2 lon2 0 0; ...
   • Contoh: area(${field_boundary}) — hitung luas ladang yang disurvei dalam m².
   • Contoh: round(area(${field_boundary}) div 10000, 2) — konversi ke hektar.

2. distance(coordinates): Menghitung total panjang jalur dalam meter dari geotrace (garis), atau jarak antara dua geopoint.

   • Untuk geotrace: distance(${route}) mengembalikan total panjang jalur dalam meter.
   • Untuk dua geopoint: distance(concat(${point_a}, ' ', ${point_b})) mengembalikan jarak di antara keduanya.
   • Contoh: round(distance(${road_trace}) div 1000, 3) — panjang jalan dalam kilometer.

Fungsi validasi link

1. regex(value, pattern): Mengembalikan true jika value cocok dengan ekspresi reguler pattern. Gunakan dalam kolom constraint untuk validasi berbasis pola.

   • Pola menggunakan sintaks regex standar (subset POSIX ERE).
   • Contoh: regex(., '^[0-9]{10}$') — validasi angka 10 digit.
   • Contoh: regex(., '^[A-Z]{2}[0-9]{6}$') — validasi format nomor paspor (2 huruf besar diikuti 6 digit).
   • Contoh: regex(., '^[^@]+@[^@]+\.[^@]{2,}$') — pemeriksaan format email dasar.

2. checklist(min, max, v1, v2, ...): Mengevaluasi daftar ekspresi boolean dan mengembalikan true jika jumlah nilai true berada antara min dan max (inklusif). Masukkan -1 untuk min atau max untuk melewati batas tersebut.

   • Contoh: checklist(2, 3, ${q1} = 'yes', ${q2} = 'yes', ${q3} = 'yes') — lulus jika tepat 2 atau 3 dari tiga kondisi terpenuhi.
   • Contoh: checklist(1, -1, ${smoke_alarm}, ${fire_ext}, ${emergency_plan}) — setidaknya satu tindakan keamanan harus benar.

3. weighted-checklist(min, max, v1, w1, v2, w2, ...): Seperti checklist(), tetapi setiap nilai memiliki bobot. Jumlah bobot untuk nilai true harus berada antara min dan max.

   • Contoh: weighted-checklist(10, -1, ${has_toilet}, 4, ${has_sink}, 3, ${has_shower}, 5) — jumlah bobot untuk fasilitas yang ada harus minimal 10.

Fungsi utilitas link

1. uuid(): Menghasilkan UUID acak (format RFC 4122 v4) sebagai string.

   • Contoh: uuid() → 'a3f8b2c1-4d5e-6f7a-8b9c-0d1e2f3a4b5c'
   • Biasanya digunakan dengan once() untuk menghasilkan ID unik yang stabil: once(uuid())

2. version(): Mengembalikan nilai atribut version formulir seperti yang diatur dalam lembar kerja settings.

   • Contoh: version() → '3.1'
   • Berguna dalam bidang calculate untuk menyematkan versi formulir dalam data yang diekspor.

3. position(): Ketika dipanggil di dalam grup pengulangan, mengembalikan indeks berbasis 1 dari instans pengulangan saat ini.

   • Contoh: position() dalam instans pertama mengembalikan 1, dalam instans kedua mengembalikan 2, dan seterusnya.
   • Lihat juga: index() (alias), indexed-repeat() untuk mereferensikan nilai pengulangan dari luar grup.

4. thousandsep(length, separator, value): Memformat angka dengan pemisah ribuan. length adalah panjang string total minimum (diisi dengan spasi jika lebih pendek), separator adalah karakter yang digunakan (misalnya, ','), dan value adalah angka yang akan diformat.

   • Contoh: thousandsep(0, ',', 1234567) → '1,234,567'
   • Contoh: thousandsep(0, '.', ${income}) → memformat pendapatan dengan titik sebagai pemisah ribuan.

5. substr-jsonpath(value, jsonpath): Mengekstrak substring dari string JSON menggunakan ekspresi JSONPath.

   • Contoh: substr-jsonpath(${api_response}, '$.data.name') — ekstrak bidang name dari string JSON yang disimpan di api_response.
   • Biasanya digunakan bersamaan dengan callapi() untuk mengekstrak nilai spesifik dari respons API.