Pendahuluan

Ambil formulir dinamis dengan pengiriman dan pengumpulan data secara real-time.

Informasi lebih lanjut tentang antarmuka pengguna modul ini https://doc.oneentry.cloud/docs/category/forms

---

🎯 Apa yang dilakukan modul ini?

Modul Forms memungkinkan Anda untuk mengambil formulir - formulir kontak, survei, pendaftaran, formulir umpan balik - sehingga Anda dapat menampilkannya di aplikasi Anda. Anda membangun formulir di panel admin OneEntry; SDK mengambil strukturnya (bidang, validator, label yang dilokalisasi) secara dinamis. Pengumpulan pengiriman yang sebenarnya ditangani oleh modul FormsData.

🚀 Memulai dengan Cepat

Inisialisasi modul dari defineOneEntry:

const { Forms } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Ambil satu formulir berdasarkan penandanya dan baca bidangnya:

// Fetch the "contact_form" form structure.
const form = await Forms.getFormByMarker("contact_form", "en_US");

console.log(form.identifier, form.localizeInfos.title);

// Render each field from the form's attributes.
form.attributes.forEach((field) => {
  console.log(field.marker, field.type, field.localizeInfos.title);
});

Untuk mencantumkan setiap formulir (dengan paginasi) gunakan getAllForms(langCode, offset, limit), yang mengembalikan objek { total, items }.

✨ Konsep Kunci

Apa itu Formulir?

Sebuah formulir (IFormsEntity) adalah cara terstruktur untuk mengumpulkan informasi dari pengguna:

• Bidang (attributes) - elemen input, masing-masing merupakan atribut dengan type (string, text, file, list, …)
• Validator (validators) - aturan per bidang (wajib, panjang string, format email)
• Struktur - tata letak dan label yang dilokalisasi yang ditentukan di admin OneEntry
• Pengiriman - respons pengguna, dikirim dan diambil melalui modul FormsData

Jenis Bidang Formulir

Setiap type bidang adalah AttributeType. Nilai umum:

Tipe (AttributeType)	Deskripsi	Contoh Penggunaan
string	Teks pendek satu baris	Nama, Judul, Kota
text / textWithHeader	Teks multi-baris	Pesan, Komentar, Bio
integer / real / float	Input numerik	Usia, Jumlah, Harga
date / dateTime / time	Pemilih tanggal & waktu	Tanggal lahir, Tanggal acara
list	Dropdown / multi-pilih dari opsi	Negara, Kategori
radioButton	Pilihan tunggal dari opsi	Ukuran, Rencana
file / image	Unggah file / gambar	Resume, Foto, Dokumen
groupOfImages	Beberapa gambar	Galeri
entity	Referensi ke entitas lain	Produk atau halaman yang terhubung

Catatan: Email adalah bidang string dengan emailInspectionValidator diaktifkan — tidak ada tipe bidang email terpisah.

📋 Apa yang Perlu Anda Ketahui

Struktur Formulir

Setiap formulir (IFormsEntity) memiliki id, identifier (penanda), type opsional ('order' | 'sing_in_up' | 'collection' | 'data' | 'rating' | null), localizeInfos (judul, pesan sukses, …) dan array attributes dari bidang. Setiap bidang memiliki marker, type, localizeInfos, dan objek validators:

{
  "marker": "email",
  "type": "string",
  "localizeInfos": { "title": "Email" },
  "validators": {
    "requiredValidator": { "strict": true },
    "emailInspectionValidator": true,
    "stringInspectionValidator": { "stringMin": 5, "stringMax": 100, "stringLength": 0 }
  }
}

Validator umum:

• requiredValidator — { strict: boolean }, bidang harus diisi
• stringInspectionValidator — { stringMin, stringMax, stringLength }, batasan panjang teks
• emailInspectionValidator — boolean, menegakkan format email
• defaultValueValidator — nilai default ditambah teks kesalahan kustom opsional

Set validator dapat diperluas — tipe validator tambahan dapat dikembalikan oleh API.

Formulir dibuat di panel admin

SDK digunakan untuk mengambil formulir (dan, melalui modul FormsData, mengirim data) — bukan untuk membuat atau mengedit formulir. Untuk membangun atau mengubah formulir, gunakan panel admin OneEntry: buka bagian Formulir, tambahkan bidang, konfigurasikan aturan validasi, dan aktifkan formulir.

---

📊 Tabel Referensi Cepat - Metode

Metode	Apa yang Dilakukan	Kapan Digunakan
getAllForms()	Ambil semua formulir (dengan paginasi)	Daftar semua formulir yang tersedia
getFormByMarker()	Ambil formulir berdasarkan penanda	Ambil formulir tertentu dalam kode

Kedua metode bersifat publik — tidak memerlukan otorisasi pengguna.

---

❓ Pertanyaan Umum (FAQ)

Bagaimana cara membuat atau mengedit formulir?

Formulir dibuat dan diedit di panel admin OneEntry (bagian Formulir), bukan melalui SDK. SDK hanya mengambil struktur formulir dan mengirim data.

---

Bisakah saya mengunggah file dengan formulir?

Ya. Tambahkan bidang file / image / groupOfImages ke formulir Anda; pengiriman dengan file ditangani oleh FormData.postFormsData(), yang mengunggahnya melalui modul FileUploading secara otomatis. Lihat modul FormsData.

---

Bisakah formulir memiliki bidang bersyarat (tampilkan/sembunyikan berdasarkan bidang lain)?

Tidak langsung di SDK — terapkan logika tampil/sembunyi di UI Anda sendiri berdasarkan nilai bidang formulir yang diambil.

---

🎓 Praktik Terbaik

• Rujuk formulir dengan identifier (penanda) mereka, bukan dengan ID numerik.
• Render bidang dan status yang diperlukan dari validators setiap bidang sehingga UI Anda sesuai dengan validasi sisi server.
• Gunakan try/catch di sekitar pengambilan dan tangani bentuk pengembalian IError.

---

🔗 Dokumentasi Terkait

• Modul FormsData - Kirim dan kelola pengiriman formulir
• Modul Events - Atur notifikasi otomatis saat formulir dikirim
• Modul FileUploading - Tangani unggahan file dalam formulir
• Modul Users - Kelola pengguna yang mengirim formulir

---