Начало работы
Темы — это изолированный Liquid — шаблоны только с данными, рендерящиеся на сервере по фиксированному контракту данных. Темы поставляются с нулём JavaScript: корзина, опции позиций и оформление берутся из commerce runtime платформы, к которому ваша разметка привязывается декларативно.
- Скачайте и распакуйте стартовый набор.
- Переименуйте
slugвtheme.json. - Редактируйте секции в
sections/; добавляйте сниппеты вsnippets/. - Заархивируйте содержимое папки и отправьте на проверку.
Структура пакета
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 runtime один раз на страницу). Неизвестные фильтры/теги вызывают ошибку при загрузке.
Среда выполнения коммерции
Отпустить {% commerce %} один раз (обычно в конце шаблона), затем привяжите через data-атрибуты — runtime владеет состоянием корзины, панелью опций и оформлением:
<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>Оформите UI runtime через его .mb-* классы и CSS-переменные
(--mb-sheet-bg, --mb-sheet-ink, --mb-accent).
Настройки мерчанта
Мерчанты настраивают вашу тему в панели по вашим схемам. Приоритет: значения по умолчанию схемы ← значения шаблона ← значения мерчанта. Настройки хранятся независимо от версии темы, поэтому выпуск обновления никогда не стирает настройки мерчанта.
Правила и лимиты
- Нет
<script>, без встроенных обработчиков событий, безjavascript:URL, без iframe — отклоняется при загрузке. - Экранируйте видимые пользователю данные:
{{ item.name | escape }}. - Рендеринг ограничен по ресурсам (лимиты длины вывода + работы движка). Секция, дающая сбой во время выполнения, пропускается, а не превращает страницу в пустую; при загрузке это жёсткая ошибка.
- Опубликованные версии неизменяемы — обновления являются новыми версиями, проходящими проверку.
- Используйте логические CSS-свойства (
inline-size,margin-inline…) — меню рендерятся и в RTL.
