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

مقدمة

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

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

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

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

📖 شرح بسيط​

تحتاج كل تطبيق إلى تقديم محتوى متسق:

  • 🖼️ قوالب الصور - أحجام وقصات محددة مسبقًا (صورة مصغرة، صورة رئيسية، معرض)
  • 📄 قوالب الصفحات - تكوينات تخطيط الصفحة (مقال مدونة، صفحة هبوط)
  • 🧱 قوالب الكتل - مظهر كتل المحتوى (بطاقة، لافتة، قسم)
  • 🛍️ قوالب المنتجات - تنسيقات عرض المنتجات (شبكة، قائمة، تفاصيل)
  • 🎨 تصميم متجاوب - أحجام مختلفة للجوال، التابلت، الكمبيوتر المكتبي
  • ♻️ تكوينات قابلة لإعادة الاستخدام - تعريف مرة واحدة، استخدام في كل مكان

المشكلة مع منطق العرض الثابت:

المشاكل:

  • 🔒 غير متسق - أحجام مختلفة في أماكن مختلفة
  • 🎨 صعب الصيانة - يتطلب التغيير تعديل ملفات متعددة
  • 📱 غير متجاوب - الأحجام الثابتة لا تتكيف
  • ♻️ لا إعادة استخدام - كود مكرر في كل مكان

حل القوالب:

الفوائد:

  • 🔒 متسق - نفس القالب مستخدم في كل مكان
  • 🎨 صيانة سهلة - تغيير في لوحة الإدارة، ينطبق في كل مكان
  • 📱 متجاوب - قوالب مختلفة لشاشات مختلفة
  • ♻️ قابل لإعادة الاستخدام - تعريف مرة واحدة، استخدام في جميع أنحاء التطبيق

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

ما هو القالب؟​

القالب هو تكوين عرض يحدد كيف يجب أن يظهر المحتوى:

  • نوع القالب - قالب صورة، صفحة، كتلة، منتج
  • الأبعاد - العرض، الارتفاع، نسبة العرض إلى الارتفاع
  • إعدادات القص - كيفية قص الصور (مركز، أعلى، أسفل)
  • التنسيق - تنسيق الصورة (JPEG، PNG، WebP)
  • الجودة - جودة الضغط
  • المؤشر - معرف فريد للإشارة إلى الكود

هيكل القالب​

كل قالب له هذا الهيكل:

{
  id: 1,                                    // معرف فريد
  title: "صورة مصغرة للمنتج",               // اسم القالب (غير فريد)
  identifier: "product_thumbnail",          // مؤشر القالب (فريد)
  generalTypeId: 1,                         // مرجع معرف النوع
  version: 0,                               // رقم الإصدار
  attributeSetIdentifier: null,             // مجموعة السمات المرتبطة
  localizeInfos: {                          // معلومات محلية
    en_US: {
      title: "صورة مصغرة للمنتج",
      description: "صورة صغيرة للمنتج"
    }
  },
  attributeValues: {},                      // بيانات السمات الإضافية
  isActive: true,                           // حالة النشاط
  createdAt: "2024-01-15T10:00:00Z",
  updatedAt: "2024-01-15T10:00:00Z"
}

الحقول الرئيسية:

  • identifier - مؤشر فريد للإشارة إلى القالب (استخدم هذا، وليس المعرف)
  • title - اسم القالب المعروض في لوحة الإدارة
  • generalTypeId - فئة الكيان التي ينطبق عليها القالب
  • attributeSetIdentifier - مجموعة السمات المرتبطة الاختيارية

أنواع القوالب​

تنظم القوالب حسب نوع الكيان وتدعم الفئات التالية:

نوع القالبفئة الكيانحالات الاستخدام المثال
كتل المنتجاتforCatalogProductsشبكة المنتجات، قائمة المنتجات، المنتجات المميزة
كتل عاديةforOneBlockبطاقات المحتوى، لافتات، أقسام، أدوات
صفحات الخطأforErrorPagesصفحة 404، صفحة 500، تخطيطات خطأ مخصصة
صفحات عاديةforOnePageمقال مدونة، صفحة هبوط، صفحة حول
صفحات المنتجاتforOneProductتفاصيل المنتج، مقارنة المنتجات
صفحات الكتالوجforCatalogPageقائمة الفئات، نتائج البحث
النماذجforFormنموذج الاتصال، نموذج التسجيل، استبيان
الطلباتforOrderتأكيد الطلب، تاريخ الطلب

قوالب الصور الشائعة​

القالبالحجمالقصحالة الاستخدام
صورة مصغرة150×150مركزصور المعاينة الصغيرة
صورة البطاقة300×200مركزبطاقات المنتجات، بطاقات المدونة
صورة رئيسية1920×1080مركزلافتات بعرض كامل
صورة المعرض800×600مركزمعارض الصور
الصورة الرمزية100×100مركزصور ملفات تعريف المستخدمين
صورة رئيسية للجوال768×432مركزلافتات محسنة للجوال

سير عمل تكوين القالب​

1. إنشاء قوالب في لوحة الإدارة
   (تحديد الأحجام، القصات، التنسيقات)
   ↓
2. جلب القوالب عبر SDK
   (Templates.getTemplates())
   ↓
3. تطبيق تكوينات القالب
   (استخدام الأحجام في عرض الصور)
   ↓
4. الصور محسنة تلقائيًا
   (شبكة توزيع المحتوى OneEntry تقدم الحجم الصحيح)
   ↓
5. عرض متسق في كل مكان
   (نفس القالب = نفس المظهر)

لماذا تستخدم وحدة القوالب؟​

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

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

تُنشأ القوالب في لوحة الإدارة​

لا يمكنك إنشاء قوالب عبر SDK - يتم إنشاؤها في لوحة إدارة OneEntry:

لوحة إدارة OneEntry → الإعدادات → القوالب → إنشاء قالب → تعيين الاسم/المؤشر/النوع → حفظ

عملية الإنشاء:

  • قدم اسمًا (معرف غير فريد)
  • قدم مؤشرًا (معرف فريد)
  • اختر نوعًا (فئة الكيان التي ينطبق عليها القالب)
  • انقر على "إنشاء" لإنهاء

عمليات الإدارة:

  • التكوين - انقر على أيقونة الترس لتعديل الاسم أو المؤشر أو النوع
  • الحذف - اختر القالب وانقر على أيقونة الحذف، ثم أكد الإزالة

SDK مخصص لـ جلب تكوينات القالب، وليس لإنشائها.

تحديد القالب​

ثلاث طرق لتحديد القوالب:

الطريقةمتى تستخدمهاالمثال
حسب النوعالإشارة في الكود (أفضل ممارسة)product_thumbnail, hero_banner
حسب المؤشرالإشارة في الكود (أفضل ممارسة)product_thumbnail, hero_banner
قائمة الكلعرض القوالب المتاحةgetTemplates()

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

تكامل CDN لقوالب الصور​

تحسن OneEntry تلقائيًا الصور بناءً على إعدادات القوالب.

تصميم متجاوب مع القوالب​

قم بإنشاء قوالب مختلفة لأحجام الشاشات المختلفة.

هيكل القالب:

interface ITemplateEntity {
  id: number;                        // معرف فريد
  title: string;                     // اسم القالب (غير فريد)
  identifier: string;                // مؤشر القالب (فريد)
  generalTypeId: number;             // مرجع معرف النوع
  version: number;                   // رقم الإصدار
  attributeSetIdentifier: string | null;  // مجموعة السمات المرتبطة
  localizeInfos: {                   // معلومات محلية
    [langCode: string]: {
      title: string;
      description?: string;
    };
  };
  attributeValues: any;              // بيانات السمات الإضافية
  isActive: boolean;                 // حالة النشاط
}

أنواع القوالب المتاحة:

  • forCatalogProducts - كتل المنتجات
  • forOneBlock - كتل عادية
  • forErrorPages - صفحات الخطأ
  • forOnePage - صفحات عادية
  • forOneProduct - صفحات المنتجات
  • forCatalogPage - صفحات الكتالوج
  • forForm - النماذج
  • forOrder - الطلبات

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

تُنشأ القوالب في لوحة الإدارة​

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

لإنشاء/تعديل القوالب: استخدم لوحة إدارة OneEntry.

كيف تعمل القوالب​

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

  1. وصف المكونات في كود مشروعك
  2. وضع علامات على المكونات باستخدام القوالب التي أنشأتها المنصة
  3. تبديل القوالب لتغيير كيفية عمل الكيانات
  4. تحديث المظهر دون تعديل كود المصدر

تسمح هذه الفجوة بتنوعات تصميمية ووظيفية متعددة دون تغييرات في الكود.

تحسين الصور​

تحسن شبكة توزيع المحتوى OneEntry تلقائيًا الصور بناءً على إعدادات القالب:

  • تغيير الحجم تلقائيًا
  • تحويل التنسيق (JPEG، PNG، WebP)
  • الضغط
  • القص
  • التخزين المؤقت

ما عليك سوى الإشارة إلى مؤشر القالب:

<img src={`${image.url}?template=thumbnail`} />

قوالب متجاوبة​

قم بإنشاء قوالب منفصلة لأجهزة مختلفة:

  • قوالب للجوال (768 بكسل عرض أو أقل)
  • قوالب للتابلت (1024 بكسل عرض)
  • قوالب للكمبيوتر المكتبي (1920 بكسل عرض)

استخدم مع عنصر <picture> للصور المتجاوبة.

تخزين القوالب​

تتغير القوالب نادرًا - نفذ التخزين المؤقت:

  • الواجهة الأمامية: localStorage، sessionStorage
  • الواجهة الخلفية: Redis، ذاكرة التخزين المؤقت
  • TTL: ساعة واحدة موصى بها

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

الطريقةالوصفحالة الاستخدام
getAllTemplates()الحصول على جميع القوالب مجمعة حسب الأنواععرض جميع القوالب المتاحة
getTemplateByType()الحصول على القوالب حسب نوع الكيانجلب القوالب لنوع كيان محدد
getTemplateByMarker()الحصول على القالب حسب المؤشرجلب تكوين قالب محدد

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

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

تقوم القوالب بتكوين عرض المحتوى العام (الصفحات، الكتل، المنتجات)، بينما تتعامل TemplatePreviews بشكل خاص مع صور سمات المنتجات (عينة الألوان، معاينات المواد). استخدم القوالب للمحتوى الرئيسي، وTemplatePreviews لصور السمات.

كيف يمكنني تطبيق قالب على عنوان URL للصورة؟​

أضف ?template=marker إلى عنوان URL للصورة، حيث marker هو معرف القالب. تقوم شبكة توزيع المحتوى OneEntry تلقائيًا بتقديم الصورة المحسنة بناءً على تكوين القالب (الحجم، القص، التنسيق).

هل يمكنني إنشاء قوالب مختلفة للجوال والكمبيوتر المكتبي؟​

نعم! قم بإنشاء قوالب منفصلة بأحجام مناسبة لكل جهاز (مثل hero_mobile، hero_desktop). استخدم تقنيات التصميم المتجاوب أو عناصر <picture> لتحميل القالب الصحيح بناءً على حجم الشاشة.

ماذا يحدث إذا قمت بالإشارة إلى قالب غير موجود؟​

ستظهر الصورة بحجمها الأصلي دون تحسين القالب. تحقق دائمًا من وجود مؤشرات القالب وتعامل مع القوالب المفقودة بشكل لطيف مع أحجام احتياطية.

كيف يمكنني تحديث قالب دون التأثير على الإنتاج؟​

تعد القوالب تكوينات، وليست كودًا. تنطبق التغييرات في لوحة الإدارة على الفور. اختبر تغييرات القالب في بيئة staging أولاً، ثم قم بتحديث قوالب الإنتاج عند التحقق.

أي أنواع القوالب يجب أن أستخدم لمحتواي؟​

اختر بناءً على نوع الكيان: forOnePage للصفحات القياسية، forCatalogProducts لقوائم المنتجات، forOneBlock لكتل المحتوى، forOneProduct لتفاصيل المنتجات. قم بمطابقة نوع القالب مع فئة المحتوى الخاصة بك.

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

  • استخدم المؤشرات، وليس المعرفات - المؤشرات مستقرة عبر البيئات
  • قم بتخزين القوالب مؤقتًا - تقليل استدعاءات API للبيانات التي نادرًا ما تتغير
  • قم بإنشاء قوالب متجاوبة - أحجام مختلفة لشاشات مختلفة
  • استخدم تنسيق WebP - ضغط أفضل من JPEG/PNG
  • حدد إعدادات الجودة - توازن بين الجودة وحجم الملف
  • استخدم معلمات القالب في CDN - ?template=marker للتحسين
  • أنشئ مؤشرات دلالية - product_thumbnail، وليس img_1
  • وثق استخدام القالب - اشرح ما هو الغرض من كل قالب

مزيد من المعلومات حول القوالب في لوحة إدارة OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/templates/content_templates/

تعريف وحدة القوالب​

تقوم وحدة Templates بتكوين عرض المحتوى داخل تطبيقك.

تؤثر بعض القوالب على الصور المخزنة في OneEntry، بينما تحدد أخرى مظهر الكيانات مثل الكتل، الصفحات، والمنتجات.


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

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