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

مقدمة

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

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

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

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

📖 شرح بسيط​

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

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

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

User fills contact form
↓
postFormsData() → Saved in OneEntry
↓
getFormsDataByMarker() → OneEntry returns data
↓
Admin views submissions

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

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

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

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

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

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

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

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

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

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

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

1. User fills form in browser
   ↓
2. Frontend validates input
   ↓
3. postFormsData() sends to OneEntry
   ↓
4. OneEntry validates & stores form data submission
   ↓
5. Notifications sent (email, webhook)
   ↓
6. Admin retrieves with getFormsDataByMarker()
   ↓
7. Review, export, or respond

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

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

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

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

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

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

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

// Fetch form
const form = await Forms.getFormByMarker('contact_form');

// Extract required IDs
const formModuleConfigId = form.moduleFormConfigs[0].id;
const moduleEntityIdentifier = form.moduleFormConfigs[0].entityIdentifiers[0].id;

// Now you can submit

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

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

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

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

formData: [
  {
    marker: "field_name", // Field identifier
    type: "text"          // Field type
    value: "user_input",  // User's 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، ثم قم بتضمين عناوين URL للملفات في بيانات النموذج

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

استخدم معلمات الجسم 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);

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