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

مقدمة

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

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

🎯 ماذا تفعل هذه الوحدة؟​

تتيح لك وحدة 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 لمعالجة الأخطاء

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

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

تعريف وحدة Forms​


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

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

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