البدء

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

نزّل القالب المبدئي (.zip)

1. نزّل القالب المبدئي وفكّ ضغطه.
2. أعد تسمية slug في theme.json.
3. حرّر الأقسام في sections/; أضف المقتطفات في snippets/.
4. اضغط محتويات المجلد وقدّمه للمراجعة.

بنية الحزمة

mytheme.zip
├── theme.json                  # manifest (data, never code)
├── templates/index.json        # OS 2.0 sectioned template (or index.liquid single-file)
├── sections/*.liquid           # section files, each with its schema block
├── snippets/*.liquid           # reusable partials for the render tag
├── config/settings_schema.json # theme-level settings (Shopify-style groups)
├── locales/en.json …           # theme strings for the t filter
├── assets/                     # css / images / fonts — static only
└── preview.png                 # listing screenshot

الحدود: 10 MB الرمز البريدي 2 MB لكل ملف، عمق المجلدات ≤ 3. أنواع الملفات المسموح بها: .liquid .json .css .png .jpg .jpeg .webp .svg .woff2. لا PHP. لا JavaScript. يجب ألّا تحتوي ملفات SVG على script أو foreignObject.

theme.json البيان

{
  "name": "My Theme",
  "slug": "my-theme",          // letters/numbers/dashes — becomes the install path
  "version": "1.0.0",          // published versions are immutable; ship updates as new versions
  "author": "You",
  "description": "…",
  "min_platform_version": "2.0"
}

القوالب والأقسام (OS 2.0)

templates/index.json يسرد نُسخ الأقسام; كل قسم هو ملف Liquid في sections/ يحمل مخطّط إعداداته في كتلة schema. الحدود: ≤ 25 قسمًا لكل قالب، ≤ 50 كتلة لكل قسم.

// templates/index.json
{
  "sections": {
    "hero":  { "type": "hero", "settings": { "heading": "Welcome" } },
    "menu":  { "type": "menu-grid",
               "blocks": { "b1": { "type": "badge", "settings": { "label": "New" } } },
               "block_order": ["b1"] }
  },
  "order": ["hero", "menu"]
}

داخل ملف القسم تستقبل section.id, section.type, section.settings.* و section.blocks (كل كتلة: id / type / settings.*). أنواع الإعدادات: text, textarea, color, checkbox, select (الخيارات), range (الحد الأدنى/الأقصى), image_picker.

البيانات — مرجع Drop

يمكن للقوالب الوصول إلى فقط الخصائص أدناه (المُولَّدة من فئات Drop في المنصّة — لا يمكن لهذا الجدول أن ينحرف). المتغيّرات العامة: restaurant, options, settings, menu, allergies, banners, branches, active_branch, table, customer, localization, flags, stats, و section داخل ملفات الأقسام. أي شيء آخر يُصيَّر فارغًا (ويسبّب خطأً عند الرفع).

AllergyDrop

id int image string title string

BannerDrop

id int image string image_url string link_url string subtitle string title string

BlockDrop

id string settings App\Storefront\Drops\SettingsDrop type string

BranchDrop

accepts_orders bool id int is_open bool name string status string

CategoryDrop

id int image_url string items array name string

CustomerDrop

name string phone string store_credit float store_credit_formatted string

ExtraDrop

id int name string price float

FlagsDrop

allow_order bool delivery bool on_table bool payment bool scheduling bool takeaway bool

ItemDrop

description string dietary_tags array extras array has_variants bool id int image string is_daily_special bool is_gluten_free bool is_halal bool is_popular bool is_sold_out bool is_vegan bool name string option_groups array price float rating float rating_count int variants array

LanguageDrop

code string direction string name string

LocalizationDrop

currencies array current App\Storefront\Drops\LanguageDrop direction string languages array

MenuDrop

categories array is_empty bool items array

OptionGroupDrop

choices array id int max_select int min_select int name string required bool

OptionsDrop

allow_call_waiter bool allow_coupons bool allow_dietary_filters bool allow_multi_branch_switch bool allow_order_scheduling bool allow_tips bool currency_code string currency_pos string currency_sign string customer_auth_mode string delivery_charge float enable_multi_currency bool menu_sections string min_order_value float open_close_store bool tax_charge float tax_label string whatsapp_number string

RestaurantDrop

address string color string cover string description string id int logo string main_image string phone string slug string sub_title string title string

SectionDrop

blocks array id string settings App\Storefront\Drops\SettingsDrop type string

SettingsDrop

StatsDrop

scans_today int

TableDrop

id int table_no string

VariantDrop

id int name string price float

المرشّحات والوسوم

مرشّحات المنصّة (بالإضافة إلى مجموعة Liquid الآمنة القياسية — escape, date, where, map, sort, size…):

media_urlmoneymoney_codettheme_asset

• t — ترجمة مفتاح. للقراءة فقط؛ المفاتيح غير المعروفة تُعيد المفتاح نفسه.
• money / money_code — تنسيق سعر بعملة المطعم.
• media_url — عنوان URL لصورة المطعم: {{ item.image | media_url: 'menu' }} (الأنواع: menu, logo, cover, allergy, banner).
• theme_asset — عنوان URL لأحد أصولك المُجمّعة: {{ 'css/style.css' | theme_asset }}.

العلامات schema (إعدادات القسم، تُزال من المُخرَجات), render (المقتطفات بالاسم — مجلّد snippets/ الخاص بك فقط), commerce (يُصدر بيئة تشغيل التجارة مرّة واحدة لكل صفحة). المرشّحات/الوسوم غير المعروفة تفشل عند الرفع.

بيئة تشغيل التجارة

أدرج {% commerce %} مرّة واحدة (عادةً في نهاية قالبك)، ثم اربط بسمات البيانات — بيئة التشغيل تملك حالة السلّة وورقة الخيارات والدفع:

<button data-mb-add="{{ item.id }}">Add</button>
<span   data-mb-cart-count></span>
<span   data-mb-cart-total></span>
<button data-mb-open-cart>Cart</button>
<button data-mb-call-waiter>Call waiter</button>
<div    data-mb-item-sheet-mount hidden></div>
<div    data-mb-cart-mount hidden></div>

نسّق واجهة بيئة التشغيل عبر .mb-* أصنافها وخصائص CSS المخصّصة (--mb-sheet-bg, --mb-sheet-ink, --mb-accent).

إعدادات التاجر

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

القواعد والحدود

• لا <script>, لا معالِجات أحداث مضمّنة، ولا javascript: عناوين URL، ولا إطارات iframe — تُرفض عند الرفع.
• قم بتهريب البيانات المرئية للمستخدم: {{ item.name | escape }}.
• التصيير محدود بالموارد (طول المُخرَجات + حدود عمل المحرّك). القسم الذي يفشل أثناء التشغيل يُتخطّى، دون صفحة فارغة أبدًا؛ وعند الرفع يكون خطأً صارمًا.
• الإصدارات المنشورة غير قابلة للتغيير — التحديثات هي إصدارات جديدة تمرّ عبر المراجعة.
• استخدم خصائص CSS المنطقية (inline-size, margin-inline…) — القوائم تُصيَّر من اليمين إلى اليسار أيضًا.