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

مقدمة

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

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

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

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

📖 شرح بسيط​

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

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

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

يملأ المستخدم نموذج الاتصال → postFormsData() → محفوظ في OneEntry
                                                              ↓
يستعرض المسؤول التقديمات ← getFormsData() ← 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',              // قيمة الحقل
      },
      {
        marker: 'number',
        type: 'integer',
        value: 1,
      },
    ]
  };

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

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

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

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

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

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

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

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

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

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

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

قم بتحميل الملفات بشكل منفصل باستخدام موديل FileUploading، ثم قم بتضمين عناوين URL للملفات في بيانات النموذج:

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

احصل على جميع التقديمات وقم بالتصفية على جانب العميل

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

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

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

استخدم الإزاحة والحد الأقصى

ما الفرق بين getFormsData() و getFormsDataByMarker()؟​

الطريقةما تعيدهمتى تستخدم
getFormsData()جميع التقديمات من جميع النماذجلوحة تحكم المسؤول تعرض كل شيء
getFormsDataByMarker()التقديمات لنموذج واحد محددعرض فقط تقديمات نموذج الاتصال

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

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

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

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

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

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

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

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

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

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

الترقيم مهم:

  • لا تقم بجلب آلاف التقديمات دفعة واحدة
  • استخدم 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);

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