Erste Schritte
Themes sind Liquid (Sandbox) — reine Daten-Templates, serverseitig gegen einen festen Datenvertrag gerendert. Themes werden ausgeliefert mit null JavaScript: Warenkorb, Artikeloptionen und Checkout stammen aus der Commerce-Runtime der Plattform, an die sich Ihr Markup deklarativ bindet.
Starter-Theme herunterladen (.zip)
- Laden Sie den Starter herunter und entpacken Sie ihn.
- Benennen Sie die
slugintheme.json. - Bearbeiten Sie Sektionen in
sections/; Fügen Sie Snippets hinzu insnippets/. - Zippen Sie den Ordnerinhalt und reichen Sie ihn zur Überprüfung ein.
Paketstruktur
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 screenshotLimits: 10 MB PLZ 2 MB pro Datei, Ordnertiefe ≤ 3. Zulässige Dateitypen: .liquid .json .css .png .jpg .jpeg .webp .svg .woff2.
Kein PHP. Kein JavaScript. SVGs dürfen kein script oder foreignObject enthalten.
theme.json Manifest
{
"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"
}Templates & Sektionen (OS 2.0)
templates/index.json listet Sektionsinstanzen; jede Sektion ist eine Liquid-Datei in
sections/ die ihr Einstellungsschema in einem Schema-Block trägt. Limits:
≤ 25 Sektionen pro Template, ≤ 50 Blöcke pro Sektion.
// 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"]
}Innerhalb einer Sektionsdatei erhalten Sie section.id, section.type,
section.settings.* und section.blocks (jeder Block:
id / type / settings.*). Einstellungstypen: text, textarea,
color, checkbox, select (Optionen), range
(min/max), image_picker.
Daten — die Drop-Referenz
Templates können auf nur die untenstehenden Eigenschaften zugreifen (generiert aus den Drop-Klassen der Plattform — diese Tabelle kann nicht abweichen). Globals:
restaurant, options, settings, menu,
allergies, banners, branches, active_branch,
table, customer, localization, flags,
stats, und section innerhalb von Sektionsdateien. Alles andere wird leer gerendert (und verursacht beim Hochladen einen Fehler).
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
Filter & Tags
Plattform-Filter (plus das standardmäßige sichere Liquid-Set — escape, date, where, map, sort, size…):
media_urlmoneymoney_codestudio_blockstudio_textttheme_asset
t— einen Schlüssel übersetzen. Schreibgeschützt; unbekannte Schlüssel geben den Schlüssel selbst zurück.money/money_code— einen Preis mit der Währung des Restaurants formatieren.media_url— Restaurant-Bild-URL:{{ item.image | media_url: 'menu' }}(Typen: menu, logo, cover, allergy, banner).theme_asset— URL eines Ihrer gebündelten Assets:{{ 'css/style.css' | theme_asset }}.
Tags schema (Sektionseinstellungen, aus der Ausgabe entfernt), render
(Snippets nach Name — Ihr snippets/ -Verzeichnis nur), commerce (gibt die Commerce-Runtime einmal pro Seite aus). Unbekannte Filter/Tags schlagen beim Hochladen fehl.
Commerce-Runtime
Rückgang {% commerce %} einmal (üblicherweise am Ende Ihres Templates), dann mit Data-Attributen binden — die Runtime verwaltet den Warenkorbstatus, das Optionsblatt und den Checkout:
<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>Gestalten Sie die Runtime-UI über ihre .mb-* Klassen und CSS-Custom-Properties
(--mb-sheet-bg, --mb-sheet-ink, --mb-accent).
Händlereinstellungen
Händler passen Ihr Theme im Dashboard anhand Ihrer Schemas an. Reihenfolge: Schema-Standards ← Template-Werte ← Händler-Werte. Einstellungen werden unabhängig von der Theme-Version gespeichert, sodass das Ausliefern eines Updates die Anpassungen eines Händlers niemals löscht.
Regeln & Limits
- Nein
<script>, keine Inline-Event-Handler, keinejavascript:-URLs, keine iframes — beim Hochladen abgelehnt. - Escapen Sie für Nutzer sichtbare Daten:
{{ item.name | escape }}. - Renderings sind ressourcenbegrenzt (Ausgabelänge + Engine-Arbeitslimits). Eine Sektion, die zur Laufzeit fehlschlägt, wird übersprungen, nie eine leere Seite; beim Hochladen ist es ein harter Fehler.
- Veröffentlichte Versionen sind unveränderlich — Updates sind neue Versionen, die durch die Überprüfung gehen.
- Verwenden Sie logische CSS-Eigenschaften (
inline-size,margin-inline…) — Menüs werden auch in RTL gerendert.
