Lewati ke konten utama

Pengenalan

Tangani pengiriman formulir dan ambil data formulir.

Informasi lebih lanjut tentang formulir di panel admin OneEntry: https://doc.oneentry.cloud/docs/category/forms

🎯 Apa yang dilakukan modul ini?​

Modul FormData memungkinkan Anda untuk mengirim formulir yang diisi pengguna (formulir kontak, survei, pendaftaran) ke OneEntry dan mengambil, memperbarui, atau menghapus data yang dikirim untuk analisis, pelaporan, dan manajemen.

Anggap saja ini sebagai manajer pengiriman formulir Anda - pengguna mengirim formulir, Anda menyimpannya di OneEntry, dan mengambilnya kapan pun Anda perlu melihat tanggapan, menghasilkan laporan, atau menganalisis data.

🚀 Memulai dengan Cepat​

Inisialisasi modul dari defineOneEntry:


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

Bangun tubuh dari konfigurasi formulir dan kirimkan:

// 1. Fetch the form to read its module config.
const form = await Forms.getFormByMarker("contact_form");
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// 2. Submit the user's input.
const response = await FormData.postFormsData({
  formIdentifier: "contact_form",
  formModuleConfigId,
  moduleEntityIdentifier,
  replayTo: null,
  status: "sent",
  formData: [
    { marker: "name", type: "string", value: "Jack" },
  ],
});

console.log(response);

Untuk membaca pengiriman nanti, panggil getFormsDataByMarker(marker, formModuleConfigId, body?, isExtended?, langCode?, offset?, limit?).

✨ Konsep Kunci​

Apa itu Data Formulir?​

Data formulir adalah informasi yang dikirim pengguna melalui formulir. Setiap pengiriman dibangun dari array formData objek field (marker, type, value) ditambah pengenal konfigurasi formulir.

Struktur tubuh pengiriman​

postFormsData menerima IBodyPostFormData:

const body = {
  formIdentifier: 'contact_form', // Form marker
  formModuleConfigId: 9,          // Module config ID (from the form)
  moduleEntityIdentifier: 'blog', // Module entity identifier (from the form)
  replayTo: null,                 // Email address to reply to (optional)
  status: 'sent',                 // Submission status (optional)
  formData: [                     // Form fields
    { marker: 'name', type: 'string', value: 'Test' },
  ],
};

📋 Apa yang Perlu Anda Ketahui​

Pengiriman memerlukan konfigurasi formulir​

Sebelum mengirim, Anda memerlukan tiga nilai, semua dibaca dari formulir itu sendiri:

  1. Marker formulir (formIdentifier) — pengenal teks formulir
  2. formModuleConfigId — dari moduleFormConfigs formulir
  3. moduleEntityIdentifier — dari moduleFormConfigs formulir
const form = await Forms.getFormByMarker('contact_form');
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

Cache nilai-nilai ini agar Anda tidak mengambil ulang formulir pada setiap pengiriman.

Field formData​

Setiap entri dalam array formData menggambarkan satu field:

  • marker — harus cocok dengan marker field dari definisi formulir
  • type — tipe field (digunakan untuk validasi dan penanganan file)
  • value — input pengguna

Field dengan tipe file / image / groupOfImages diunggah secara otomatis melalui modul FileUploading ketika Anda mengirimkan File/FileList/Blob sebagai value.

Status pengiriman​

Gunakan field status untuk melacak status pengiriman. "sent" adalah nilai tipikal untuk pengiriman baru; Anda dapat memindahkan pengiriman ke status ditinjau/arsip dengan updateFormsDataStatusByid().

Memperbarui dan menghapus pengiriman​

Pengiriman tidak bersifat tidak dapat diubah. Pengguna yang terautentikasi dapat mengubah atau menghapusnya:

  • updateFormsDataByid(id, body) — edit pengiriman yang disimpan berdasarkan id 🔐
  • updateFormsDataStatusByid(id, body) — ubah hanya status pengiriman berdasarkan id 🔐
  • deleteFormsDataByid(id) — hapus pengiriman berdasarkan id 🔐

Membaca pengiriman​

getFormsDataByMarker mengembalikan pengiriman untuk sebuah formulir. Halaman melalui hasil dengan offset / limit, dan sempitkan dengan body permintaan (misalnya status, dateFrom, dateTo, userIdentifier).

Mencari pengiriman berdasarkan makna​

getFormsDataByVectorSearch(body, langCode, offset, limit) menjalankan pencarian semantik (vektor) atas pengiriman: Anda mengirimkan queryText dalam bahasa alami dan mendapatkan kembali catatan yang cocok dengan maknanya, bukan berdasarkan kata kunci literal.

Catatan-catatan ini menggunakan tipe yang berbeda dari sisa modul - IFormDataSearchEntity alih-alih IFormDataEntity. Keduanya membawa id, formIdentifier, time, dan formData, tetapi entitas pencarian juga mengekspos field moderasi dan pengirim dari catatan mentah:

FieldTipeMakna
status'sent' | 'banned' | 'deleted' | 'moderation' | 'approved'Status moderasi dari catatan
ipstringAlamat IP dari mana formulir dikirim
fingerprintstringSidik jari perangkat pengirim
isUserAdminbooleanApakah seorang admin yang mengirim catatan
userIdentifierstringSiapa yang mengirim formulir
entityIdentifierstringEntitas yang dimiliki catatan
parentIdnumberCatatan data formulir induk

📊 Tabel Referensi Cepat​

MetodeDeskripsiKasus Penggunaan
postFormsData()Kirim data formulir baruPengguna mengirim formulir kontak
getFormsDataByMarker()Dapatkan pengiriman untuk formulir tertentuLihat semua pengiriman formulir kontak
updateFormsDataByid() 🔐Perbarui pengiriman formulir berdasarkan idEdit pengiriman yang disimpan
updateFormsDataStatusByid() 🔐Perbarui status pengiriman berdasarkan idTandai sebagai diproses/diarsipkan
deleteFormsDataByid() 🔐Hapus pengiriman formulir berdasarkan idHapus pengiriman
getFormsDataByVectorSearch()Pencarian semantik (vektor) untuk data formulirTemukan pengiriman berdasarkan makna, bukan kata kunci

🔐 metode memerlukan otorisasi pengguna — lihat AuthProvider. postFormsData() dan getFormsDataByMarker() bersifat publik.

❓ Pertanyaan yang Sering Diajukan (FAQ)​

Bagaimana cara mengirim formulir?​

Ambil formulir dengan Forms.getFormByMarker(), baca formModuleConfigId dan moduleEntityIdentifier dari moduleFormConfigs-nya, bangun tubuhnya, lalu panggil FormData.postFormsData(body). Lihat bagian Memulai dengan Cepat di atas.

Bisakah saya memperbarui atau menghapus data formulir yang dikirim?​

Ya. Pengiriman dapat diubah atau dihapus melalui SDK (ini memerlukan otorisasi pengguna):

  • updateFormsDataByid() — edit pengiriman yang disimpan berdasarkan id
  • updateFormsDataStatusByid() — ubah hanya status pengiriman berdasarkan id
  • deleteFormsDataByid() — hapus pengiriman berdasarkan id

Bagaimana cara menangani unggahan file dalam formulir?​

Kirimkan File / FileList / Blob sebagai value field dan postFormsData() akan mengunggahnya untuk Anda, atau unggah secara terpisah dengan modul FileUploading dan sertakan URL yang dikembalikan dalam formData.

Bagaimana cara memfilter pengiriman berdasarkan tanggal?​

Kirimkan dateFrom dan dateTo dalam body permintaan getFormsDataByMarker().

Bagaimana cara melakukan paginasi melalui semua pengiriman?​

Gunakan argumen offset dan limit dari getFormsDataByMarker().

🎓 Praktik Terbaik​

  • Cache konfigurasi formulir (formModuleConfigId, moduleEntityIdentifier) untuk menghindari pengambilan ulang formulir pada setiap pengiriman.
  • Validasi field yang diperlukan di sisi klien sebelum mengirim; OneEntry juga memvalidasi di sisi server.
  • Paginasi pembacaan dengan offset / limit daripada mengambil semuanya sekaligus.
  • Referensikan formulir berdasarkan marker, bukan berdasarkan ID numerik.
  • Gunakan field status (dan updateFormsDataStatusByid) untuk mengorganisir pengiriman.
  • Tangani kesalahan dengan try/catch dan periksa bentuk pengembalian IError.

🔗 Dokumentasi Terkait​