Primeiros passos

Os temas são Liquid em sandbox — templates somente de dados renderizados no servidor contra um contrato de dados fixo. Os temas vêm com zero JavaScript: carrinho, opções de item e checkout vêm do runtime de comércio da plataforma, ao qual sua marcação se vincula de forma declarativa.

Baixar o tema inicial (.zip)

  1. Baixe e descompacte o tema inicial.
  2. Renomeie o slug em theme.json.
  3. Edite seções em sections/; adicione snippets em snippets/.
  4. Compacte o conteúdo da pasta e envie para revisão.

Estrutura do pacote

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 CEP 2 MB por arquivo, profundidade de pasta ≤ 3. Tipos de arquivo permitidos: .liquid .json .css .png .jpg .jpeg .webp .svg .woff2. Sem PHP. Sem JavaScript. SVGs não devem conter script nem foreignObject.

theme.json Manifesto

{
  "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 e seções (OS 2.0)

templates/index.json listas instâncias de seção; cada seção é um arquivo Liquid em sections/ carregando seu schema de configurações em um bloco schema. Limites: ≤ 25 seções por template, ≤ 50 blocos por seção.

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

Dentro de um arquivo de seção você recebe section.id, section.type, section.settings.* e section.blocks (cada bloco: id / type / settings.*). Tipos de configuração: text, textarea, color, checkbox, select (Opções), range (mín/máx), image_picker.

Dados — a referência de Drop

Os templates podem acessar apenas as propriedades abaixo (geradas a partir das classes Drop da plataforma — esta tabela não pode divergir). Globais: restaurant, options, settings, menu, allergies, banners, branches, active_branch, table, customer, localization, flags, stats, e section dentro dos arquivos de seção. Qualquer outra coisa renderiza em branco (e gera erro no upload).

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

Filtros e tags

Filtros da plataforma (mais o conjunto Liquid seguro padrão — escape, date, where, map, sort, size…):

media_urlmoneymoney_codestudio_blockstudio_textttheme_asset

  • t — traduz uma chave. Somente leitura; chaves desconhecidas retornam a própria chave.
  • money / money_code — formata um preço com a moeda do restaurante.
  • media_url — URL da imagem do restaurante: {{ item.image | media_url: 'menu' }} (tipos: menu, logo, capa, alergia, banner).
  • theme_asset — URL de um dos seus assets incluídos: {{ 'css/style.css' | theme_asset }}.

Etiquetas schema (configurações da seção, removidas da saída), render (snippets por nome — seu snippets/ diretório apenas), commerce (emite o runtime de comércio uma vez por página). Filtros/tags desconhecidos falham no upload.

Runtime de comércio

Largar {% commerce %} uma vez (normalmente no final do seu template) e depois vincule com atributos data — o runtime controla o estado do carrinho, a folha de opções e o 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>

Estilize a interface do runtime por meio de suas .mb-* classes e propriedades CSS personalizadas (--mb-sheet-bg, --mb-sheet-ink, --mb-accent).

Configurações do lojista

Os lojistas personalizam seu tema no painel contra seus schemas. Precedência: padrões do schema ← valores do template ← valores do lojista. As configurações são armazenadas independentemente da versão do tema, então lançar uma atualização nunca apaga a personalização de um lojista.

Regras e limites

  • Não <script>, sem manipuladores de evento inline, sem javascript: URLs, sem iframes — rejeitados no upload.
  • Faça escape dos dados visíveis ao usuário: {{ item.name | escape }}.
  • As renderizações têm recursos limitados (limites de tamanho de saída + trabalho do motor). Uma seção que falha em tempo de execução é ignorada, nunca uma página em branco; no upload é um erro fatal.
  • As versões publicadas são imutáveis — atualizações são novas versões que passam por revisão.
  • Use propriedades CSS lógicas (inline-size, margin-inline…) — os menus também são renderizados em RTL.

Contate-nos

Siga-nos

Entrar Começar