Jinja في ثيمات زد: القوالب والـ Objects والفلاتر والأنماط التي ستستخدمها يوميًا

أين تعيش Jinja داخل الثيم؟

ثيمات زد مبنية على محرك القوالب Jinja، وله صيغتان: {{ ... }} لعرض قيمة، و{% ... %} للمنطق والحلقات وبنية القالب. تدعم زد فلاتر Jinja الأساسية، وتضيف فوقها مجموعة صغيرة من الوسوم والفلاتر والماكروهات الخاصة بالمنصة. وهذه بنية المجلدات المطلوبة:

├── locale/ar/LC_MESSAGES/messages.po
├── assets/
├── sections/
│   ├── slider.jinja
│   └── slider.schema.json
├── components/
│   └── pagination.jinja
├── templates/
│   ├── home.jinja
│   ├── cart.jinja
│   └── product.jinja
├── layout.jinja
├── layout.schema.json
├── footer.jinja
├── footer.schema.json
├── header.jinja
└── header.schema.json

• أسماء القوالب والـLayout ومساراتها يجب أن تكون بالأسماء التي يعرفها النظام (مثل home.jinja وproduct.jinja وcart.jinja)، أما الأقسام والمكوّنات فتسميها كما تشاء.
• كل قسم .jinja يحتاج ملف .schema.json مقابلًا له في المجلد نفسه، والـLayout والرأس والتذييل تحتاج layout.schema.json وheader.schema.json وfooter.schema.json في جذر الثيم.
• الأصول في assets/، وتُعطى بصمة وتُقدَّم عبر CDN زد.

الوراثة والكتل والتضمين

كل قالب يمتد من layout.jinja ويملأ كتلة المحتوى؛ أمثلة مكتبة القوالب تستخدم الكتلة main_content. هذا مقتطف من مثال product.jinja في التوثيق:

{% extends "layout.jinja" %}

{% block main_content %}
  <h1>{{ product.name }}</h1>

  <div class="price">
    {% if product.selected_product.formatted_sale_price %}
      <span>{{ product.selected_product.formatted_sale_price }}</span>
      <del>{{ product.selected_product.formatted_price }}</del>
    {% else %}
      {{ product.selected_product.formatted_price }}
    {% endif %}
  </div>

  {{ product.description | safe }}

  {% include 'vitrin:products/variants_list.jinja' %}
  {% include 'vitrin:shared/bank_discounts.jinja' %}
{% endblock %}

• include يُدرج قالبًا آخر وقت العرض، مثل components/pagination.jinja. ولتمرير سياق محلي صغير: {% with a=1 %}{% include 'x' %}{% endwith %}.
• القوالب التي تديرها المنصة تُضمَّن بالبادئة vitrin:، مثل vitrin:products/variants_list.jinja وvitrin:cart/products_list.jinja.
• في الصفحة الرئيسية، الوسم {% template_components %} يعرض الأقسام التي يرتّبها التاجر في محرر الثيم.

الـ Objects المتاحة في القوالب

كل صفحة في مكتبة القوالب تسرد متغيراتها. store وsession متاحان في القوالب الموثّقة، ومعهما Object خاص بالصفحة:

• product في product.jinja: name وslug وdescription (HTML) وselected_product وهو المتغيّر الحالي بخصائصه formatted_price وformatted_sale_price وin_stock وsku وmedia، إضافة إلى variants وoptions وrating وrelated_products وbrand.
• brand وproducts في brand.jinja (المسار /brands/{slug_brand}): للعلامة id وname وslug وdescription وlogo، وقائمة المنتجات فيها results وcount وpage وpages_count وfilters. وقائمة كل العلامات في brands.jinja على المسار /brands.
• settings: نسخة مسطّحة من ملف المخطط؛ فالإعداد logo داخل المجموعة header يصبح settings.header_logo. والإعدادات داخل قائمة تصبح قائمة Objects تمر عليها بـ safeget(settings, "images", []).
• session: session.query_params.get('q') لURL Parameters، وsession.url.path للمسار الحالي، وsession.url.include_query_params(page=2) لبناء رابط بـ Parameters إضافية.
• store.settings: إعدادات المتجر، مثل store.settings.checkout.is_coupon_form_enabled.

الدوال والفلاتر الخاصة بالمنصة

• asset_url (فلتر): يعيد رابط CDN بإصدار محدد لملف من assets/.
• url_for: يبني رابط المسار من اسم العملية (Operation) ويحترم اللغة وقواعد التوجيه، مثل product_details وlist_products وcart_page وfaqs، ويقبل query_params لإضافة Parameters. مسارات العلامات التجارية غير مدعومة فيه حاليًا، فاستخدم /brands و/brands/{{ brand.slug }}.
• image_url (ماكرو): image_url(path, w=None, h=None, q=None, f=None)؛ w وh للأبعاد بالبكسل، وq للجودة من 0 إلى 100، وf='auto' ليختار المتصفح أفضل صيغة (AVIF أو WebP).
• التاريخ والوقت: today() وnow() وformat_datetime وformat_time، والمنطقة الزمنية واللغة مضبوطتان مسبقًا.
• فلاتر Jinja الأساسية تعمل كالمعتاد، مثل upper وlength وsafe (لعرض HTML خام) وdefault (أو d) وreplace وtojson وurlencode.

<link rel="stylesheet" href="{{ 'theme.css' | asset_url }}">

<a href="{{ url_for('product_details', slug=product.slug) }}">{{ product.name }}</a>
<a href="{{ url_for('faqs') }}">Help & FAQs</a>

<img src="{{ image_url(my_image, w=400, q=85, f='auto') }}" alt="">

{{ format_datetime(order.created_at, fmt="long") }}

أنماط شائعة: الحلقات والشروط والحماية من القيم الفارغة

أكثر نمط ستكتبه هو المرور على قائمة منتجات مع الفلاتر والتقسيم إلى صفحات. هذا مقتطف من مثال brand.jinja في التوثيق، وهو النمط نفسه في صفحات قوائم المنتجات:

{% extends "layout.jinja" %}

{% block main_content %}
  <h1>{{ brand.name }}</h1>

  {% if products.filters | length > 0 %}
    {% include 'vitrin:products/filters.jinja' %}
  {% endif %}

  <div class="products">
    {% for product in products.results %}
      {% include 'components/product-card.jinja' %}
    {% endfor %}
  </div>

  {% include 'components/pagination.jinja' %}
{% endblock %}

• Jinja تتعامل بأمان مع الوصول المتسلسل إلى قيم فارغة، لكن المرور على قيمة فارغة أو القسمة على صفر يكسر العرض. احمِ الحلقات بـ {% if var is defined and var is iterable %}.
• للقيم الافتراضية: {{ title or 'Untitled' }} أو {{ title | default('Untitled') }}، وdefault('x', true) يعامل القيم الفارغة مثل '' و0 كأنها غير موجودة.
• لعرض العلامة التجارية في صفحة المنتج، تحقق أولًا بـ {% if product.brand %} ثم اعرض product.brand.logo وproduct.brand.name.
• لمعرفة توفر المتغيّر الحالي استخدم product.selected_product.in_stock، وللمخزون product.selected_product.quantity.

الترجمة عبر gettext

القوالب تحتوي نصوصًا إنجليزية حرفية، وملف locale/ar/LC_MESSAGES/messages.po يربط كل نص (msgid) بترجمته (msgstr). الصيغ الأساسية:

{{ _("Add to cart") }}

{{ _("Hello %(name)s", name=user.name) }}

{% trans count=n %}{{ count }} item{% pluralize %}{{ count }} items{% endtrans %}

{{ pgettext("button", "Open") }}
{{ pgettext("verb", "Open") }}

• أبقِ النصوص حرفية ولا تبنها بالدمج، حتى تجدها أدوات الاستخراج.
• استخدم العناصر النائبة %(name)s بدل .format().
• {% trans %} مع {% pluralize %} يترك صيغ الجمع لقواعد اللغة، وهذا مهم للعربية التي لها ست صيغ (msgstr[0] إلى msgstr[5]).
• pgettext يفرّق بين نصين متطابقين بمعنيين مختلفين، واحرص أن يكون كل msgid فريدًا في الملف، وأبقِ وسوم HTML خارج النص المترجَم.

إعدادات المتجر التي تغيّر ما تعرضه: حقل الكوبون

بعض إعدادات التاجر يجب أن يحترمها القالب. يتحكم التاجر في حقل الكوبون من Settings ثم Checkout Options عبر الخيار Show coupon code field (مفعّل افتراضيًا)، ويقرأ الثيم القيمة store.settings.checkout.is_coupon_form_enabled:

{% set coupon_form_enabled = store.settings.checkout.is_coupon_form_enabled != false %}

{% if coupon_form_enabled %}
  <section class="cart-coupon" data-coupon-section>
    {# Coupon input, apply button, applied coupon details, and remove button #}
  </section>
{% endif %}

• استخدم != false لا شرط القيمة الصحيحة المباشر، حتى يبقى القسم ظاهرًا عندما تكون القيمة null أو غير موجودة.
• أخفِ القسم كاملًا: الحقل وزر التطبيق والكوبون المطبّق وزر الإزالة ورسائل التحقق والخطأ.
• لا تخفِه بـ CSS؛ الشرط في Jinja يمنع توليد HTML من الأساس.
• أضف فحصًا للقيمة الفارغة في JavaScript قبل الوصول إلى عناصر الكوبون، وطبّق الشرط في كل مواضع السلة.
• إعدادات المتجر قد تُخزَّن مؤقتًا حتى 10 دقائق، فانتظر قبل أن تحكم على نتيجة الاختبار.