Начало работы
Темы — это изолированный 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
AnnouncementDrop
key string
text 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
FeaturesDrop
age_gate bool
call_waiter bool
catering bool
coupons bool
curbside bool
customer_wallet bool
dietary_filters bool
expiry bool
fitment bool
gift_cards bool
google_review bool
loyalty bool
meal_plans bool
multi_currency bool
reservations bool
scheduling bool
service bool
store_reviews bool
tips bool
variant_goods bool
waitlist bool
FlagsDrop
allow_order bool
delivery bool
on_table bool
payment bool
room_service bool
scheduling bool
takeaway bool
HoursDrop
closes_at string
has_hours bool
is_open bool
manual_closed bool
now_time string
opens_at string
state string
today string
today_key string
week array
ItemDrop
age_restricted bool
available_from_label string
available_now bool
description string
dietary_tags array
discount_percent int
expiry_date string
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
on_offer bool
option_groups array
original_price float
price float
pricing_unit string
rating float
rating_count int
reviews array
schedule_label string
sku string
stock_qty int
stock_status string
turnaround_hours 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
PlatformDrop
brand_name string
brand_url string
hide_branding bool
RestaurantDrop
address string
color string
cover string
description string
id int
logo string
main_image string
phone string
slug string
store_type string
sub_title string
title string
ReviewsDrop
author string
body string
created_at string
id int
is_verified bool
rating int
SectionDrop
blocks array
id string
settings App\Storefront\Drops\SettingsDrop
type string
SettingsDrop
SocialDrop
address string
facebook_url string
google_review_url string
instagram_url string
maps_url string
phone string
whatsapp string
whatsapp_url string
StatsDrop
scans_today int
StoryDrop
caption string
cta_label string
cta_url string
id int
image_url string
TableDrop
id int
table_no string
VariantDrop
id int
name string
price float
VocabDrop
add_to_cart string
board string
catalog string
categories string
category string
create_item string
group string
item string
items string
order string
orders string
Фильтры и теги
Фильтры платформы (плюс стандартный безопасный набор Liquid — escape, date, where, map, sort, size…):
media_urlmoneymoney_codestudio_blockstudio_textttheme_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.
