تخطٍ إلى المحتوى

توثيق المطوّرين · واجهة برمجة القوالب v1.0 · v1.1

أنشئ قالبًا متكاملًا لموقع شركة بأمان.

تحدّد قوالب Eyivo نظامًا بصريًا مكتملًا يشمل بنية الصفحات والخطوط والمكوّنات والتنسيق. ثم يملأ صاحب العمل المحتوى المعتمد من داخل التطبيق، دون نقل الأقسام أو تعديل الشفرة أو إفساد التصميم.

المبدأ الأساسي

تحدّد Liquid كيف يبدو الموقع؛ وتحدّد نواة Eyivo أي محتوى للشركة يظهر فيه.

1. النموذج الذهني

هناك ثلاث مسؤوليات منفصلة. وفهم هذا الفصل هو أساس فهم الإصدار الأول.

Eyivo Core

يخزّن بيانات الشركة والصفحات والوسائط وتحسين محركات البحث والتنقّل وحالة النشر. وهو المرجع المعتمد للمحتوى.

حزمة القالب

يحدّد أشكال الصفحات الثابتة والأقسام المسموح بها ومخططات المكوّنات المخصصة وCSS. ولا يستعلم عن البيانات أو يشغّل شفرة التطبيق.

محرر التطبيق

ينشئ نماذج إدخال آمنة من المخطط. ويمكن للمالكين تحديث النصوص والصور والصفحات وترتيب الأقسام داخل المنطقة.

ليس أداة لبناء الصفحات: يمكن للمالك إضافة قسم مسموح إلى main واختيار موضعه الرقمي. لا يمكنه إنشاء منطقة جديدة أو سحب قسم البطل إلى التذييل أو تغيير ملفات قالبك. يمكنه إضافة CSS خاص بموقعه يُحمَّل بعد أوراق الأنماط الخاصة بك، ومنح الأقسام أسماء فئات (راجع CSS المخصص للموقع).

2. البدء السريع: قالب بسيط وقابل للاستخدام

يملك كل قالب في الإصدار الأول تخطيطه وتنسيقاته ونصوصه البرمجية كاملة، ويمكن لمؤلفه ترتيبها وفق أي تصميم يختاره. ولا يرث القالب تخطيطًا أو أصلًا من قالب آخر. تأتي مكوّنات eyivo: المشتركة وأنواع الصفحات الاحتياطية السبعة من theme-core؛ ولا يخزّن القالب إلا أنواع الصفحات التي يستبدلها والمكوّنات التي يعرّفها ضمن مساحة الأسماء theme:.

يحتاج كل قالب في الإصدار الأول إلى ملف تخطيط افتراضي. ويكون كل من page-types/ وcomponents/ اختياريًا إذا استخدمت الحزمة بدائل النواة فقط:

acme-industrial/
├── theme.json
├── layouts/default.liquid
├── page-types/
│   └── home.liquid        # optional override
├── components/
│   └── featured_course.liquid
├── locales/
│   ├── en.json
│   └── tr.json
├── screenshots/
│   └── home-desktop.png   # demo-data screenshot
└── assets/
    ├── css/theme.css
    └── js/theme.js        # Theme API 1.1, reviewed

يأتي layouts/default.liquid دائمًا من القالب النشط، وهو المسؤول عن مستند الموقع العام كاملًا. يبحث Eyivo أولًا عن نوع الصفحة المطلوب في ذلك القالب، ثم يعود إلى theme-core/page-types. ولا توفّر النواة تخطيطًا أو أصولًا، لذلك يظل محتوى الصفحة الاحتياطية ضمن تخطيط القالب النشط وتنسيقه.

3. صِف القالب في theme.json

ملف التعريف إعلان عن القدرات وعقد تُنشأ منه نماذج التطبيق. وهو يجيب عن ثلاثة أسئلة: ما بُنى الصفحات المتاحة، وما المناطق الموجودة في كل بنية، وما الذي يُسمح للمكوّن بتخزينه. تعلن السمات المدمجة صراحة عن أنواع الصفحات القياسية العشرة وتتضمن ملفات Liquid المقابلة لها. ويمكن للسمات المخصصة الاستمرار في استخدام قوالب النواة الاحتياطية لأنواع الصفحات غير المعلنة.

{
  "name": "Acme Industrial",
  "version": "1.0.0",
  "eyivo_theme_api": "1.0",
  "settings": {
    "primary_color": { "type": "color" },
    "button_radius": { "type": "number" }
  },
  "page_types": {
    "home": {
      "areas": {
        "hero": {
          "allowed_components": ["eyivo:hero"],
          "min": 0,
          "max": 1
        },
        "main": {
          "allowed_components": ["eyivo:rich_text", "eyivo:image_text", "theme:featured_course"]
        }
      }
    },
    "page": { "areas": { "main": { "allowed_components": ["eyivo:rich_text"] } } }
  },
  "components": {
    "featured_course": {
      "variants": ["card", "compact"],
      "schema": {
        "heading": { "type": "text", "required": true, "translatable": true },
        "summary": { "type": "textarea", "translatable": true }
      }
    }
  }
}
المفتاحالمعنىمثال
keyتسمية اختيارية لمرجعك الخاص. تمنح Eyivo كل قالب مرفوع معرّفًا خاصًا به، لذا لا يحدد المفتاح أبدًا القالب الذي ينتمي إليه الرفع.acme-industrial
versionإصدار القالب الثابت الذي لا يتغيّر بعد نشره، وفق الترقيم الدلالي للإصدارات.1.2.0
eyivo_theme_apiعقد واجهة Eyivo العامة الذي تدعمه حزمتك.1.0
areasمواضع مسماة يعرضها ملف صفحة Liquid في أماكن ثابتة.hero, main, bottom
allowed_componentsالمكوّنات التي يستطيع المحرر إضافتها إلى منطقة معينة.["eyivo:hero"]
componentsتعريفات مكوّنات theme: المخصصة للقالب النشط. وتبقى تعريفات eyivo: المشتركة في theme-core.featured_course
min/maxحدود اختيارية لعدد الأقسام في تلك المنطقة.max: 1

العودة إلى نوع الصفحة الاحتياطي: الأنواع المضمّنة هي home وpage وgallery وcontact وproducts وproduct وvideos. احذف أيًا منها لاستخدام تعريفه وملف Liquid الخاص به من theme-core. ولا تعلن نوعًا إلا إذا وفّر القالب ملف الاستبدال المطابق له في page-types/<type>.liquid.

يتلقى المحرر واجهة أنواع الصفحات المدمجة: تحل تعريفات القالب النشط محل تعريفات النواة المطابقة، بينما تبقى جميع الأنواع المحذوفة متاحة من النواة.

4. محتوى تجريبي كامل في demo.json

يجب أن تتضمن كل حزمة مرفوعة ملف demo.json قابلًا للنقل لمحتوى مسودة فقط، ولقطة شاشة واحدة على الأقل مأخوذة بعد تحميله. تستخدم القوالب المدمجة المخطط نفسه. لا تُدرج معرّفات قاعدة البيانات أو نطاقات العملاء أو بيانات الدخول أو بيانات اعتماد التخزين.

{
  "schema_version": 2,
  "default_locale": "en",
  "label": "Northline Build Co.",
  "summary": "Thoughtful construction for the way life happens.",
  "media": {
    "media/hero.jpg": {
      "public_url": "https://cdn.eyivo.com/demo/hero.jpg",
      "mime_type": "image/jpeg",
      "original_name": "hero.jpg",
      "bytes": 184000,
      "width": 1600,
      "height": 900
    },
    "assets/images/team.jpg": {
      "mime_type": "image/jpeg",
      "original_name": "team.jpg"
    }
  },
  "company": { "display_name": "Northline Build Co.", "logo_asset": "media/hero.jpg" },
  "theme_settings": { "settings": { "header_cta_url": "/contact" } },
  "pages": [],
  "catalog": [],
  "galleries": [],
  "videos": []
}
المفتاحالغرض
mediaروابط المصادر العامة وبياناتها الوصفية، مفهرسة بمعرّفات أصول قابلة للنقل. أعد استخدام المعرّف في hero_asset وcover_asset وmedia_asset وasset لعناصر المعرض وlogo_asset وfavicon_asset.
companyملف الشركة وروابط التواصل الاجتماعي وألوان العلامة التجارية وأصل اختياري للشعار أو الأيقونة، مع ترجمات مفهرسة حسب اللغة.
theme_settingsإعدادات القالب الأولية، مع ترجمات اختيارية مفهرسة حسب اللغة.
pagesالنوع وترتيب العرض وحالة التنقّل وتحسين محركات البحث وإعدادات الصفحة والمكوّنات والمحتوى المفهرس حسب اللغة.
catalogعناصر الكتالوج بمحتوى مفهرس حسب اللغة وcover_asset اختياري.
galleriesبيانات المعرض الوصفية وعناصر الصور. يحتاج كل عنصر إلى asset وalt_text غير فارغ.
videossource_url خارجي أو media_asset، ونمط العرض، ومحتوى مفهرس حسب اللغة.

يحتاج كل إدخال في media إما إلى public_url عبر https على مضيف مسموح (مضيف وسائط العرض في Eyivo cdn.eyivo.com أو images.pexels.com)، أو إلى ملف مضمَّن في القالب داخل assets/ يُشار إليه بمساره ومن دون public_url. تُرفض المضيفات الأخرى وhttp وعناوين IP والمنافذ الأخرى وعمليات إعادة التوجيه مع تشخيص الرفع demo_media_url. القيم mime_type وwidth وheight مجرد تلميحات: تكتشف Eyivo النوع الحقيقي من محتوى الملف الذي نُزّل، ويجب أن يكون صورة أو فيديو مسموحًا بحجم 20 ميغابايت كحد أقصى.

تستخدم نماذج العرض التوضيحي ربط نماذج قابلًا للنقل، تحلّه Eyivo بشكل منفصل لكل موقع يستورد العرض التوضيحي. تصبح صور العرض التوضيحي المستوردة مراجع وسائط عادية في ذلك الموقع؛ وحذفها هناك لا يحذف الأصل المشترك أبدًا.

الصفحات والمكوّنات

{
  "type": "home",
  "sort_order": 0,
  "navigation_visible": true,
  "hero_asset": "media/hero.jpg",
  "translations": {
    "en": { "slug": "home", "title": "Home", "meta_title": "Home | Northline" },
    "tr": { "slug": "ana-sayfa", "title": "Ana sayfa", "meta_title": "Ana sayfa | Northline" }
  },
  "components": [{
    "component_type": "eyivo:hero",
    "area": "hero",
    "position": 100,
    "variant": "split",
    "data": { "primary_url": "/contact" },
    "translations": {
      "en": { "heading": "Built for real life", "primary_label": "Contact us" },
      "tr": { "heading": "Gerçek yaşam için tasarlandı", "primary_label": "Bize ulaşın" }
    }
  }]
}

يجب إعلان أنواع المكوّنات والمناطق في ملف تعريف القالب النشط أو theme-core. استخدم مسارات نسبية مثل /contact للروابط داخل الموقع نفسه. تستخدم عروض الصفحة الرئيسية المضمّنة صورة المقدّمة الحالية كخلفية بعرض كامل مع طبقة تضمن وضوح النص وتنسيق متجاوب: immersive في معظم القوالب وcentered مع صورة في Compact. تحتفظ أنماط المقدّمة الأخرى بتخطيطاتها.

لغات العرض التجريبي واللغة البديلة

الإنجليزية هي اللغة الأساسية المطلوبة: اضبط default_locale على en. غياب الحقل في الملفات القديمة يعني الإنجليزية أيضًا. اللغات الأخرى المدعومة اختيارية؛ لا تعرض نسخ النص الإنجليزي بوصفها ترجمات.

وفّر translations.en وكائنات اختيارية للغات الأخرى لبيانات الشركة وإعدادات القالب والصفحات والمكونات والمنتجات والمعارض وتعليقات الصور ونصوصها البديلة والفيديوهات والمقالات. تبقى الحقول الإنجليزية القديمة دون مفتاح لغة مدعومة. عند الإنشاء تُختار لغة الموقع الأساسية ويُستخدم الحقل الإنجليزي لكل حقل مفقود. تستبدل المصفوفة المترجمة المصفوفة الإنجليزية بالكامل، وتُحفظ القيم الفارغة الصريحة. تُستورد اللغة المختارة فقط دون تفعيل لغات أخرى تلقائيًا.

استخدم معرّفات المسارات الإنجليزية المصدرية في الروابط الداخلية وعناصر القوائم القابلة للنقل. يحولها الاستيراد إلى المسار المترجم، بما في ذلك روابط النص المنسق والمقالات. يمكن للقوائم توفير خرائط slugs وlabels صريحة. تستخدم التسميات المفقودة الإنجليزية. لا تتغير الروابط الخارجية.

{
  "company": {
    "translations": {
      "en": { "display_name": "Northline", "description": "Built around your needs." },
      "tr": { "display_name": "Northline", "description": "İhtiyaçlarınıza göre tasarlandı." }
    }
  },
  "theme_settings": {
    "settings": { "header_cta_url": "/contact" },
    "translations": {
      "en": { "header_cta_label": "Contact us" },
      "tr": { "header_cta_label": "Bize ulaşın" }
    }
  },
  "menus": {
    "footer": [{ "type": "page", "slug": "contact",
      "slugs": { "en": "contact", "tr": "iletisim" },
      "labels": { "en": "Contact us", "tr": "Bize ulaşın" }
    }]
  }
}

سلامة الاستيراد والوسائط

تتضمن المواقع الجديدة من لوحة التحكم بيانات تجريبية افتراضيًا وتنشر اللغة المختارة فورًا؛ ويمكن للمالك إلغاء الخيار. تحميل العرض من إعدادات الهوية لموقع موجود يظل ينشئ مسودات ويحفظ المحتوى المنشور. ينسخ التطبيق المركزي الصور إلى مكتبة الموقع الجديد ويرسل مراجعها عبر الواجهة الداخلية. لا تتلقى خوادم master والقوالب بيانات اعتماد تخزين الكائنات. تستخدم القوالب قيمة media.public_url المقدمة.

أعلن لقطات الشاشة في theme.json.preview باستخدام data_source: "demo_data". ويجب أن تحتوي الحزمة على كل صورة preview مُعلنة.

5. اكتب التخطيط الذي يحتاجه قالبك

يمتلك التخطيط الافتراضي مستند HTML بالكامل. لا شيء خارج القالب النشط يوفّر رأسه أو تذييله أو ملف أنماطه أو بنيته المرئية. تضيف المنصة فقط سكربتاتها الخاصة بالنماذج والتحقق البشري والموافقة وشارة Eyivo؛ وتتطلب سكربتات القوالب Theme API 1.1.

<!doctype html>
<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  {% eyivo_head %}
  <link rel="stylesheet" href="{{ 'css/theme.css' | asset_url }}">
</head>
<body>
  <header class="site-header">
    <a href="{{ locale.home_url }}">{{ company.name }}</a>
    <nav>
      {% for item in navigation.main %}
        <a href="{{ item.url }}">{{ item.label }}</a>
      {% endfor %}
    </nav>
  </header>

  {{ content | raw }}
</body>
</html>

يحدد ملف نوع الصفحة المواضع الدقيقة لمناطقها الديناميكية. مكوّنات المنطقة هي سلاسل HTML معروضة مسبقًا، لذا أدرجها باستخدام | raw. وتُهرَّب القيم العادية افتراضيًا.

<main class="home-layout">
  <section class="home-layout__hero">{{ areas.hero | raw }}</section>
  <div class="home-layout__content">{{ areas.main | raw }}</div>
  <aside class="home-layout__footer-cta">{{ areas.bottom | raw }}</aside>
</main>

عرض مكوّن مباشرة

يمكن للمصمم وضع مكوّن مسجّل مباشرة في التخطيط أو ملف نوع الصفحة. يثبّت القالب هذا الموضع، فلا يمكن إعادة ترتيبه أو إزالته من اللوحة. مرّر كائنًا عبر data: أو حقول المخطط منفردة أو كليهما؛ وتتقدم الحقول المسماة على المفاتيح المطابقة في data:.

{% eyivo_component "eyivo:cta",
  eyebrow: "Let’s talk",
  heading: page.title,
  text: company.description,
  button_label: "Contact us",
  button_url: routes.contact
%}

{% eyivo_component "theme:featured_course",
  data: page.settings.featured_course,
  variant: "compact"
%}

يجب أن يكون النوع نصًا صريحًا داخل علامات اقتباس مع مساحة اسم. يستخدم العرض المباشر المخطط والمتغيرات وملف المكوّن وكائن component الموحّد نفسها المستخدمة لمكوّن داخل منطقة. ولا يمكن لملفات المكوّنات عرض مكوّنات أخرى.

الأصول: استخدم دائمًا {{ 'css/theme.css' | asset_url }}. يقدمه Eyivo من الحزمة النشطة في /theme-assets/<theme>/css/theme.css؛ ولا تثبّت اسم قالب آخر أو مسارًا في نظام الملفات.

رأس المستند والمسارات وقواميس الواجهة

يجب أن يعرض كل تخطيط {% eyivo_head %} مرة واحدة بالضبط. يتولى Eyivo حينها إخراج العنوان والوصف وrobots وcanonical وhreflang وOpen Graph والبيانات المنظمة. استخدم routes.home وroutes.contact وroutes.catalog وroutes.gallery وroutes.videos بدل تثبيت المسارات العامة في الشفرة. مرّر إعدادات الروابط القابلة للتعديل عبر | localized_url لتكتسب المسارات الداخلية المعروفة بادئة اللغة النشطة مع إبقاء الروابط الخارجية كما هي.

{{ 'Menu' | t }}
{{ theme.settings.header_cta_url | localized_url }}

أنشئ ملفات locales/<locale>.json اختيارية لتسميات الواجهة التي يضيفها القالب. ترتيب البحث هو: إنجليزية النواة، ثم لغة النواة، ثم إنجليزية القالب، ثم لغة القالب. لذلك تعمل التسميات المشتركة من theme-core دون نسخ ملفات. ضع النصوص التجارية في المحتوى القابل للترجمة أو حقول المكوّنات أو إعدادات القالب، لا في القواميس.

ملف مكوّن مخصص

<article class="featured-course featured-course--{{ component.variant }}">
  <div class="featured-course__content">
    <h1>{{ component.data.heading }}</h1>
    {% if component.data.summary %}<p>{{ component.data.summary }}</p>{% endif %}
  </div>
</article>

يختار Eyivo لغة الزائر للحقول القابلة للترجمة قبل العرض. لذلك يرى الزائر التركي والزائر الإنجليزي بنية المكوّن نفسها، لكن بقيم مختلفة في component.data.heading.

7. بيانات Liquid الآمنة المتاحة لك

يتلقى Liquid بيانات بسيطة وموحّدة، لا نماذج Laravel أو قاعدة البيانات. إذا لم تظهر قيمة في هذا الجدول، فاعتبرها غير متاحة في v1.

الكائنالحقول المفيدةالاستخدام المعتاد
sitename, localeاسم على مستوى الموقع ولغته الأصلية.
companyname, legal_name, description, address, phone, emailمعلومات الترويسة والتذييل والتواصل.
pageid, type, title, slug, body, settingsمحتوى الصفحة العام وإعداداتها الخاصة.
seotitle وdescription وقيم canonical وrobots وOpen Graph عند توفيرهارأس المستند.
navigation.mainيتضمن كل عنصر label وurl وactiveقائمة الموقع.
localecode, name, native_name, direction, is_default, home_url, availableلغة المستند واتجاه RTL وروابط الصفحة الرئيسية المحلية ومحددات اللغة.
routeshome, contact, catalog, gallery, videos, blogروابط النظام الصحيحة للغة؛ لا تنشئ البادئات في Liquid.
blogtitle, url, categories, category, posts, post, paginationصفحات قائمة المدونة المجانية وأرشيف الفئات والمقالات. تعرض المنشورات العنوان والملخص والرابط والتواريخ والفئات وصورة الغلاف. يحتوي blog.post.body_html وحده على HTML آمن أنشأه الخادم لمتن المقالة، وينبغي عرضه باستخدام raw. توفر صفحات التصفح previous_url وnext_url.
theme.settingsإعدادات ملف التعريف الخاص بقالبكاستخدام لون أو تباعد أو خيار تصميم مضبوط.
products/productعنوان ورابط وملخص ومتن مترجمةنوعا صفحات قائمة المنتجات وتفاصيل المنتج.
galleriesعنوان ووصف مترجماننوع صفحة المعرض.
videostitle, description, source_type, source_url, playback_url, mediaاستخدم playback_url لملفات الفيديو المرفوعة وsource_url لفيديوهات HTTP(S) الخارجية وفقًا لقيمة source_type. الصور المرفقة ليست مصادر فيديو أبدًا. لا تستخدم ملف الفيديو نفسه كصورة ملصق.
componentid, type, variant, dataداخل ملف مكوّن فقط.

مثال لتخطيط يحترم لغة الزائر

<html lang="{{ locale.code }}" dir="{{ locale.direction }}">
<a href="{{ locale.home_url }}">{{ company.name }}</a>
{% if locale.available.size > 1 %}
  <nav aria-label="Language">
    {% for language in locale.available %}
      <a href="{{ language.url }}" lang="{{ language.code }}"
         {% if language.current %}aria-current="page"{% endif %}>
        {{ language.native_name }}
      </a>
    {% endfor %}
  </nav>
{% endif %}

يعرض كل عنصر لغة متاحة أيضًا label وdirection وis_default وcurrent وhas_translation. يزوّد Eyivo الترجمات المنشورة المكافئة فقط، لذا يجب على القوالب استخدام language.url بدل إنشاء /en أو أي بادئة أخرى.

مثال على قيمة تنسيق تستند إلى إعداد: style="--brand: {{ theme.settings.primary_color }}". يجب أولًا تعريف الإعداد في theme.json.

8. المكوّنات المباشرة والديناميكية

للمكوّنات عقد عرض واحد وطريقتان لوضعها. يتحكم المصمم في المكوّن المباشر داخل التخطيط أو نوع الصفحة. ويُخزَّن المكوّن الديناميكي كنسخة داخل منطقة صفحة ويتحكم به المستخدم عبر المحرر. لكل نسخة ديناميكية معرّف ثابت ونوع ذو مساحة اسم ومنطقة وموضع ومتغير اختياري وبيانات وترجمات. الموضع يحدد الترتيب فقط، لا الهوية.

أنواع الحقول

text وtextarea وrichtext وnumber وboolean وselect وurl وemail وimage وvideo وfile وcolor وicon وpage وproduct وrepeater.

مساحات الأسماء

يُجلب eyivo: من theme-core/components، ويُجلب theme: من القالب النشط، ويُحجز plugin: لإضافات مستقبلية. استخدم النوع الكامل بمساحة اسمه داخل منطقة أو وسم eyivo_component.

مكوّن عام: ضع "universal": true في تعريف المكوّن للسماح به في جميع مناطق أنواع الصفحات المتوافقة. ويجب أن يبقى له مخطط صالح وملف Liquid.

تتكيف روابط الإجراءات المشتركة مع لغة المسارات الداخلية المعروفة مع الحفاظ على معلمات الاستعلام وأجزاء الروابط. يحتفظ النص المنسق بالتنسيق الآمن داخل حاويات المحرر المتداخلة. تُحذف صور المعرض الفارغة، ولا تكون صور الخرائط التي ليس لها وجهة روابط، وتستخدم تسميات الشرائح والبحث لغة واجهة الزائر.

9. CSS المخصص للموقع وفئات الأقسام

يمكن للمالكين إضافة CSS خاص بهم إلى الموقع ومنح الأقسام أسماء فئات (التصميم ← CSS مخصص). اكتب القوالب بحيث يعمل ذلك جيدًا:

  • ترتيب التحميل: يُضاف CSS الخاص بالموقع على شكل <style id="eyivo-custom-css"> قبل </head> مباشرةً، بعد كل أوراق أنماط القالب. أبقِ </head> في تخطيطاتك، ولا تعتمد على أن يكون CSS الخاص بك الأخير.
  • فئات الأقسام: يضيف المُصيِّر أسماء فئات القسم إلى العنصر الأول في مخرجات المكوّن، لذا امنح كل قالب مكوّن عنصرًا جذريًا واحدًا. تتوفر الأسماء أيضًا عبر {{ component.css_class }} إذا أردت وضعها في مكان آخر.
  • محددات ثابتة: حافظ على الفئتين body.theme-{key} وlayout-{name} وعلى فئة جذرية ثابتة لكل مكوّن، حتى يستمر CSS المالكين في العمل عبر إصداراتك. اذكر أي إعادة تسمية في ملاحظات الإصدار.
  • القوالب المرفوعة: تحصل أيضًا على CSS مخصص للموقع. تتشارك كل إصدارات القالب المرفوع ورقة أنماط واحدة لكل موقع، وتُحذف عند إيقاف آخر إصدار للقالب على الموقع أو حذفه.
  • أسماء محجوزة: البادئة eyivo- للفئات والمعرّف eyivo-custom-css خاصان بالمنصة.

10. سكربتات القوالب (Theme API 1.1)

يمكن أن يتضمن القالب شيفرة JavaScript خاصة به للقوائم وشرائح العرض وعلامات التبويب والمرشحات والميزات المشابهة. السكربتات اختيارية: يجب أن يعمل كل قالب من دونها، وتستمر حزم Theme API 1.0 في العمل كما هي من دون سكربتات.

  • أعلن عنها: اضبط "eyivo_theme_api": "1.1" و"capabilities": {"custom_javascript": true} في theme.json، وضع كل ملف مباشرةً في assets/js/. تُرفض الحزمة التي تحتوي على ملفات .js من دون هذا الإعلان.
  • حمّلها: استخدم فقط <script src="{{ 'js/theme.js' | asset_url }}" defer></script> (أو type="module") لملف داخل الحزمة. تعمل الوسوم بالترتيب الذي تظهر به.
  • عدة ملفات: يُراجع كل ملف ويُعتمد بمفرده، لذا لا يُسمح بـ import وexport. شارك الشيفرة عبر متغير عام واحد مثل window.AcmeTheme، وحمّل الملف الذي يعرّفه أولًا.
  • الحدود: 20 ملفًا كحد أقصى، و100 كيلوبايت لكل ملف، و300 كيلوبايت إجمالًا، ونص UTF-8 فقط.
  • مرفوض في القوالب: السكربتات المضمّنة، ومصادر السكربتات الخارجية، وسمات معالجات الأحداث on…=، وعناوين javascript:، وعناصر <iframe> و<object> و<embed> و<base>.
  • شيفرة مقروءة فقط: ارفع الشيفرة المصدرية، لا شيفرة مصغّرة أو مضغوطة أو مرمّزة. يمكن لأدوات التجميع إخراج شيفرة غير مصغّرة.
  • الحالات: يكون الإصدار الجديد بانتظار المراجعة حتى تنتهي الفحوص، ثم يصبح معتمدًا أو مرفوضًا. لا يمكن معاينة أو استخدام إلا الإصدار المعتمد. يمكن لاحقًا حظر إصدار معتمد: تحتفظ المواقع بالقالب من دون سكربتاته.
  • ثلاثة فحوص تلقائية بالترتيب: شيفرة مقروءة؛ وقواعد الشيفرة (لا eval ولا new Function ولا document.write ولا إعادة توجيه للصفحة ولا window.open ولا ملفات تعريف الارتباط أو تخزين المتصفح ولا WebAssembly ولا مؤقتات نصية ولا إنشاء عناصر script أو frame ولا إرسال قيم النماذج عبر الشبكة)؛ ومراجعة أمنية بالذكاء الاصطناعي. لهذه المراجعة تُرسل السكربتات وأسطر القوالب التي تحمّلها إلى خدمة ذكاء اصطناعي. أي ملاحظة ترفض الإصدار مع ذكر الملف والسطر.

مقبول: زر لفتح القائمة

(function () {
  document.querySelectorAll('[data-menu-toggle]').forEach(function (button) {
    button.addEventListener('click', function () {
      document.body.classList.toggle('menu-open');
    });
  });
})();

مرفوض: يرسل قيم النموذج إلى الخارج

form.addEventListener('submit', function () {
  fetch('/collect', { method: 'POST', body: form.elements.email.value });
});
  • للمالك فقط: تعمل السكربتات المعتمدة فقط على المواقع التي يملكها الحساب الذي رفع القالب، وفقط ما دامت المنصة ومالك الموقع يسمحان بها.
  • سياسة الأمان: تسمح الصفحات التي تشغّل سكربتات القوالب بالملفات المراجَعة فقط، مثبّتة ببصمات SHA-256 الخاصة بها، مع connect-src 'self'، ومن دون إطارات أو workers، ومن دون eval. يتطلب تغيير أي ملف إصدارًا جديدًا. لا يزال بالإمكان تحميل الصور وملفات الأنماط عبر https:، لذا ترفض المراجعة أيضًا إرسال البيانات عبر عناوين الصور أو ملفات الأنماط.
  • بعد الاعتماد: تُبلغ المتصفحات عن محاولات خرق السياسة. تؤدي البلاغات من ثلاثة زوار خلال 24 ساعة إلى حظر الإصدار؛ وتؤدي بلاغات إساءة الاستخدام من ثلاثة زوار خلال 7 أيام إلى تعطيل السكربتات على ذلك الموقع وإعادة فحص الإصدار. يتلقى المالكون بريدًا إلكترونيًا عند اعتماد إصدار أو رفضه أو حظره.
  • ميزات المنصة: لا يجوز للسكربتات استبدال النماذج وحقولها المخفية أو التحقق البشري أو شريط الموافقة أو شارة Eyivo أو شريط المالك، أو تغليفها أو إخفاؤها.

11. دليل المكوّنات المتاحة

تشكّل مكوّنات eyivo: المشتركة وعددها 30 مكتبة الإصدار الأول الكاملة، وتُحمّل من theme-core. ويمكن للقالب أيضًا تعريف مكوّنات theme: الخاصة به وتنفيذها.

الأنواع: spliteditorialcenteredimmersive

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text نعم نعم —
summary textarea لا نعم —
image_url url لا لا —
image_alt text لا نعم —
primary_label text لا نعم —
primary_url url لا لا —
secondary_label text لا نعم —
secondary_url url لا لا —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
body richtext لا نعم —

الأنواع: image_leftimage_rightoverlap

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
body richtext لا نعم —
image_url url لا لا —
image_alt text لا نعم —
badge text لا نعم —
button_label text لا نعم —
button_url url لا لا —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
intro textarea لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
intro textarea لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
intro textarea لا نعم —
button_label text لا نعم —
button_url url لا لا —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
text textarea لا نعم —
submit_label text لا نعم —
form_binding select لا لا —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
heading text لا نعم —
text textarea لا نعم —
whatsapp_url url لا لا —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
address textarea لا نعم —
map_url url لا لا —
image_url url لا لا —
image_alt text لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
heading text لا نعم —
placeholder text لا نعم —
categories repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
summary textarea لا نعم —
video_url url لا لا —
poster_url url لا لا —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
price text لا نعم —
period text لا نعم —
features repeater لا نعم —
button_label text لا نعم —
button_url url لا لا —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
label text لا نعم —
heading text لا نعم —
body textarea لا نعم —
button_label text لا نعم —
button_url url لا لا —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

يحتفظ مكوّن eyivo:faq المشترك بالحقول والترميز نفسيهما في كل قالب. يعرضه كل قالب بطباعته ومسافاته وألوانه الخاصة.

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
text textarea لا نعم —
button_label text لا نعم —
button_url url لا لا —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
heading text لا نعم —
items repeater لا نعم —

المتغيرات: لا يوجد

الحقلالنوعمطلوبقابل للترجمةالخيارات
eyebrow text لا نعم —
heading text لا نعم —
intro textarea لا نعم —
items repeater لا نعم —

12. النماذج وسجل الطلبات

توفر Forms API 1 سبعة معالجات معتمدة. تتحكم القوالب في التصميم، والإضافات في المخطط والتحقق وسير العمل. تتولى المنصة الحفظ والتحقق البشري والإشعارات.

إضافة النظامنوع النموذج
eyivo/contactتواصل contact
eyivo/quote-requestطلب عرض سعر quote_request
eyivo/product-inquiryاستفسار عن منتج product_inquiry
eyivo/appointment-requestطلب موعد appointment
eyivo/course-applicationطلب الالتحاق بدورة course_application
eyivo/reservation-requestطلب حجز reservation
eyivo/property-inquiryاستفسار عقاري property_inquiry

نموذج واحد في مواضع متعددة

ينشئ الإعداد UUID افتراضيًا ثابتًا لكل موقع وإضافة ونوع. إعادة استخدام الموضع تحفظ الهوية، وإنشاء نموذج مسمّى يمنحه UUID آخر. تغيير القالب وإعادة التثبيت يحفظان السجل. تستخدم القوالب أسماء ربط قابلة للنقل ويختار العميل نموذجًا محفوظًا دون إدخال UUID.

{
  "plugins": ["eyivo/contact", "eyivo/quote-request"],
  "forms": {
    "contact": {"plugin":"eyivo/contact","type":"contact","schema_version":1,"instance":"default"},
    "quote": {"plugin":"eyivo/quote-request","type":"quote_request","schema_version":1,"instance":"default"}
  }
}

استخدم forms.contact في التواصل وcomponent.form في أقسام النماذج. استبدل form_preset بـ form_binding. اعرض الحقول والإرشادات وaction وCSRF وform_context الموقّع وverification_html المقدّمة. تُقبل تغييرات العرض المعلنة والحقول الإضافية المسموحة فقط؛ لا يجوز إضعاف التحقق الإلزامي.

forms.contact · component.form · form_binding · form.fields · form.action · form.csrf_token · form.context · form.verification_html

عرضان لسجل واحد

يعرض الصندوق المشترك وصفحات قائمة وتفاصيل الإضافة السجلات نفسها. تتطلب حزم النماذج Panel API 2 ومكوّني submission-list وsubmission-detail ورابط قائمة بمستوى واحد. يبقى Panel API 1 مدعومًا. العرض لا يضع علامة مقروء؛ حالات القراءة والأرشفة والعمل منفصلة والتعديل يستخدم record_revision. تعطيل الإضافة يخفي صفحاتها؛ يبقى التاريخ في الصندوق المشترك.

{"components":[{"type":"submission-list","form_type":"contact","detail_page":"submission"}]}
{"components":[{"type":"submission-detail","form_type":"contact","list_page":"submissions"}]}

البيانات والأذونات

تُحفظ السجلات في قاعدة محتوى الموقع وتشارك حد الحزمة max_db_bytes مع المحتوى الآخر. لا توجد حصة إضافية للعدد أو مدة الاحتفاظ. تبقى الإعدادات في قاعدة master بحدود 50 حقلًا و32 كيلوبايت وثلاثة مستويات. الأعضاء يشاهدون والتعديل يتطلب صلاحية المالك أو الإدارة. لا وصول مباشر للإضافات إلى القاعدة ولا نقل PHP أو Blade إلى التطبيق.

حفظ موثّق وإشعارات

تتحقق المنصة من السياق والإجابات والتحقق البشري ثم تحفظ السجل والاستخدام ومهمة الإشعار معًا. يمكن استعادة المحاولة والبيانات نفسها خلال 24 ساعة دون تكرار. يعمل SMTP لاحقًا وقد يعيد المحاولة؛ فشل البريد لا يحذف السجل. إذا لم يُحدّد مستلم للنموذج يُستخدم بريد الشركة؛ وإذا لم يكن أي عنوان صالحًا يُحفظ الطلب دون بريد.

تستخدم جميع القوالب المرفقة هذا العقد. تعيد طلبات contact POST القديمة الحالة 410 وتبقى صفحات التواصل GET متاحة. طلب الموعد أو الحجز لا يؤكد حجزًا. معالجات الأطراف الأخرى ورفع الملفات والوجهات الخارجية العشوائية غير مشمولة.

POST /__eyivo/forms/{UUID}/submissions
GET /__eyivo/forms/{UUID}/challenge

13. التنقل الثانوي والأشرطة الجانبية

سجّل القوائم header وsecondary وsidebar وfooter وuseful_links في theme.json حسب الحاجة. اعرض navigation.secondary في شريط أدوات وnavigation.sidebar بجوار الصفحات العادية. يحرر المالكون كل قائمة وينشرونها عبر محرر القوائم القياسي. اجعل القائمة الرئيسية قصيرة؛ وعلى الشاشات الصغيرة يجب أن ينتقل الشريط الجانبي إلى أسفل محتوى الصفحة.

الشريط الجانبي منطقة تخطيط وليس مكوّنًا. أعلن عن منطقة sidebar في كل نوع صفحة يستخدمها، مع allowed_components الخاصة بها (مثل rich_text وannouncement وdownload_list وcontact_actions) وقيمة max، ثم اعرض areas.sidebar داخل <aside> بجوار navigation.sidebar:

{% if navigation.secondary.size > 0 %}
<nav aria-label="{{ 'Useful information' | t }}">
  {% for item in navigation.secondary %}
    <a href="{{ item.url }}"{% if item.active %} aria-current="page"{% endif %}>{{ item.label }}</a>
  {% endfor %}
</nav>
{% endif %}
<aside aria-label="{{ 'More information' | t }}">
  {% for item in navigation.sidebar %}
    <a href="{{ item.url }}">{{ item.label }}</a>
  {% endfor %}
  {{ areas.sidebar | raw }}
</aside>

15. قوالب الصفحات والقوالب الأساسية الاحتياطية

هناك عشرة أنواع صفحات قياسية: home وpage وcontact وproducts وproduct وgallery وvideos وblog وblog_category وblog_post. يمكن للقالب توفير العشرة كلها أو بعضها فقط؛ ويوفّر theme-core قالبًا عاملًا لكل نوع لا يعلن عنه القالب. احتفظ بأسماء المناطق وربط النماذج في الأنواع الأساسية عند استبدالها، حتى يستمر المحتوى الحالي والنماذج المسجلة في العمل بعد تغيير القالب.

16. واجهات الصفحات

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

17. الصور والمعارض والفيديو

أبقِ الصور المرفوعة داخل إطارات محددة: تحافظ صور الكتالوج على نسبها، ويمكن لصور التفاصيل ملء الإطار بقص متمركز. يمكن للمعارض فتح الصورة الأصلية في نافذة حوار تُغلق بمفتاح Escape وتعيد التركيز إلى رابط الصورة؛ ومن دون سكربتات اربط الصورة الأصلية لتُفتح في علامة تبويب جديدة. يجب أن تدعم شرائح عرض الصور اللمس والأزرار ولوحة المفاتيح والحركة المخففة.

18. النص المنسق وقواعد العرض المشتركة

يقبل المكوّن المشترك eyivo:rich_text المحتوى الموسوم من المحرر ومحتوى HTML القديم. يمر كلاهما عبر قائمة التنسيق المسموح به في المنصة: تظهر الفقرات والعناوين والقوائم والروابط الآمنة كمحتوى، بينما تُزال السكربتات ومعالجات الأحداث والروابط غير الآمنة. تبقى حقول النص الأخرى مُهرّبة. اعرض النص المنسق بالمرشحات المتوفرة لا بمعالجتك الخاصة لـ HTML.

19. المقدمات ومناطق التوجيه والصفحات الطويلة

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

20. الحركة والحركة المخففة

الحركة الزخرفية اختيارية. احترم prefers-reduced-motion في الانتقالات وشرائح العرض والأقسام المتحركة، وأوقف المحتوى المتحرك مؤقتًا أثناء تمرير الزائر فوقه أو وجود التركيز داخله.

21. قائمة التحقق للقالب الكامل

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

22. ماذا يحدث من تفعيل القالب حتى النشر؟

  1. تثبيت القالب أو تفعيله. يتحقق Eyivo من الحزمة ويسجّل مفتاحها وإصدارها ويعرض إعداداتها ومخططات مكوّناتها في التطبيق.
  2. اختيار نوع الصفحة. يستخدم Eyivo ملف Liquid وتعريف المنطقة المطابقين في القالب النشط عند وجودهما، وإلا يستخدم البديل المطابق من theme-core.
  3. إضافة الأقسام المسموح بها. يعرض التطبيق الأنواع المدرجة في allowed_components فقط. ويخزّن النصوص ومراجع الوسائط والترجمات للنسخة المحددة من المكوّن.
  4. العرض بأمان. يحلّ Eyivo بيانات الشركة والصفحة وSEO والتنقل، ويعرض مكوّنات المناطق المحفوظة ثم المكوّنات المباشرة في مواضعها التي حددها المصمم، وأخيرًا نوع الصفحة وتخطيط القالب النشط.
  5. النشر. يتلقى الزائر HTML وCSS الخاصين بك، دون بيانات اعتماد قاعدة البيانات أو النماذج الداخلية أو شفرة التطبيق.
  6. حدّث بإصدار جديد. رفع ملف ZIP ضمن القوالب المخصصة ينشئ قالبًا جديدًا. لتغيير قالب موجود، افتحه وارفع قيمة version في theme.json ثم ارفع إصدارًا جديدًا. ينتقل كل موقع عندما تستخدم الإصدار الجديد كمسودة وتنشره، ويبقى الإصدار السابق متاحًا للتراجع لمدة 30 يومًا.

23. التحقق والأخطاء الشائعة

إذا رأيت…تحقق أولًا من
«إصدار Eyivo Theme API غير مدعوم»عيّن "eyivo_theme_api": "1.0".
خطأ في فقدان نوع صفحة أو تخطيط أو مكوّنيحتاج كل نوع صفحة أو مكوّن يعلنه القالب إلى ملف .liquid مطابق. ويجب أن يوفّر القالب النشط دائمًا layouts/default.liquid؛ أما أنواع الصفحات المضمّنة المحذوفة فتستخدم بدائل النواة.
المكوّن غير متاح في المحرريجب إدراج نوعه مع مساحة الاسم في قائمة allowed_components لتلك المنطقة، أو تعريفه مكوّنًا عامًا.
مكوّن مباشر غير معروفاستخدم نوع eyivo: من الدليل المشترك داخل علامات اقتباس، أو عرّف نوع theme: مطابقًا مع ملف Liquid في القالب النشط.
رُفض الحقلعرّفه في مخطط المكوّن واستخدم أحد أنواع الحقول المدعومة. استخدم translatable: true للنص الخاص بكل لغة.
القالب يظهر دون تنسيقاستخدم مرشّح asset_url لملف CSS وتأكد من وجود الملف تحت assets/.
رُفضت الحزمة بسبب صيغة غير آمنةأزل PHP/Blade وenv وconfig واستدعاءات قاعدة البيانات أو HTTP والوصول إلى نظام الملفات. Liquid مخصص للعرض فقط.
قواعد السكربتات: custom_javascript_declaration وscript_file وscript_tag وscript_import وscript_sizeاتبع سكربتات القوالب. تظهر ملاحظات المراجعة في صفحة الإصدار مع الملف والسطر؛ أصلحها وارفع إصدارًا جديدًا.

24. الأسئلة الشائعة

هل يستطيع العميل إنشاء تخطيط جديد أو نقل قسم Hero أسفل التذييل؟

لا. يمكنهم تغيير المحتوى المعتمد وترتيب المكوّنات المسموح بها داخل منطقة. ويتحكم نوع صفحة Liquid في التخطيط.

هل يستطيع المصمم استخدام مكوّن دون منطقة قابلة للتعديل؟

نعم. استخدم eyivo_component في تخطيط أو نوع صفحة. واستخدم منطقة عندما ينبغي لمالك الموقع التحكم في نسخة المكوّن وترتيبها.

هل يجب على القالب تنفيذ كل نوع صفحة؟

دعم المدونة مطلوب في كل قالب. يمكن للأنواع المضمّنة blog وblog_category وblog_post استخدام التعريفات وملفات Liquid المطابقة من theme-core داخل تخطيط القالب النشط. لا تعلن نوعًا إلا عندما توفّر ملف تجاوز مطابقًا. وتبقى حزم القوالب الحالية متوافقة. تستخدم مسارات المدونة /blog و/blog/category/{slug} و/blog/{slug} مع بادئة لغة Eyivo عند الحاجة. حافظ على eyivo_head لبيانات وصفية آمنة وأنماط مدونة متجاوبة وبطاقات صور بأبعاد مضبوطة.

هل يستطيع القالب الاستعلام عن صفحة أو استدعاء API أو قراءة متغير بيئة؟

لا. تُمرر البيانات عمدًا ككائنات آمنة، مما يجعل القوالب قابلة للنقل وآمنة ويمكن التنبؤ بسلوكها.

كيف أنشر تحديثًا؟

انشر إصدارًا دلاليًا جديدًا للقالب. لا تغيّر إصدارًا منشورًا دون إعلان؛ وينبغي للمواقع الانتقال صراحة إلى الإصدار الجديد.

أين ينبغي حفظ الصور؟

استخدم رابط وسيط Eyivo في بيانات المكوّن، أو أصلًا من الحزمة مشارًا إليه عبر asset_url. لا تستخدم مسارات عشوائية في نظام ملفات الخادم.

25. سجل التغييرات

  • 31 أكتوبر 2026. Theme API 1.1: يمكن أن تتضمن القوالب JavaScript تمت مراجعتها في assets/js/ مع إمكانية custom_javascript. تُراجع الإصدارات الجديدة تلقائيًا وتظهر بحالة بانتظار المراجعة أو معتمد أو مرفوض أو محظور. لم تتغير حزم Theme API 1.0.
  • 31 أكتوبر 2026. يمكن للمالكين إضافة CSS مخصص للموقع يُحمَّل بعد أوراق الأنماط الخاصة بك، ومنح الأقسام أسماء فئات تُضاف إلى العنصر الأول لكل مكوّن وتتوفر عبر {{ component.css_class }}. راجع CSS المخصص للموقع وفئات الأقسام.
  • 31 أكتوبر 2026. يجب أن تستخدم وسائط العرض في demo.json مضيف https مسموحًا (cdn.eyivo.com أو images.pexels.com) أو ملفًا مضمَّنًا داخل assets/. تكتشف Eyivo نوع كل ملف من محتواه. هذا إصلاح أمني؛ وتبقى Theme API على الإصدار 1.0.
  • 30 أكتوبر 2026. تمنح Eyivo كل قالب مرفوع معرّفًا خاصًا به، والحقل key في theme.json اختياري. ارفع التغييرات كإصدار جديد من صفحة القالب. يحتفظ مستودع المثال بالقالب في المجلد sample-theme/ الذي تضغطه وترفعه. لم يعد مثال الحزمة يعرض assets/js/ لأن رفع القوالب بإصدار Theme API 1.0 لا يمكن أن يتضمن ملفات JavaScript.