Premiers pas

Les thèmes sont des Liquid en bac à sable — templates de données uniquement rendus côté serveur par rapport à un contrat de données fixe. Les thèmes sont livrés avec zéro JavaScript: le panier, les options d'article et le paiement proviennent du runtime de commerce de la plateforme, auquel votre balisage se lie de manière déclarative.

Télécharger le thème de démarrage (.zip)

1. Téléchargez et décompressez le thème de démarrage.
2. Renommez le slug dans theme.json.
3. modifiez les sections dans sections/; ajoutez des snippets dans snippets/.
4. Compressez le contenu du dossier et soumettez-le pour révision.

Structure du package

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

Limites : 10 MB Code postal 2 MB par fichier, profondeur de dossier ≤ 3. Types de fichiers autorisés : .liquid .json .css .png .jpg .jpeg .webp .svg .woff2. Pas de PHP. Pas de JavaScript. Les SVG ne doivent contenir aucun script ni foreignObject.

theme.json Manifeste

{
  "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 et sections (OS 2.0)

templates/index.json liste les instances de section; chaque section est un fichier Liquid dans sections/ portant son schéma de paramètres dans un bloc schema. Limites : ≤ 25 sections par template, ≤ 50 blocs par section.

// 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"]
}

Dans un fichier de section, vous recevez section.id, section.type, section.settings.* et section.blocks (chaque bloc : id / type / settings.*). Types de paramètre : text, textarea, color, checkbox, select (Options), range (min/max), image_picker.

Données — la référence Drop

Les templates peuvent atteindre uniquement les propriétés ci-dessous (générées à partir des classes Drop de la plateforme — cette table ne peut pas dériver). Globales : restaurant, options, settings, menu, allergies, banners, branches, active_branch, table, customer, localization, flags, stats, et section dans les fichiers de section. Tout le reste s'affiche vide (et provoque une erreur à l'envoi).

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

Filtres et balises

Filtres de la plateforme (plus l'ensemble Liquid sûr standard — escape, date, where, map, sort, size…) :

media_urlmoneymoney_codettheme_asset

• t — traduire une clé. Lecture seule ; les clés inconnues renvoient la clé elle-même.
• money / money_code — formater un prix avec la devise du restaurant.
• media_url — URL de l'image du restaurant : {{ item.image | media_url: 'menu' }} (types : menu, logo, couverture, allergies, bannière).
• theme_asset — URL de l'un de vos assets fournis : {{ 'css/style.css' | theme_asset }}.

Étiquettes schema (paramètres de section, retirés de la sortie), render (snippets par nom — votre snippets/ répertoire uniquement), commerce (émet le runtime de commerce une fois par page). Les filtres/balises inconnus échouent à l'envoi.

Runtime de commerce

Baisse {% commerce %} une fois (généralement à la fin de votre template), puis liez avec des attributs data — le runtime gère l'état du panier, la feuille d'options et le paiement :

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

Habillez l'interface du runtime via ses .mb-* classes et propriétés CSS personnalisées (--mb-sheet-bg, --mb-sheet-ink, --mb-accent).

Paramètres marchand

Les marchands personnalisent votre thème dans le tableau de bord par rapport à vos schémas. Priorité : valeurs par défaut du schéma ← valeurs du template ← valeurs du marchand. Les paramètres sont stockés indépendamment de la version du thème, donc livrer une mise à jour n'efface jamais la personnalisation d'un marchand.

Règles et limites

• Non <script>, aucun gestionnaire d'événement en ligne, aucune javascript: URL, aucun iframe — rejetés à l'envoi.
• Échappez les données visibles par l'utilisateur : {{ item.name | escape }}.
• Les rendus sont bornés en ressources (limites de longueur de sortie + de travail du moteur). Une section qui échoue à l'exécution est ignorée, jamais une page blanche ; à l'envoi, c'est une erreur bloquante.
• Les versions publiées sont immuables — les mises à jour sont de nouvelles versions passant par la révision.
• Utilisez les propriétés CSS logiques (inline-size, margin-inline…) — les menus s'affichent aussi en RTL.