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

مقدمة

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

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

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

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

📖 شرح بسيط​

تخيل أن لديك نموذج اتصال على موقعك. عندما يقوم المستخدمون بملئه:

  1. تقديم - ينقر المستخدم على "إرسال" → تذهب بيانات النموذج إلى OneEntry
  2. تخزين - يقوم OneEntry بحفظ التقديم (الاسم، البريد الإلكتروني، الرسالة)
  3. استرجاع - تقوم بجلب التقديمات لعرضها، أو تصديرها، أو تحليلها
  4. إدارة - تصفية، بحث، وتنظيم ردود النماذج

سير العمل في العالم الحقيقي:

يملأ المستخدم نموذج الاتصال
↓
postFormsData() → محفوظ في OneEntry
↓
getFormsDataByMarker() → يعيد OneEntry البيانات
↓
يستعرض المسؤول التقديمات

ما يمكنك القيام به:

  • 📤 تقديم النماذج - إرسال البيانات المملوءة من قبل المستخدمين إلى OneEntry
  • 📥 عرض التقديمات - الحصول على جميع ردود النماذج مع الترقيم
  • 🔍 البحث في التقديمات - العثور على تقديمات محددة بواسطة علامة أو فلتر
  • 📊 تصدير البيانات - استرجاع التقديمات للتقارير والتحليل
  • 📧 إدارة الردود - تتبع تقديمات النماذج في مكان واحد

سيناريوهات مثال:

السيناريوماذا يحدث
نموذج الاتصاليقوم المستخدم بالتقديم → تتلقى إشعار عبر البريد الإلكتروني → عرض في لوحة التحكم
استطلاعجمع الردود → تصدير إلى CSV → تحليل النتائج
تسجيليقوم المستخدم بالتسجيل → يتم تخزين البيانات → إرسال بريد تأكيد
تعليقاتيترك العميل تعليقات → يقوم الفريق بمراجعتها → الرد على العميل

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

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

بيانات النموذج هي المعلومات التي يقدمها المستخدمون من خلال النماذج

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

كل تقديم في OneEntry يحتوي على:

  const body: IBodyPostFormData = {
    formIdentifier: 'contact_form', // علامة النموذج
    formModuleConfigId: 9,          // معرف إعدادات الموديل
    moduleEntityIdentifier: 'blog', // معرف كيان الموديل
    replayTo: null,                 // عنوان البريد الإلكتروني للرد عليه
    status: 'sent',                 // حالة التقديم
    formData: [                     // حقول النموذج
      {
        marker: 'string',           // علامة الحقل
        type: 'string',             // نوع الحقل
        value: 'Test',              // قيمة الحقل
      },
    ]
  };

دورة حياة بيانات النموذج​

1. يملأ المستخدم النموذج في المتصفح
   ↓
2. يتحقق الواجهة الأمامية من صحة الإدخال
   ↓
3. postFormsData() ترسل إلى OneEntry
   ↓
4. يتحقق OneEntry ويخزن تقديم بيانات النموذج
   ↓
5. يتم إرسال الإشعارات (البريد الإلكتروني، الويب هوك)
   ↓
6. يسترجع المسؤول باستخدام getFormsDataByMarker()
   ↓
7. مراجعة، تصدير، أو الرد

حالات الاستخدام الشائعة​

حالة الاستخدامالوصفالمثال
نماذج الاتصاليتواصل العملاء مع أسئلةيقوم فريق الدعم بمراجعة والرد
توليد العملاء المحتملينجمع معلومات العملاء المحتملينيتابع فريق المبيعات
استطلاعاتجمع التعليقات والآراءيقوم التسويق بتحليل النتائج
التسجيلاتالتسجيل في الأحداث، النشراتتتبع الحضور/المشتركين
طلبات العملجمع السير الذاتية ورسائل التغطيةتقوم الموارد البشرية بمراجعة المرشحين
نماذج التعليقاترضا العملاء والتعليقاتتحسين المنتجات/الخدمات

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

تقديم النماذج يتطلب إعدادات​

قبل التقديم، تحتاج إلى:

  1. علامة النموذج - معرف نص فريد للنموذج
  2. معرف إعدادات الموديل - من إعدادات النموذج
  3. معرف كيان الموديل - من إعدادات النموذج

كيفية الحصول على هذه:

// جلب النموذج
const form = await Forms.getFormByMarker('contact_form');

// استخراج المعرفات المطلوبة
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// الآن يمكنك التقديم

لماذا تحتاجها؟ يحتاج OneEntry إلى معرفة:

  • أي قالب نموذج يجب استخدامه
  • أين يتم تخزين البيانات
  • ما هي قواعد التحقق التي يجب تطبيقها

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

تحتوي مصفوفة formData على كائنات الحقول:

formData: [
  {
    marker: "field_name", // معرف الحقل
    type: "text"          // نوع الحقل
    value: "user_input",  // إدخال المستخدم
  }
]

مهم:

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

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

استخدم status لتتبع حالة التقديم:

الحالةالمعنىمتى تستخدم
"sent"تم تقديمه بنجاحالافتراضي للتقديمات الجديدة
"pending"في انتظار المراجعةيتطلب الاعتدال
"processed"تم التعامل معه بواسطة المسؤولتم وضع علامة كمراجعة
"archived"تقديم قديم/مغلقالاحتفاظ بالسجلات

الترقيم​

استرجع التقديمات في دفعات.

علامة النموذج​

طريقة واحدة لتحديد التقديمات:

المعرفما هومتى تستخدم
علامة النموذجمعرف قالب النموذجالحصول على جميع التقديمات لنموذج معين

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

الطريقةالوصفحالة الاستخدام
postFormsData()تقديم بيانات نموذج جديدةيقوم المستخدم بتقديم نموذج الاتصال
getFormsDataByMarker()الحصول على التقديمات لنموذج معينعرض جميع تقديمات نموذج الاتصال

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

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

تحتاج إلى ثلاثة أشياء:

  1. إعداد النموذج من Forms.getFormByMarker()
  2. بيانات إدخال المستخدم
  3. استدعاء FormData.postFormsData()

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

ليس مباشرة. عادةً ما تكون تقديمات النماذج غير قابلة للتغيير للحفاظ على سلامة البيانات.

الحلول البديلة:

  • تقديم نسخة جديدة مع بيانات محدثة
  • استخدام حقل status لوضع علامة على التقديمات القديمة على أنها غير صالحة
  • تنفيذ منطق تحديث مخصص في الواجهة الأمامية الخاصة بك

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

استخدم ببساطة File أو FileList مع FormData.postFormsData() أو قم بتحميل الملفات بشكل منفصل باستخدام موديل FileUploading، ثم قم بتضمين روابط الملفات في بيانات النموذج

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

استخدم معلمات الجسم dateFrom و dateTo.

هل يمكنني البحث في التقديمات حسب قيمة الحقل؟​

نعم، قم بجلب التقديمات وابحث في الجانب العميل

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

استخدم offset و limit

كيف أتعامل مع أخطاء التحقق؟​

استخدم try/catch وتحقق من رسائل الخطأ

💡 ملاحظات مهمة​

⚠️ يتطلب إعداد النموذج​

لا يمكنك تقديم النماذج بدون إعداد:

  • formModuleConfigId و moduleEntityIdentifier هما مطلوبان
  • احصل على هذه من Forms.getFormByMarker() قبل التقديم
  • قم بتخزينها في تطبيقك لتجنب المكالمات المتكررة لواجهة برمجة التطبيقات

🔒 اعتبارات الأمان​

لا تكشف عن البيانات الحساسة:

  • لا تقدم كلمات المرور كنص عادي
  • تحقق من الإدخال على كل من العميل والخادم
  • قم بتنظيف إدخال المستخدم قبل العرض

📦 مجموعات البيانات الكبيرة​

الترقيم مهم:

  • لا تقم بجلب آلاف التقديمات دفعة واحدة
  • استخدم limit و offset للترقيم
  • ضع في اعتبارك التخزين المؤقت للبيانات التي يتم الوصول إليها بشكل متكرر

🔄 قراءة فقط بعد التقديم​

بيانات النموذج غير قابلة للتغيير:

  • لا يمكن تحديث التقديمات عبر SDK
  • قدم نسخة جديدة إذا كانت التغييرات مطلوبة
  • استخدم حقل status لتتبع حالة التقديم

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

  • تخزين إعدادات النموذج في الذاكرة - تجنب الجلب في كل تقديم
  • تحقق قبل التقديم - تحقق من الحقول المطلوبة على جانب العميل
  • استخدم الترقيم - جلب التقديمات في دفعات
  • تعامل مع الأخطاء بشكل لطيف - استخدم دائمًا try/catch
  • استخدم العلامات بشكل متسق - ارجع إلى النماذج بواسطة العلامة، وليس المعرف
  • تتبع حالة التقديم - استخدم حقل الحالة لتنظيم التقديمات
  • تصدير البيانات بانتظام - احتفظ بنسخ احتياطية للتقديمات إلى CSV/قاعدة البيانات
  • راقب التقديمات الجديدة - نفذ الاستطلاع أو الويب هوك

تعريف موديل FormData​


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

إعدادات النموذج:​

  1. احصل على النموذج بواسطة العلامة باستخدام Forms.getFormByMarker('your-form-marker').
  2. استخدم حقل moduleFormConfigs من النموذج المسترجع للإعدادات المستخدمة عند تقديم بيانات النموذج.
  3. أنشئ الجسم باستخدام moduleFormConfig وقدم بيانات النموذج.


const formModuleConfigId = moduleFormConfigs[0].id;
const moduleEntityIdentifier = moduleFormConfigs[0].entityIdentifiers[0].id;

const body = {
  "formIdentifier": "your-form-marker",
  "formModuleConfigId": formModuleConfigId,
  "moduleEntityIdentifier": moduleEntityIdentifier,
  "replayTo": null,
  "status": "sent",
  "formData": [...]
};

const response = await FormData.postFormsData(body);

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