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

المقدمة

استرجع قوالب العرض التي تتحكم في كيفية عرض الصفحات، الكتل، المنتجات، والصور عبر تطبيقك.

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

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

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

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

🚀 البداية السريعة​

قم بتهيئة الموديل من defineOneEntry:


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

استرجع القوالب واقرأ تكوينها:

// Fetch all templates of a given BlockType.
const productTemplates = await Templates.getTemplateByType("product", "en_US");

productTemplates.forEach((tpl) => {
  console.log(tpl.identifier, tpl.title, tpl.generalTypeName);
});

// Or fetch a single template by its marker.
const card = await Templates.getTemplateByMarker("product_thumbnail", "en_US");
console.log(card.attributeValues);

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

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

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

  • النوع العام (generalTypeName) - فئة الكيان التي ينطبق عليها القالب، مثل BlockType مثل product، common_page، common_block، form، أو order
  • العنوان (title) - اسم القالب المعروض في لوحة الإدارة (غير فريد)
  • المؤشر (identifier) - معرف فريد للإشارة إلى الكود (استخدم هذا، وليس المعرف)
  • قيم السمات (attributeValues) - خريطة لقيم السمات مفاتيحها هي المؤشر
  • مجموعة السمات (attributeSetIdentifier) - مجموعة السمات المرتبطة (اختياري)

هيكل القالب (ITemplateEntity):

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
  generalTypeName: BlockType;              // General type name
  attributeSetIdentifier: string | null;   // Associated attribute set
  attributeValues: IAttributeValues;       // Map of attribute values keyed by marker
  position: number;                        // Sort position
}

أنواع القوالب (BlockType)​

نوع القالب هو generalTypeName، قيمة BlockType. تقبل getTemplateByType(type) نفس BlockType. القيم الشائعة:

النوعفئة الكيانحالات الاستخدام المثال
productالمنتجاتتفاصيل المنتج، عرض المنتج
catalog_pageصفحات الكتالوجقائمة الفئات، نتائج البحث
common_pageالصفحات العاديةمنشور مدونة، صفحة هبوط، صفحة حول
error_pageصفحات الأخطاءصفحة 404، صفحة 500، تخطيطات أخطاء مخصصة
common_blockكتل المحتوىبطاقات المحتوى، لافتات، أقسام، أدوات
formالنماذجنموذج الاتصال، نموذج التسجيل، استبيان
orderالطلباتتأكيد الطلب، تاريخ الطلب
serviceكيانات الخدمةمحتوى متعلق بالخدمة

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

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

لا يمكنك إنشاء قوالب عبر SDK - يتم إنشاؤها في لوحة إدارة OneEntry (الإعدادات > القوالب). يحتاج كل قالب إلى اسم (غير فريد)، مؤشر فريد، ونوع (فئة الكيان التي ينطبق عليها). SDK مخصص لـ استرجاع تكوينات القوالب، وليس لإنشائها.

استخدم المؤشرات، وليس المعرفات​

قم دائمًا بالإشارة إلى القوالب بواسطة المؤشر (identifier) في كودك - المؤشرات مستقرة عبر البيئات، بينما المعرفات ليست كذلك. استخدم getTemplateByMarker(marker) لقالب واحد، وgetTemplateByType(type) لجميع القوالب من نوع BlockType واحد، وgetAllTemplates() لاسترجاع كل قالب مجمع حسب النوع.

القوالب المفقودة​

ترجع الطرق كائن خطأ (IError) عندما لا يتم العثور على قالب. تحقق دائمًا من وجود المؤشرات وتعامل مع القوالب المفقودة بشكل لطيف.

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

تتغير القوالب نادرًا - قم بتخزينها مؤقتًا (localStorage/sessionStorage على الواجهة الأمامية، Redis/ذاكرة على الواجهة الخلفية؛ ~1 ساعة TTL هو نقطة انطلاق معقولة).

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

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

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

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

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

كيف يمكنني استرجاع قالب محدد؟​

استخدم getTemplateByMarker(marker) لقالب واحد بواسطة مؤشّره، أو getTemplateByType(type) لاسترجاع جميع القوالب من نوع BlockType معين (مثل product، common_page). استخدم getAllTemplates() لاسترجاع كل قالب مجمع حسب النوع.

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

ترجع الطرق كائن خطأ (IError). تحقق دائمًا من وجود مؤشرات القوالب وتعامل مع القوالب المفقودة بشكل لطيف.

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

اختر بناءً على نوع الكيان: common_page للصفحات العادية، catalog_page لقوائم المنتجات، common_block لكتل المحتوى، product لتفاصيل المنتجات. قم بمطابقة نوع القالب مع فئة المحتوى الخاصة بك.

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

  • استخدم المؤشرات، وليس المعرفات - المؤشرات مستقرة عبر البيئات.
  • أنشئ مؤشرات دلالية - product_card، وليس tpl_1.
  • قم بتخزين القوالب مؤقتًا - قلل من استدعاءات API للبيانات التي نادرًا ما تتغير.
  • تعامل مع القوالب المفقودة - تحقق من شكل إرجاع IError.

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