انتقل إلى المحتوى الرئيسي

المقدمة

تعامل مع تقديمات النماذج واسترجاع بيانات النماذج.

مزيد من المعلومات حول النماذج في لوحة تحكم OneEntry: https://doc.oneentry.cloud/docs/category/forms

🎯 ماذا يفعل هذا الموديل؟​

يتيح لك موديل FormData تقديم النماذج المملوءة من قبل المستخدمين (نماذج الاتصال، الاستطلاعات، التسجيلات) إلى OneEntry و استرجاع، تحديث، أو حذف البيانات المقدمة للتحليل، والتقارير، والإدارة.

فكر في الأمر كمدير تقديمات النماذج الخاص بك - يقوم المستخدمون بتقديم النماذج، وأنت تخزنها في OneEntry، وتسترجعها كلما احتجت لمشاهدة الردود، أو توليد التقارير، أو تحليل البيانات.

🚀 البدء السريع​

قم بتهيئة الموديل من defineOneEntry:


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

قم ببناء الجسم من تكوين النموذج وقدمها:

// 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);

لقراءة التقديمات لاحقًا، استدعِ getFormsDataByMarker(marker, formModuleConfigId, body?, isExtended?, langCode?, offset?, limit?).

✨ المفاهيم الأساسية​

ما هي بيانات النموذج؟​

بيانات النموذج هي المعلومات التي يقدمها المستخدمون من خلال نموذج. يتم بناء كل تقديم من مصفوفة formData من كائنات الحقول (marker, type, value) بالإضافة إلى معرفات تكوين النموذج.

هيكل جسم التقديم​

تقبل postFormsData كائن 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' },
  ],
};

📋 ما تحتاج لمعرفته​

يتطلب التقديم تكوين النموذج​

قبل التقديم، تحتاج إلى ثلاث قيم، جميعها تُقرأ من النموذج نفسه:

  1. علامة النموذج (formIdentifier) — المعرف النصي للنموذج
  2. formModuleConfigId — من moduleFormConfigs للنموذج
  3. moduleEntityIdentifier — من moduleFormConfigs للنموذج
const form = await Forms.getFormByMarker('contact_form');
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

قم بتخزين هذه القيم حتى لا تحتاج إلى إعادة جلب النموذج في كل تقديم.

حقول formData​

كل إدخال في مصفوفة formData يصف حقلًا واحدًا:

  • marker — يجب أن يتطابق مع علامة حقل من تعريف النموذج
  • type — نوع الحقل (يستخدم للتحقق من الصحة ومعالجة الملفات)
  • value — إدخال المستخدم

تُرفع الحقول من نوع file / image / groupOfImages تلقائيًا من خلال موديل FileUploading عندما تمرر File/FileList/Blob كقيمة.

حالة التقديم​

استخدم حقل status لتتبع حالة التقديم. "sent" هي القيمة النموذجية للتقديمات الجديدة؛ يمكنك لاحقًا نقل تقديم إلى حالة تمت مراجعته/أرشفته باستخدام updateFormsDataStatusByid().

تحديث وحذف التقديمات​

التقديمات ليست غير قابلة للتغيير. يمكن للمستخدمين المصرح لهم تغييرها أو إزالتها:

  • updateFormsDataByid(id, body) — تحرير تقديم مخزن بواسطة المعرف 🔐
  • updateFormsDataStatusByid(id, body) — تغيير حالة تقديم فقط بواسطة المعرف 🔐
  • deleteFormsDataByid(id) — حذف تقديم بواسطة المعرف 🔐

قراءة التقديمات​

تُرجع getFormsDataByMarker التقديمات لنموذج معين. يمكنك التنقل عبر النتائج باستخدام offset / limit، وتضييقها باستخدام جسم الطلب (مثل status, dateFrom, dateTo, userIdentifier).

📊 جدول المرجع السريع​

الطريقةالوصفحالة الاستخدام
postFormsData()تقديم بيانات نموذج جديدةيقدم المستخدم نموذج الاتصال
getFormsDataByMarker()الحصول على التقديمات لنموذج معينعرض جميع تقديمات نموذج الاتصال
updateFormsDataByid() 🔐تحديث تقديم نموذج بواسطة المعرفتحرير تقديم مخزن
updateFormsDataStatusByid() 🔐تحديث حالة تقديم بواسطة المعرفوضع علامة كمعالجة/أرشفة
deleteFormsDataByid() 🔐حذف تقديم نموذج بواسطة المعرفإزالة تقديم

🔐 تتطلب الطرق إذن المستخدم — انظر AuthProvider. postFormsData() و getFormsDataByMarker() هما عامان.

❓ الأسئلة الشائعة (FAQ)​

كيف أقدم نموذجًا؟​

احصل على النموذج باستخدام Forms.getFormByMarker()، اقرأ formModuleConfigId و moduleEntityIdentifier من moduleFormConfigs الخاصة به، قم ببناء الجسم، ثم استدعِ FormData.postFormsData(body). انظر قسم البدء السريع أعلاه.

هل يمكنني تحديث أو حذف بيانات النموذج المقدمة؟​

نعم. يمكن تغيير أو إزالة التقديمات عبر SDK (تتطلب هذه إذن المستخدم):

  • updateFormsDataByid() — تحرير تقديم مخزن بواسطة المعرف
  • updateFormsDataStatusByid() — تغيير حالة تقديم فقط بواسطة المعرف
  • deleteFormsDataByid() — حذف تقديم بواسطة المعرف

كيف أتعامل مع تحميل الملفات في النماذج؟​

مرر File / FileList / Blob كقيمة حقل و postFormsData() يقوم بتحميلها لك، أو قم بالتحميل بشكل منفصل باستخدام موديل FileUploading وضمن URLs المعادة في formData.

كيف أفلتر التقديمات حسب التاريخ؟​

مرر dateFrom و dateTo في جسم الطلب لـ getFormsDataByMarker().

كيف أتنقل عبر جميع التقديمات؟​

استخدم معطيات offset و limit لـ getFormsDataByMarker().

🎓 أفضل الممارسات​

  • قم بتخزين تكوين النموذج (formModuleConfigId, moduleEntityIdentifier) لتجنب إعادة جلب النموذج في كل تقديم.
  • تحقق من صحة الحقول المطلوبة على جانب العميل قبل التقديم؛ OneEntry أيضًا يتحقق من الصحة على جانب الخادم.
  • قم بالتنقل في القراءة باستخدام offset / limit بدلاً من جلب كل شيء دفعة واحدة.
  • قم بالإشارة إلى النماذج بواسطة العلامة، وليس بواسطة المعرف الرقمي.
  • استخدم حقل status (و updateFormsDataStatusByid) لتنظيم التقديمات.
  • تعامل مع الأخطاء باستخدام try/catch وتحقق من شكل إرجاع IError.

🔗 الوثائق ذات الصلة​