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

المقدمة

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

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

يتيح لك موديل Forms استرجاع النماذج - نماذج الاتصال، الاستطلاعات، التسجيلات، نماذج التعليقات - وجمع تقديمات المستخدمين مع التحقق، وتحميل الملفات، والإشعارات التلقائية.

فكر في الأمر كأداة بناء النماذج الخاصة بك - تقوم بإنشاء النماذج في لوحة تحكم OneEntry، وعرضها في تطبيقك، وجمع الردود تلقائيًا.

📖 شرح بسيط​

تخيل أنك بحاجة لجمع المعلومات من المستخدمين:

  • 📞 نموذج الاتصال - الاسم، البريد الإلكتروني، الرسالة، الهاتف
  • 📋 استطلاع - أسئلة متعددة الخيارات، تقييمات
  • 👤 نموذج التسجيل - تفاصيل المستخدم، التفضيلات
  • 💼 طلب وظيفة - تحميل السيرة الذاتية، خطاب التقديم
  • 📝 نموذج التعليقات - تقييمات، تعليقات، اقتراحات
  • 🎟️ تسجيل الحدث - معلومات الحضور، اختيار التذاكر

بدلاً من بناء النماذج من الصفر:

  • ✅ إنشاء النماذج في لوحة تحكم OneEntry (سحب وإفلات الحقول)
  • ✅ استرجاع هيكل النموذج ديناميكيًا
  • ✅ تقديم البيانات إلى OneEntry (تخزين تلقائي)
  • ✅ التحقق من الحقول (مطلوب، تنسيق البريد الإلكتروني، أنواع الملفات)
  • ✅ الحصول على إشعارات عند تقديم النماذج
  • ✅ عرض الردود في لوحة التحكم الإدارية

مثال من العالم الحقيقي:

بدون موديل النماذج (يدوي):
- بناء HTML/التحقق من النموذج يدويًا ❌
- إعداد الخلفية لتخزين التقديمات ❌
- إنشاء جداول قاعدة البيانات ❌
- بناء لوحة تحكم إدارية لعرض الردود ❌
- كتابة كود إشعار البريد الإلكتروني ❌

مع موديل النماذج (تلقائي):
- إنشاء نموذج في لوحة التحكم الإدارية ✅
- استرجاع هيكل النموذج عبر API ✅
- تقديم البيانات → تخزين تلقائي ✅
- عرض الردود في لوحة التحكم ✅
- إشعارات البريد الإلكتروني التلقائية ✅

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

ما هو النموذج؟​

النموذج هو وسيلة منظمة لجمع المعلومات من المستخدمين:

  • الحقول - عناصر الإدخال (نص، بريد إلكتروني، مربعات اختيار، تحميل ملفات)
  • التحقق - القواعد (مطلوب، تنسيق، الحد الأدنى/الحد الأقصى للطول)
  • التقديمات - ردود المستخدمين المخزنة في قاعدة البيانات
  • الهيكل - تخطيط النموذج المحدد في OneEntry
  • ديناميكي - استرجاع هيكل النموذج من API، وعرضه في تطبيقك

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

1. إنشاء نموذج في لوحة تحكم OneEntry
   ↓
2. تحديد الحقول (الاسم، البريد الإلكتروني، الرسالة، إلخ)
   ↓
3. تعيين قواعد التحقق
   ↓
4. استرجاع هيكل النموذج عبر SDK
   ↓
5. عرض النموذج في تطبيقك
   ↓
6. يقوم المستخدم بملء النموذج
   ↓
7. تقديم البيانات إلى OneEntry
   ↓
8. يحدث التحقق
   ↓
9. يتم تخزين البيانات في قاعدة البيانات
   ↓
10. إرسال الإشعارات (البريد الإلكتروني، webhook)

أنواع حقول النموذج​

أنواع الحقول الشائعة التي يمكنك استخدامها:

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

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

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

كل نموذج يحتوي على هذه الحقول الأساسية:

{
  id: 123,
  marker: "contact_form",   // معرف فريد
  localizeInfos: {
    title: "اتصل بنا",    // عنوان النموذج
    description: "تواصل معنا" // وصف النموذج
  },
  fields: [   // حقول النموذج
    {
      marker: "name",
      type: "text",
      localizeInfos: { title: "الاسم" },
      isRequired: true,
      validation: { minLength: 2, maxLength: 50 }
    },
  ],
  statusId: 1,                 // 1 = نشط، 0 = مسودة
  isActive: true,              // هل النموذج مفعل
  successMessage: "شكرًا لك!" // رسالة بعد التقديم
}

التحقق من الحقول​

يمكن أن تحتوي كل حقل على قواعد تحقق:

{
  "marker": "email",
  "type": "email",
  "isRequired": true, // يجب ملؤه
  "validation": {
    "format": "email",  // يجب أن يكون بريد إلكتروني صالح
    "minLength": 5,     // الحد الأدنى 5 أحرف
    "maxLength": 100,   // الحد الأقصى 100 حرف
    "pattern": "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$"  // تعبير عادي مخصص
  }
}

قواعد التحقق الشائعة:

  • isRequired - يجب ملء الحقل
  • minLength - الحد الأدنى لطول النص
  • maxLength - الحد الأقصى لطول النص
  • format - تنسيق البريد الإلكتروني، الهاتف، URL
  • pattern - نمط تعبير عادي مخصص
  • min / max - نطاق الأرقام
  • fileTypes - أنواع الملفات المسموح بها
  • maxFileSize - الحد الأقصى لحجم الملف

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

الطريقةماذا تفعلمتى تستخدم
getAllForms()الحصول على جميع النماذج (مقيدة)قائمة بجميع النماذج المتاحة
getFormByMarker()الحصول على نموذج بواسطة العلامةاسترجاع نموذج محدد في الكود

ملاحظة: لإنشاء/تعديل النماذج، استخدم لوحة تحكم OneEntry. SDK مخصص لاسترجاع النماذج وتقديم البيانات.

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

كيف يمكنني إنشاء أو تعديل النماذج؟​

تُنشأ النماذج في لوحة تحكم OneEntry:

  1. تسجيل الدخول إلى لوحة تحكم OneEntry
  2. الانتقال إلى قسم النماذج
  3. إنشاء نموذج جديد أو تعديل نموذج موجود
  4. إضافة الحقول (سحب وإفلات)
  5. تكوين قواعد التحقق
  6. تفعيل النموذج

SDK مخصص لاسترجاع النماذج وتقديم البيانات، وليس لإنشاء النماذج.

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

استخدم التحقق من المتصفح + الفحوصات اليدوية:

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

نعم! استخدم موديل FileUploading وأضف file إلى حقل النموذج الخاص بك:

تعلم المزيد: FormsData Module

هل يمكنني إرسال إشعارات مخصصة عند تقديم النموذج؟​

نعم، قم بتكوين ذلك في لوحة تحكم OneEntry:

  • إشعارات البريد الإلكتروني إلى المسؤول/المستخدم
  • إشعارات webhook إلى خادمك
  • التكامل مع موديل الأحداث

كيف يمكنني التعامل مع أخطاء تقديم النموذج؟​

استخدم دائمًا try/catch

هل يمكن أن تحتوي النماذج على حقول شرطية (عرض/إخفاء بناءً على حقول أخرى)؟​

ليس مباشرة في SDK، ولكن يمكنك تنفيذ ذلك في واجهة المستخدم الخاصة بك

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

تُنشأ النماذج في لوحة التحكم​

تذكر: SDK مخصص لـ استرجاع النماذج و تقديم البيانات، وليس لإنشاء النماذج.

لإنشاء/تعديل النماذج: استخدم لوحة تحكم OneEntry أو واجهة برمجة التطبيقات الإدارية.

تحقق دائمًا من البيانات​

✅ التحقق من جانب العميل ليس كافيًا:

  • تحقق على العميل (تجربة مستخدم أفضل)
  • تحقق على الخادم (OneEntry يقوم بذلك تلقائيًا)

تعامل مع تحميل الملفات بعناية​

✅ أفضل الممارسات لتحميل الملفات:

  • تحقق من نوع الملف قبل التحميل
  • تحقق من حدود حجم الملف
  • عرض تقدم التحميل
  • التعامل مع أخطاء التحميل

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

✅ ما يجب فعله:

  • استخدم العلامات للإشارة إلى النماذج (ليس المعرفات)
  • تحقق من البيانات على العميل والخادم
  • عرض حالات التحميل أثناء التقديم
  • تقديم رسائل خطأ واضحة
  • تعطيل زر التقديم بعد التقديم الناجح
  • مسح النموذج بعد التقديم الناجح
  • التعامل مع أخطاء تحميل الملفات بشكل لطيف
  • استخدم try/catch للتعامل مع الأخطاء

❌ ما لا يجب فعله:

  • ترميز معرفات النماذج في الكود
  • تقديم النماذج بدون تحقق
  • تجاهل التعامل مع الأخطاء
  • السماح بالتقديمات المكررة
  • تحميل الملفات بدون تحقق من الحجم/النوع
  • عرض الأخطاء التقنية للمستخدمين
  • نسيان تقديم ملاحظات للمستخدم
  • تخطي حالات التحميل

مزيد من المعلومات حول واجهة المستخدم للموديل https://doc.oneentry.cloud/docs/forms/introduction

تعريف موديل النماذج​


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

يمكن العثور على أمثلة الاستخدام المتقدمة في مقدمة النماذج.

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

  • FormsData Module - عرض وإدارة تقديمات النماذج
  • Events Module - إعداد إشعارات تلقائية عند تقديم النموذج
  • FileUploading Module - التعامل مع تحميل الملفات في النماذج
  • Users Module - إدارة المستخدمين الذين يقدمون النماذج