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

المقدمة

قم بإنشاء كتل محتوى قابلة لإعادة الاستخدام يمكن استخدامها عبر صفحات متعددة.

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

يتيح لك موديل Blocks استخدام مكونات محتوى قابلة لإعادة الاستخدام (كتل) تحتوي على مجموعات من السمات ويمكن استخدامها عبر صفحات متعددة وصفحات المنتجات - مثل الرؤوس، والتذييلات، واللافتات، والشهادات، أو أي محتوى متكرر.

فكر في الأمر ككتل LEGO لموقعك الإلكتروني - تقوم بإنشاء كتلة مرة واحدة، وتعيد استخدامها في كل مكان تحتاجه. قم بتغيير الكتلة مرة واحدة، وستتحدث في كل مكان تلقائيًا.

📖 شرح بسيط​

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

  • 🔝 رأس - شعار، قائمة تنقل (نفس الشيء في كل صفحة)
  • 🔽 تذييل - معلومات الاتصال، روابط التواصل الاجتماعي (نفس الشيء في كل صفحة)
  • 📢 لافتة ترويجية - عرض خاص (تظهر في صفحات متعددة)
  • ⭐ شهادات - مراجعات العملاء (تُستخدم في أماكن مختلفة)
  • 📞 نموذج الاتصال - يظهر في صفحات متعددة

بدلاً من نسخ هذا المحتوى إلى كل صفحة:

  • ✅ أنشئ مرة واحدة ككتلة
  • ✅ أدخل الكتلة حيثما تحتاجها
  • ✅ قم بالتحديث في مكان واحد → التغييرات تحدث في كل مكان تلقائيًا
  • ✅ حافظ على محتواك DRY (لا تكرر نفسك)

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

بدون كتل (نسخ ولصق):

  • تحديث التذييل → تحرير 50 صفحة يدويًا ❌
  • إضافة رابط اجتماعي → تحديث في كل مكان ❌
  • محتوى غير متسق عبر الصفحات ❌

مع الكتل (قابلة لإعادة الاستخدام):

  • تحديث كتلة التذييل → تغييرات على جميع الصفحات الـ 50 على الفور ✅
  • إضافة رابط اجتماعي → تحديث مرة واحدة ✅
  • دائمًا متسق ✅

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

ما هي الكتلة؟​

الكتلة هي مكون محتوى قابل لإعادة الاستخدام يحتوي على:

  • المحتوى - نصوص، صور، روابط، أي بيانات
  • السمات - حقول مخصصة تحددها
  • المؤشر - معرف فريد للإشارة إليها
  • الحالة - نشط، مسودة، مؤرشف

قابلية إعادة استخدام الكتل​

يمكن أن تكون الكتل:

  • ✅ مستخدمة في صفحات متعددة وإذا تم تحديث الكتل، يتم تحديثها في كل مكان
  • ✅ محلية (محتوى مختلف لكل لغة)

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

أفضل الممارسات: استخدم دائمًا المؤشرات في كودك (فهي لا تتغير أبدًا).

هيكل الكتلة​

كل كتلة تحتوي على هذه الحقول الرئيسية:

{
  id: 3, // معرف فريد
  localizeInfos: { // بيانات الكتلة المحلية
    title: 'Block', // عنوان الكتلة المحلي
  },
  version: 0, // إصدار الكتلة
  position: 1, // موقع الكتلة في مصفوفة الكتل
  identifier: 'block', // معرف الكتلة
  type: 'common_block', // نوع الكتلة
  templateIdentifier: null, // معرف القالب
  isVisible: true, // الرؤية
  attributeValues: {}, // سمات الكتلة
}

السمات المخصصة​

تستخدم الكتل AttributesSets للحقول المخصصة:

أمثلة:

  • كتلة التذييل: نص حقوق الطبع والنشر، روابط التواصل الاجتماعي، معلومات الاتصال
  • لافتة البطل: العنوان، العنوان الفرعي، زر CTA، صورة الخلفية
  • شهادة: اسم المؤلف، الصورة، الاقتباس، التقييم
  • نموذج الاتصال: تكوين الحقول، نص زر الإرسال

تعلم المزيد: انظر AttributesSets Module

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

الطريقةماذا تفعلمتى تستخدم
getBlocks()الحصول على جميع الكتل (مقيدة، مصفاة)قائمة بجميع الكتل المتاحة
getBlockByMarker()الحصول على كتلة بواسطة المؤشرجلب كتلة معينة في الكود
searchBlock()البحث عن الكتلجلب الكتل

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

ما الفرق بين الكتل والصفحات؟​

  • الصفحات/صفحات المنتجات - صفحات مكتفية ذاتيًا تمامًا مع عناوين URL (مثل /about) يمكنك إضافة كتل ومكونات صفحة أخرى يمكن إعادة استخدامها عبر صفحات متعددة.
  • الكتل - مكونات قابلة لإعادة الاستخدام تُدرج في الصفحات (مثل، التذييل)

فكر في الأمر كالتالي:

  • الصفحة = وثيقة كاملة
  • الكتلة = فقرة تعيد استخدامها في مستندات متعددة

كيف يمكنني تحديث محتوى كتلة؟​

قم بتحديثه في OneEntry لوحة الإدارة:

  1. انتقل إلى قسم الكتل
  2. ابحث عن كتلتك (مثل "التذييل")
  3. حرر السمات
  4. احفظ

جميع الصفحات التي تستخدم تلك الكتلة تتحدث تلقائيًا! ✨

هل يجب أن أنشئ العديد من الكتل الصغيرة أم عدد قليل من الكتل الكبيرة؟​

العديد من الكتل الصغيرة هو الأفضل:

✅ جيد (صغير، مركز):

- header_logo
- header_navigation
- footer_copyright
- footer_social_links

❌ تجنب (كبير جدًا):

- entire_page_layout (يحتوي على كل شيء)

لماذا؟ الكتل الصغيرة أسهل في إعادة الاستخدام والصيانة.

كيف يمكنني إظهار/إخفاء الكتل بشكل شرطي؟​

تحقق من حقل isVisible

هل يمكنني إنشاء كتل ديناميكيًا عبر API؟​

SDK هو للقراءة فقط. لإنشاء كتل، استخدم لوحة إدارة OneEntry.

كيف يمكنني التعامل مع الكتل المفقودة بشكل سلس؟​

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

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

أفضل ممارسات مؤشرات الكتل​

✅ أسماء مؤشرات جيدة:

  • وصفية: global_footer, homepage_hero
  • استخدم الشرطات السفلية: contact_form
  • أحرف صغيرة: promo_banner
  • تشير إلى النطاق: global_header مقابل blog_header

❌ أسماء مؤشرات سيئة:

  • عامة: block1, content
  • مسافات: my block
  • حالة مختلطة: MyBlock, ProMoBanner

تخزين الكتل مؤقتًا​

تتغير الكتل نادرًا → خزّنها مؤقتًا!

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

  • أنشئ كتل صغيرة ومركزة (مسؤولية واحدة)
  • استخدم مؤشرات وصفية (footer، وليس block1)
  • خزّن الكتل مؤقتًا لتقليل استدعاءات API
  • تعامل مع الكتل المفقودة بشكل سلس (try/catch)
  • وثق ما هي كل كتلة
  • حافظ على هيكل الكتلة متسقًا
  • اختبر تغييرات الكتلة قبل النشر
  • استخدم statusId لمعاينة التغييرات

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

تعريف موديل الكتل​


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

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