Erste Schritte

Themes sind sandboxed Liquid — 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)

1. Laden Sie den Starter herunter und entpacken Sie ihn.
2. Benennen Sie die slug in theme.json.
3. Bearbeiten Sie Sektionen in sections/; Fügen Sie Snippets hinzu in snippets/.
4. 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 screenshot

Limits: 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

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

Filter & Tags

Plattform-Filter (plus das standardmäßige sichere Liquid-Set — escape, date, where, map, sort, size…):

media_urlmoneymoney_codettheme_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, keine javascript: -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.