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

مقدمة

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

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

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

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

📖 شرح بسيط​

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

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

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

المشاكل:

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

حل القوالب:

الفوائد:

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

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

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

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

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

هيكل القالب​

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

{
  id: 1,                                    // Unique identifier
  title: "Product Thumbnail",               // Template name (non-unique)
  identifier: "product_thumbnail",          // Template marker (unique)
  generalTypeId: 1,                         // Type ID reference
  version: 0,                               // Version number
  attributeSetIdentifier: null,             // Associated attribute set
  localizeInfos: {                          // Localized information
    en_US: {
      title: "Product Thumbnail",
      description: "Small product image"
    }
  },
  attributeValues: {},                      // Additional attribute data
  isActive: true,                           // Active status
  createdAt: "2024-01-15T10:00:00Z",
  updatedAt: "2024-01-15T10:00:00Z"
}

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

  • identifier - علامة فريدة للإشارة إلى القالب (استخدم هذا، وليس ID)
  • 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. Create templates in admin panel
   (Define sizes, crops, formats)
   ↓
2. Fetch templates via SDK
   (Templates.getTemplates())
   ↓
3. Apply template configurations
   (Use sizes in image rendering)
   ↓
4. Images automatically optimized
   (OneEntry CDN serves correct size)
   ↓
5. Consistent display everywhere
   (Same template = same appearance)

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

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

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

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

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

OneEntry Admin Panel → Settings → Templates → Create Template → Set Name/Marker/Type → Save

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

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

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

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

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

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

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

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

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

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

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

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

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

هيكل القالب:

interface ITemplateEntity {
  id: number;                        // Unique identifier
  title: string;                     // Template name (non-unique)
  identifier: string;                // Template marker (unique)
  generalTypeId: number;             // Type ID reference
  version: number;                   // Version number
  attributeSetIdentifier: string | null;  // Associated attribute set
  localizeInfos: {                   // Localized information
    [langCode: string]: {
      title: string;
      description?: string;
    };
  };
  attributeValues: any;              // Additional attribute data
  isActive: boolean;                 // Active status
}

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

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

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

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

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

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

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

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

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

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

تحسين الصور​

يقوم CDN الخاص بـ 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 هو معرف القالب. يقوم CDN الخاص بـ 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"
  }
);

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