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

مقدمة

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

تتيح لك وحدة 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. تحديث المظهر دون تعديل كود المصدر

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

تحسين الصور​

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

  • تغيير الحجم تلقائيًا
  • تحويل التنسيق (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 CDN تلقائيًا بتقديم الصورة المحسنة بناءً على تكوين القالب (الحجم، القص، التنسيق).

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

نعم! قم بإنشاء قوالب منفصلة بأحجام مناسبة لكل جهاز (مثل 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"
  }
);

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