Field, Placeholder & Aturan Pencocokan

Tentukan komponen susunan acara sekali saja, ambil nilainya otomatis dari teks mentah menggunakan regular expression, lalu hubungkan langsung ke tata letak slide canvas 16:9.

Ditulis untuk WorshipDeck 0.1.2

Alur Kerja Lengkap

Anda tidak perlu lagi mengetik ulang nama pelayan, tema khotbah, atau pengumuman ke dalam kotak teks slide satu per satu setiap minggu. WorshipDeck menghubungkan teks susunan acara langsung ke slide presentasi melalui enam tahap:

1. ADMIN MENENTUKAN FIELD & REGEX
   Artifacts → Layout & Fields → Predefined Fields & Regex
   Tentukan variable_name (misal song_leader) dan extraction_regex
                    │
                    ▼
2. ADMIN MEMASUKKAN FIELD KE KELOMPOK KARTU
   Card Groupings & Layout → Masukkan field ke kartu formulir
                    │
                    ▼
3. ADMIN MENGUJI POLA DI SANDBOX
   Rundown Test Area & Sandbox → Uji dengan teks susunan acara asli
                    │
                    ▼
4. ADMIN MENAUTKAN PLACEHOLDER KE CANVAS
   Main spine → Editor Canvas → Ketik teks: "Dipimpin oleh {song_leader}"
                    │
                    ▼
5. OPERATOR MENEMPELKAN SUSUNAN ACARA
   Services → New → Tempel teks susunan acara → Klik Baca susunan acara
                    │
                    ▼
6. HIDRASI RUNTIME & EKSPOR
   {song_leader} digantikan nama yang diambil di layar & PPTX

Definisi Field Bawaan

Buka Artifacts → Layout & Fields, lalu pilih sub-tab Predefined Fields & Regex. Setiap field kustom mengatur bagaimana data disimpan, disunting, dan dicocokkan:

Properti Ketentuan Deskripsi
Variable Name ^[a-z][a-z0-9_]{1,63}$ Kunci token unik. Wajib diawali huruf kecil, hanya memuat huruf kecil, angka, dan garis bawah, serta dilarang memakai nama reserved sistem (seperti id, service_id, created_at, title).
Field Label 1 sampai 100 karakter Judul tampilan yang muncul di atas kotak isian pada formulir pembuatan ibadah.
Field Type text atau text_area Teks satu baris untuk isian ringkas (nama, referensi ayat), atau teks multi-baris untuk catatan. Tipe field image khusus untuk file gambar yang diunggah dan tidak mendukung pencocokan regex.
Extraction Regex Pola RE2 yang valid Pola regular expression untuk membaca baris teks susunan acara mentah. Bersifat opsional; field tanpa regex diisi manual oleh operator.

Setelah menentukan field, beralihlah ke sub-tab Card Groupings & Layout untuk memasukkan field ke dalam kartu formulir yang sudah ada atau membuat wadah kartu baru. Field yang belum dimasukkan ke kartu tidak akan muncul di formulir ibadah.

Pola RE2 dan Named Groups

WorshipDeck menggunakan engine regular expression RE2 demi kecepatan pemrosesan dan performa linier. Karena RE2 murni beroperasi secara regular, beberapa fitur dari engine lain sengaja tidak didukung:

  • Didukung: Flag case-insensitive inline (?i), grup non-capturing (?:...), kelas karakter, dan quantifier standar (*, +, ?).
  • Dilarang: Lookahead assertion ((?=...), (?!...)), lookbehind assertion ((?<=...), (?<!...)), dan backreference (\1). Server akan menolak pola yang tidak valid dengan pesan error terperinci.

Named Capturing Groups

Saat sebuah baris cocok dengan pola Anda, parser mengambil nilai target menggunakan named groups. Gunakan sintaks grup standar:

Nama Grup Tujuan Contoh Sintaks
value Nilai teks utama yang dimasukkan ke kotak isian form. Jika tidak ada, parser mengambil grup capture pertama, atau seluruh teks yang cocok. (?i)^Pemimpin\s+Pujian\s*:\s*(?<value>.+)$
number Nomor lagu untuk slot kartu lagu. Otomatis memicu pencarian lirik di buku lagu lokal. (?i)^Lagu\s+Buka\s*#?\s*(?<number>\d+)
book Kode buku lagu opsional (otomatis menggunakan SDAH bila dikosongkan). (?i)^Lagu\s*#?(?<number>\d+)\s*\((?<book>[A-Z]+)\)

Rundown Test Area & Sandbox

Untuk memeriksa keakuratan regular expression sebelum menyimpan skema ibadah aktif, gunakan sub-tab Rundown Test Area & Sandbox di bawah Artifacts → Layout & Fields. Sandbox ini berjalan murni di memori dan tidak akan mengubah data ibadah atau catatan database yang sudah ada.

  1. Kartu A: Pengujian Susunan Acara Lengkap

    Tempel seluruh teks susunan acara dari ibadah terdahulu ke kotak pengujian, lalu klik Test Rundown. Sandbox menampilkan setiap field aktif dengan indikator status: Matched (menampilkan nilai yang diambil), Empty Regex (untuk field manual), atau Unmatched. Baris yang belum terpetakan muncul di kotak daftar khusus di bagian bawah.

  2. Kartu B: Evaluasi Pola Regex Tunggal

    Masukkan satu baris teks contoh dan usulan pola regular expression, lalu klik Evaluate Pattern. Pemeriksa akan menampilkan apakah pola cocok, nilai yang berhasil diambil, serta tabel capture groups bernama lengkap dengan posisi karakter mulainya.

Regular expression dievaluasi baris demi baris setelah spasi di awal dan akhir baris dibersihkan. Baris pertama yang cocok adalah yang diambil. Jika tidak ada baris yang cocok, parser menjalankan pola satu kali ke seluruh teks multi-baris sebagai langkah cadangan.

Pengikatan Placeholder ke Canvas

Setelah field berhasil dibuat, tautkan variable name-nya ke elemen teks apa pun di canvas tata letak visual:

  1. Buka Artifacts → Main spine, lalu klik tata letak yang ingin Anda edit, atau buat tata letak baru.
  2. Tambahkan kotak teks baru atau klik dua kali elemen teks yang sudah ada.
  3. Ketik nama variabel di dalam kurung kurawal, misalnya Dipimpin oleh {song_leader} atau Pembicara: {preacher}. Anda juga bisa mengeklik tombol Insert placeholder di bilah alat untuk memilih token yang sudah terdaftar.
  4. Klik Save Layout. Jika token placeholder yang Anda ketik belum ada di katalog field, canvas menampilkan ikon peringatan kuning, tetapi proses penyimpanan tetap diizinkan.

Aturan Hidrasi Runtime

Saat operator mengeklik Baca susunan acara di formulir pembuatan ibadah, WorshipDeck mengisi setiap kolom input. Ketika slide ditayangkan di konsol operator atau diekspor ke PowerPoint, sistem menghidrasi setiap slide mengikuti tiga aturan berikut:

Kondisi Perilaku Sistem
Nilai Tersedia Token {variable_name} langsung digantikan oleh teks hasil ekstraksi atau editan operator, dengan mempertahankan gaya huruf, ukuran font, dan perataan teks di sekitarnya.
Nilai Kosong (Elemen Opsional) Jika sebuah elemen hanya memuat token placeholder (misalnya {special_item}) dan nilainya kosong, seluruh elemen tersebut dihilangkan dari slide untuk mencegah kotak kosong atau jarak yang janggal. Jika elemen memuat teks statis di sekitarnya, token digantikan teks kosong.
Nilai Kosong (Elemen Wajib) Jika elemen ditandai wajib di tata letak dan placeholder terkait tidak memiliki nilai, pembuatan slide gagal dengan pesan error jelas: missing required placeholder: variable_name.

Pola Seed Bawaan

WorshipDeck menyertakan 13 field seed bawaan untuk tata ibadah umum gereja. Klik Seed Defaults di panel Predefined Fields untuk memuatnya:

Variable Name Label Bawaan Contoh Baris Input Rekomendasi Regex
song_leader Pemimpin Pujian Pemimpin Pujian: Sdr. Daniel (?i)^(?:Song\s+Leader|Pemimpin\s+Pujian)\s*[:\-]\s*(?<value>.+)$
preacher Pembicara Khotbah Khotbah: Pdt. Arthur Pendelton (?i)^(?:Sermon|Speaker|Khotbah|Pembicara)\s*[:\-]\s*(?<value>.+)$
sermon_title Judul Khotbah Judul: Terang yang Teguh (?i)^(?:Title|Judul\s+Khotbah|Tema)\s*[:\-]\s*(?<value>.+)$
scripture_reader Pembaca Alkitab Bacaan Alkitab: Sdri. Sarah (?i)^(?:Scripture\s+Reading|Bacaan\s+Alkitab)\s*[:\-]\s*(?<value>.+)$
scripture_ref Referensi Ayat Ayat Bacaan: Yohanes 3:16-17 (?i)^(?:Reading|Ayat\s+Bacaan|Nats)\s*[:\-]\s*(?<value>.+)$
Jangan pernah menempelkan data pribadi rahasia jemaat, permohonan doa pribadi, atau nomor telepon ke dalam template ekstraksi atau contoh regex pada repositori publik.