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

المقدمة

حدد حقولًا مخصصة لمحتواك دون الحاجة إلى تعديل الكود.

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

يتيح لك موديل AttributesSets استخدام حقول مخصصة لمحتواك (المنتجات، الصفحات، النماذج، إلخ) دون الحاجة إلى ترميزها في تطبيقك.

فكر في الأمر كمنشئ نماذج لبياناتك - أنت تحدد الحقول التي تحتاجها، وOneEntry تتولى الباقي.

📖 شرح بسيط​

تخيل أنك تبني متجرًا عبر الإنترنت. كل منتج يحتاج إلى:

  • اسم (نص)
  • سعر (رقم)
  • صورة (صورة)
  • وصف (نص طويل)
  • فئة (قائمة منسدلة)

بدلاً من ترميز هذه الحقول في تطبيقك، تستخدم Attributes لتعريفها في لوحة إدارة OneEntry. ثم يمكنك:

  • ✅ إضافة حقول جديدة في أي وقت (لا تغييرات في الكود!)
  • ✅ إعادة استخدام الحقول عبر أنواع محتوى مختلفة
  • ✅ تغيير أنواع الحقول دون إعادة نشر
  • ✅ إدارة هيكل المحتوى بالكامل في مكان واحد

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

بدون Attributes (مشفرة):
- الكود: const product = { name, price, image, description }
- لإضافة حقل "اللون" → تغيير الكود، إعادة النشر، الانتظار ❌

مع Attributes (ديناميكي):
- لوحة الإدارة: إضافة خاصية "اللون"
- الكود يتضمن الحقل الجديد تلقائيًا ✅
- لا حاجة للنشر! ✅

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

ما هو السمة؟​

السمة هي حقل واحد يخزن البيانات.

أمثلة:

  • اسم المنتج (سلسلة نصية)
  • سعر المنتج (عدد عشري)
  • صورة المنتج (صورة)
  • تاريخ النشر (تاريخ)

ما هو مجموعة السمات؟​

مجموعة السمات هي مجموعة من السمات التي تحدد هيكلًا.

مثال: مجموعة سمات المنتج

- الاسم (سلسلة نصية)
- السعر (عدد عشري)
- الوصف (نص)
- الصور (مجموعة من الصور)
- الفئة (قائمة)
- في المخزون (عدد صحيح)

لماذا تستخدم مجموعات السمات؟​

بدون السماتمع السمات
❌ حقول مشفرة✅ حقول ديناميكية
❌ تغييرات في الكود مطلوبة✅ تعديل في لوحة الإدارة
❌ إعادة نشر مطلوبة✅ تحديثات مباشرة
❌ هيكل صارم✅ هيكل مرن
❌ كود مكرر✅ مجموعات قابلة لإعادة الاستخدام

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

ثلاثة مصطلحات مهمة​

المصطلحما هومثال
المؤشرمعرف فريد للكود"product_name"
النوعنوع البيانات المخزنة"string"، "integer"، "image"
القيمةقيمة السمة"اسم المنتج"

مهم حول المؤشرات:

  • يجب أن تكون فريدة
  • لا يُسمح بالمسافات (استخدم _ بدلاً من ذلك)
  • لا يمكن أن تبدأ برقم
  • استخدم الحروف الصغيرة للاتساق

أمثلة:

  • ✅ جيد: product_name، price_usd، main_image
  • ❌ سيء: product name، 2nd_price، Product Name

إعادة الاستخدام​

يمكن إعادة استخدام مجموعات السمات عبر كيانات مختلفة:

مجموعة سمات "المعلومات الأساسية":
- العنوان (سلسلة نصية)
- الوصف (نص)
- تاريخ النشر (تاريخ)

تستخدم من قبل:
✅ مقالات المدونة
✅ مقالات الأخبار
✅ صفحات المنتجات
✅ قوائم الأحداث

لماذا يهم هذا: تغيير واحد، تحديثات في كل مكان!

📚 أنواع البيانات المتاحة​

يمكن أن تخزن السمات أنواعًا مختلفة من البيانات. اختر النوع المناسب لكل حقل.

جدول مرجعي سريع​

النوعالأفضل للاستخداممثال الاستخدام
stringنص قصيراسم المنتج، البريد الإلكتروني
textنص طويل منسقمقالة، وصف
textWithHeaderنص مع عنوانأقسام المقالات
integerأعداد صحيحةالكمية، العمر
realأعداد عشرية عالية الدقةبيانات علمية
floatأعداد عشريةالسعر، التقييم
dateمجرد التاريختاريخ الميلاد، الموعد النهائي
dateTimeالتاريخ + الوقتبدء الحدث، نشر في
timeمجرد الوقتساعات العمل
fileأي ملفPDF، مستند
imageصورة واحدةصورة شخصية، شعار
groupOfImagesصور متعددةمعرض الصور
radioButtonاختيار واحدالحجم (S/M/L)
listاختيار من القائمة المنسدلةالدولة، الفئة
entityرابط لمحتوى آخرالمنتجات ذات الصلة
timeIntervalنطاق تاريخيفترة الترويج
jsonبيانات مهيكلة مخصصةاستجابة API

🔍 أوصاف مفصلة لأنواع البيانات​

أنواع النصوص​

متى تستخدم ماذا:

  • string - سطر واحد، أقل من 255 حرفًا (اسم، بريد إلكتروني، عنوان)
  • text - عدة فقرات، يدعم التنسيق (مقالات، أوصاف)
  • textWithHeader - نص يحتاج إلى عنوان (أقسام المدونة، الأسئلة الشائعة)

أنواع الأرقام​

متى تستخدم ماذا:

  • integer - لا حاجة للأعداد العشرية (العمر، الكمية، المشاهدات)
  • float - أعداد عشرية قياسية (السعر 19.99 دولار، التقييم 4.5)
  • real - دقة إضافية مطلوبة (حسابات علمية)

أنواع التاريخ/الوقت​

متى تستخدم ماذا:

  • date - مجرد اليوم (عيد الميلاد، الموعد النهائي)
  • time - مجرد الساعة (ساعات العمل، موعد الاجتماع)
  • dateTime - كلاهما مطلوب (بدء الحدث، نشر المقال)
  • timeInterval - فترة بين التواريخ (مدة البيع، تواريخ الإجازة)

أنواع الملفات والصور​

متى تستخدم ماذا:

  • file - أي مستند (PDF، DOC، ZIP)
  • image - صورة واحدة (صورة المنتج، صورة شخصية)
  • groupOfImages - صور متعددة (معرض، صور المنتجات)

أنواع الاختيار​

متى تستخدم ماذا:

  • radioButton - اختر خيارًا واحدًا فقط (نعم/لا، الحجم S/M/L)
  • list - قائمة منسدلة مع خيارات (الدولة، الفئة، الحالة)

أنواع متقدمة​

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

📖 أمثلة على أنواع البيانات​

فيما يلي أمثلة تقنية على هيكل كل نوع بيانات.

انقر لرؤية جميع أمثلة أنواع البيانات

مرجع أنواع البيانات​

يمكن أن تكون أنواع البيانات من الأنواع التالية:

  • String: نص بسيط، على سبيل المثال، "مرحبًا، العالم!".

مثال:

{
  "type": "string",
  "value": {},
  "marker": "string",
  "position": 1,
  "listTitles": [],
  "validators": {
    "requiredValidator": {
      "strict": true
    }
  },
  "localizeInfos": {
    "title": "String"
  },
  "additionalFields": [
    {
      "type": "integer",
      "value": "10",
      "marker": "Extra"
    }
  ]
}
  • Text: نص أطول، غالبًا ما يكون منسقًا، على سبيل المثال، مقالة أو رسالة.

مثال:

{
  "type": "text",
  "value": {},
  "marker": "text",
  "position": 2,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Text"
  },
  "additionalFields": []
}
  • Text with Header: نص مع عنوان يمكن استخدامه للدلالة على موضوع أو فئة.

مثال:

{
  "type": "textWithHeader",
  "value": {},
  "marker": "text_with_header",
  "position": 3,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Text With Header"
  },
  "additionalFields": []
}
  • Integer: عدد صحيح، على سبيل المثال، 5، 100، -2.

مثال:

{
  "type": "integer",
  "value": {},
  "marker": "integer",
  "position": 4,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Integer"
  },
  "additionalFields": []
}
  • Real: نفس الشيء مثل Float، ولكن بدقة أعلى.

مثال:

{
  "type": "real",
  "value": {},
  "marker": "real_number",
  "position": 5,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Real Number"
  },
  "additionalFields": []
}
  • Float: نوع بيانات للأعداد العشرية التي يمكن أن تحتوي على جزء عشري، على سبيل المثال، 3.14، 1.5، -0.25.

مثال:

{
  "type": "float",
  "value": {},
  "marker": "float",
  "position": 6,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Float"
  },
  "additionalFields": []
}
  • Date and Time: مجموعة من التاريخ والوقت، على سبيل المثال، 2023-10-27 10:00:00.

مثال:

{
  "type": "dateTime",
  "value": {},
  "marker": "date_time",
  "position": 7,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "DateTime"
  },
  "additionalFields": []
}
  • Date: تاريخ، على سبيل المثال، 2023-10-27.

مثال:

{
  "type": "date",
  "value": {},
  "marker": "date",
  "position": 8,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Date"
  },
  "additionalFields": []
}
  • Time: وقت، على سبيل المثال، 10:00:00.

مثال:

{
  "type": "date",
  "value": {},
  "marker": "date",
  "position": 8,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Date"
  },
  "additionalFields": []
}
  • File: أي ملف على جهاز الكمبيوتر الخاص بك، على سبيل المثال، مستند، صورة، موسيقى.

مثال:

{
  "type": "file",
  "value": {},
  "marker": "file",
  "position": 10,
  "listTitles": [],
  "validators": {
    "checkingFilesValidator": {
      "maxUnits": "kb",
      "maxValue": "2000",
      "minUnits": "kb",
      "minValue": 0,
      "extensions": []
    }
  },
  "localizeInfos": {
    "title": "File"
  },
  "additionalFields": []
}
  • Image: صورة، على سبيل المثال، صورة فوتوغرافية، رسم.

مثال:

{
  "type": "image",
  "value": {},
  "marker": "image",
  "position": 11,
  "listTitles": [],
  "validators": {
    "sizeInPixelsValidator": {
      "maxX": "500",
      "maxY": "500"
    }
  },
  "localizeInfos": {
    "title": "Image"
  },
  "additionalFields": []
}
  • Group of Images: مجموعة من الصور، على سبيل المثال، ألبوم صور.

مثال:

{
  "type": "groupOfImages",
  "value": {},
  "marker": "image_group",
  "position": 12,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Image Group"
  },
  "additionalFields": []
}
  • Radio Button: زر اختيار يمكن من خلاله اختيار خيار واحد فقط.

مثال:

{
  "type": "radioButton",
  "value": {},
  "marker": "radio",
  "position": 13,
  "listTitles": [
    {
      "title": "A",
      "value": "a",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 1
    },
    {
      "title": "B",
      "value": "b",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 2
    }
  ],
  "validators": {},
  "localizeInfos": {
    "title": "Radio"
  },
  "additionalFields": []
}
  • List: قائمة من العناصر، على سبيل المثال، قائمة تسوق.

مثال:

{
  "type": "list",
  "value": {},
  "marker": "list",
  "position": 14,
  "listTitles": [
    {
      "title": "A",
      "value": "a",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 1
    },
    {
      "title": "B",
      "value": "b",
      "extended": {
        "type": null,
        "value": null
      },
      "position": 2
    },
    {
      "title": "C",
      "value": "c",
      "extended": {
        "type": "string",
        "value": "قيمة إضافية"
      },
      "position": 3
    }
  ],
  "validators": {},
  "localizeInfos": {
    "title": "List"
  },
  "additionalFields": []
}
  • Entity: كيان يمثل كائنًا.

مثال:

{
  "type": "entity",
  "value": {},
  "marker": "entity",
  "position": 15,
  "listTitles": [
    {
      "title": "المنتجات",
      "value": {
        "id": 1,
        "depth": 0,
        "parentId": null,
        "position": 1,
        "selected": true
      }
    },
    {
      "title": "صفحة عادية",
      "value": {
        "id": 4,
        "depth": 0,
        "parentId": null,
        "position": 2,
        "selected": true
      }
    },
    {
      "title": "خطأ",
      "value": {
        "id": 2,
        "depth": 0,
        "parentId": null,
        "position": 3,
        "selected": true
      }
    }
  ],
  "validators": {},
  "localizeInfos": {
    "title": "Entity"
  },
  "additionalFields": [
    {
      "type": "string",
      "value": "حقل اختبار",
      "marker": "test_field"
    }
  ]
}
  • Time interval: تقويم مرن مع واجهة مستخدم سهلة الاستخدام لإدارة بيانات فترات الوقت.

مثال:

{
  "type": "timeInterval",
  "value": {},
  "marker": "time_interval",
  "position": 16,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Time Interval"
  },
  "additionalFields": []
}
  • JSON: بعض البيانات بتنسيق JSON.

مثال:

{
  "type": "json",
  "value": {},
  "marker": "json",
  "position": 17,
  "listTitles": [],
  "validators": {},
  "localizeInfos": {
    "title": "Json"
  },
  "additionalFields": []
}

ستتوافق واجهة ملء المحتوى مع نوع البيانات المحدد لكل حقل سمة.

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

المدققون​

يمكنك إضافة مدققين للسمات لضمان جودة البيانات:

  • الحقول المطلوبة
  • الحد الأدنى/الحد الأقصى للطول للنص
  • حدود حجم الملف للتحميلات
  • أبعاد البكسل للصور
  • نطاقات التاريخ

تعلم المزيد: انظر قسم "المدققون" للتكوين التفصيلي.

مجموعات السمات المشتركة​

⚠️ مهم: إذا تم استخدام مجموعة سمات واحدة من قبل كيانات متعددة، كن حذرًا عند إجراء تغييرات:

حذف سمة:

  • ❌ يزيلها في كل مكان يتم استخدام المجموعة فيه
  • ❌ يحذف كل المحتوى في هذا الحقل
  • ⚠️ لا يمكن التراجع عنه!

إضافة سمة:

  • ✅ تضاف في كل مكان يتم استخدام المجموعة فيه
  • ✅ المحتوى الحالي غير متغير
  • ℹ️ سيكون الحقل الجديد فارغًا للعناصر الموجودة

مثال:

"معلومات المنتج" المستخدمة من قبل:
- المنتجات المادية
- المنتجات الرقمية
- الخدمات

احذف سمة "الوزن" → تمت إزالتها من الثلاثة جميعًا! ⚠️

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

الطريقةماذا تفعلمتى تستخدم
getAttributes()الحصول على جميع كائنات مجموعات السمات.
getAttributesByMarker()الحصول على جميع السمات حسب المؤشر مع البيانات من مجموعة السمات.
getAttributeSetByMarker()الحصول على كائن واحد من مجموعة السمات حسب المؤشر.
getSingleAttributeByMarkerSet()الحصول على سمة واحدة مع البيانات من مجموعة السمات.

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

ما الفرق بين string و text؟​

  • string - نص قصير، سطر واحد (حد أقصى ~255 حرفًا). استخدمه للأسماء، العناوين، البريد الإلكتروني.
  • text - نص طويل، عدة فقرات، يدعم التنسيق وHTML. استخدمه للأوصاف، المقالات.

متى يجب أن أستخدم integer مقابل float؟​

  • integer - أعداد صحيحة فقط: 1، 2، 100، -5. استخدمه للكميات، العد، الأعمار.
  • float - أعداد عشرية: 19.99، 4.5، -0.25. استخدمه للأسعار، التقييمات، القياسات.
  • real - مثل float ولكن بدقة أعلى. استخدمه للحسابات العلمية.

أفضل ممارسة: خطط لأنواع السمات الخاصة بك قبل إضافة المحتوى.

ماذا يحدث إذا قمت بحذف سمة؟​

  • لا يمكنك حذف سمة إذا كانت مستخدمة في مجموعة سمات.

هل يمكنني إعادة استخدام نفس السمة في مجموعات سمات مختلفة؟​

لا، كل سمة تنتمي إلى مجموعة سمات واحدة. لكن يمكنك:

  • إنشاء سمات مشابهة مع مؤشرات مختلفة
  • إعادة استخدام مجموعات السمات بالكامل عبر كيانات متعددة

ما هو "المؤشر" ولماذا هو مهم؟​

المؤشر هو المعرف الفني الذي تستخدمه في الكود:

// في كودك:
product.attributeValues.product_name  // ← "product_name" هو المؤشر

// مقابل الاسم (المعروض في الإدارة):
"اسم المنتج"  // ← هذا فقط للبشر

قواعد المؤشرات:

  • يجب أن تكون فريدة
  • لا مسافات (استخدم _)
  • لا يمكن أن تبدأ بأرقام
  • استخدم الحروف الصغيرة
  • اختر أسماء وصفية

كيف أعرف أي نوع يجب أن أستخدمه لبياناتي؟​

اسأل نفسك:

  1. هل هو نص؟

    • قصير (< 255 حرفًا)؟ → string
    • طويل مع تنسيق؟ → text
    • يحتاج إلى عنوان؟ → textWithHeader

  2. هل هو رقم؟

    • لا أعداد عشرية؟ → integer
    • يحتوي على أعداد عشرية؟ → float
    • دقة علمية؟ → real

  3. هل هو اختيار؟

    • اختر خيارًا واحدًا؟ → radioButton
    • قائمة منسدلة؟ → list

  4. هل هو ملف؟

    • صورة؟ → image أو groupOfImages
    • مستند؟ → file

  5. هل هو تاريخ؟

    • مجرد تاريخ؟ → date
    • تاريخ + وقت؟ → dateTime
    • فترة زمنية؟ → timeInterval

هل يمكنني الحصول على سمات متداخلة (سمات داخل سمات)؟​

ليس مباشرة، لكن يمكنك استخدام:

  • نوع entity للربط بمحتوى آخر
  • نوع json لتخزين بيانات مهيكلة
  • مجموعات سمات متعددة لتنظيم الحقول ذات الصلة

كيف أضيف قواعد التحقق؟​

في لوحة إدارة OneEntry:

  1. انتقل إلى مجموعة السمات الخاصة بك
  2. انقر على سمة
  3. أضف المدققين (مطلوب، الحد الأدنى/الحد الأقصى، regex، إلخ)
  4. احفظ التغييرات

المدققون الشائعون:

  • حقل مطلوب
  • الحد الأدنى/الحد الأقصى للطول
  • تنسيق البريد الإلكتروني
  • تنسيق URL
  • حدود حجم الملف
  • أبعاد الصورة

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

  • استخدم مؤشرات وصفية (product_price وليس pp)
  • خطط لأنواع السمات قبل إضافة المحتوى
  • أعد استخدام مجموعات السمات عند الإمكان
  • أضف مدققين لضمان جودة البيانات
  • وثق ما هي كل سمة

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

تعريف موديل AttributesSets​


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

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