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

المقدمة

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

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

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

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

📖 شرح بسيط​

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

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

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

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

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

Without Forms Module (manual):
- Build form HTML/validation manually ❌
- Set up backend to store submissions ❌
- Create database tables ❌
- Build admin panel to view responses ❌
- Write email notification code ❌

With Forms Module (automated):
- Create form in admin panel ✅
- Fetch form structure via API ✅
- Submit data → Auto-stored ✅
- View responses in dashboard ✅
- Auto email notifications ✅

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

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

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

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

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

1. Create form in OneEntry admin
   ↓
2. Define fields (name, email, message, etc.)
   ↓
3. Set validation rules
   ↓
4. Fetch form structure via SDK
   ↓
5. Render form in your app
   ↓
6. User fills form
   ↓
7. Submit data to OneEntry
   ↓
8. Validation happens
   ↓
9. Data stored in database
   ↓
10. Notifications sent (email, webhook)

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

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

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

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

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

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

{
  id: 123,
  marker: "contact_form",   // Unique identifier
  localizeInfos: {
    title: "Contact Us",    // Form title
    description: "Get in touch" // Form description
  },
  fields: [   // Form fields
    {
      marker: "name",
      type: "text",
      localizeInfos: { title: "Name" },
      isRequired: true,
      validation: { minLength: 2, maxLength: 50 }
    },
  ],
  statusId: 1,                 // 1 = active, 0 = draft
  isActive: true,              // Is form enabled
  successMessage: "Thank you!" // Message after submission
}

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

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

{
  "marker": "email",
  "type": "email",
  "isRequired": true, // Must be filled
  "validation": {
    "format": "email",  // Must be valid email
    "minLength": 5,     // Min 5 characters
    "maxLength": 100,   // Max 100 characters
    "pattern": "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$"  // Custom regex
  }
}

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

  • isRequired - يجب ملء الحقل
  • minLength - الحد الأدنى لطول النص
  • maxLength - الحد الأقصى لطول النص
  • format - تنسيق البريد الإلكتروني، الهاتف، عنوان URL
  • pattern - نمط regex مخصص
  • 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 - إدارة المستخدمين الذين يقدمون النماذج