# Editor Local (CLI) Source: https://allbay.mintlify.app/editor/editor-local Edite o tema na sua máquina com o VS Code — sincronização automática. Prefere editar na sua máquina, com o VS Code (ou qualquer editor) e as suas ferramentas? O **editor local** baixa os arquivos do tema para uma pasta e sincroniza cada alteração com a loja automaticamente. ```bash theme={null} npx allbay-editor@latest login npx allbay-editor@latest --template SEU_ID_DO_TEMPLATE ``` ## Pré-requisitos * **Node.js 18+**. * Um editor de código (VS Code recomendado). * A loja precisa ter a vantagem de **template próprio** no nível dela (é ela que libera editar código). ## Passo a passo **1. Pegue o ID do template** No painel, vá em **Aparência → Template**, abra o menu **⋮** do seu tema e escolha **Editar no seu computador** (no Studio: botão **Sessão local**). Copie o **ID do template**. **2. Faça login (uma vez)** ```bash theme={null} npx allbay-editor@latest login ``` O navegador abre para você autorizar. A sessão fica salva no seu computador e é renovada sozinha. **3. Baixe e edite** ```bash theme={null} mkdir meu-tema && cd meu-tema npx allbay-editor@latest --template SEU_ID_DO_TEMPLATE ``` O CLI baixa todos os arquivos do tema para a pasta. Abra a pasta no seu editor: **cada arquivo salvo é sincronizado** com a loja, como rascunho. **4. Publique** Quando estiver pronto, publique pelo painel/Studio ou pelo próprio CLI: ```bash theme={null} npx allbay-editor@latest publish --template SEU_ID_DO_TEMPLATE ``` O comando publica o rascunho e coloca o tema no ar. ## Como funciona a sincronização * O CLI **baixa** todos os arquivos ao iniciar (arquivos locais com o mesmo nome são substituídos). * Enquanto roda, **observa** a pasta: a cada save, envia o tema inteiro como **rascunho**. * Só envia arquivos `.html`, `.liquid`, `.css`, `.js` e `.json`. Arquivos começando com `.`, `node_modules` e outros tipos ficam só na sua máquina. * **Apagar** um arquivo da pasta apaga do tema no próximo envio. > [!WARNING] > > Não edite o mesmo tema no painel e no editor local ao mesmo tempo: a cópia da sua pasta > **substitui** o que foi alterado no painel. ## Comandos e opções | Comando / opção | Descrição | | - | - | | `login` | Autoriza o CLI pelo navegador | | `--template ` | Edita o template `` (rascunho) | | `publish --template ` | Publica o rascunho e coloca no ar | | `logout` | Apaga a sessão salva neste computador | | `--dir`, `-d` | Pasta local do tema (padrão: pasta atual) | | `--pull` | Só baixa os arquivos e sai (não observa) | | `--help`, `-h` | Ajuda | ## Limites * Até **100 arquivos** por tema, **5 MiB** no total. * Extensões e nomes de arquivo: ver [Estrutura](/editor/estrutura#tipos-de-arquivo). > [!WARNING] > > A sessão do editor local dá acesso de edição aos temas de **todas as lojas** em que você pode > editar o tema — trate seu computador como confiável. Para encerrá-la, rode `logout` e, se > necessário, saia de todos os dispositivos na sua conta. ## Editar com IA Com os arquivos na sua máquina, você pode usar assistentes de IA: > [card] [Claude Code](/editor/ia/claude) > [card] [Cursor](/editor/ia/cursor) # Estrutura de Arquivos Source: https://allbay.mintlify.app/editor/estrutura Como um tema AllBay é organizado — pastas, arquivos, limites e resolução de rotas. Um tema é um conjunto de arquivos de texto versionados. A AllBay resolve cada rota da loja para um arquivo de página, envolve no layout e renderiza com Liquid. ## Pastas Arquivos novos só podem ser criados nestas pastas (diretamente dentro delas): | Pasta | Conteúdo | | - | - | | `pages/` | Páginas (index, category, package, checkout, order…) | | `pages/account/` | Área do cliente (orders, affiliate) | | `templates/` | Alternativa a `pages/` para as páginas | | `layouts/` | Layouts que envolvem as páginas | | `components/` · `snippets/` | Elementos reutilizáveis (`{% render %}`) | | `sections/` | Blocos usados com `{% section %}` | | `styles/` | CSS | | `scripts/` | JavaScript | | `assets/` · `widgets/` | Arquivos de apoio | Arquivos que vieram com o tema base podem estar em outros lugares e continuam valendo. > [!NOTE] > > O tema **Vega** usa: `components/`, `layouts/layout.liquid`, `pages/` (com > `pages/account/`), `scripts/`, `styles/core.css` e um `tailwind.config.json` na raiz. ## Tipos de arquivo | Extensão | Uso | | - | - | | `.liquid` | Páginas, layouts, componentes e seções (recomendado) | | `.html` | Também é Liquid; aceito por compatibilidade | | `.css` | Estilos | | `.js` | Scripts | | `.json` | **Só** os arquivos de sistema: `tailwind.config.json` e `config/settings_schema.json` | Qualquer outra extensão (`.ts`, `.jsx`, `.md`, `.svg`, imagens, fontes…) é recusada. Imagens não ficam no tema: entram pelos campos `image`/`images` do [schema](/editor/schema) e são servidas pela CDN (ver [Imagens](/editor/imagens)). ## Limites | Limite | Valor | | - | - | | Arquivos por tema | **100** (no total) | | Tamanho total do tema | **5 MiB** | | Profundidade de caminho | **8** níveis | | Nome do arquivo | até **32** caracteres (sem contar a extensão) | | Arquivos novos por pasta | **45** | | Temas editáveis por loja (em branco ou fork) | **10** | ## Nomes de arquivo * Arquivos **novos**: só letras **minúsculas**, números, `.`, `_` e `-`; o primeiro caractere precisa ser letra ou número. Ex.: `product-card.liquid`. * Nada de **espaços** nem caracteres fora do ASCII visível. * `dotfiles` (`.env`, `.git/…`) e segmentos `.`/`..` são recusados em qualquer nível. * Arquivos novos ficam a no máximo 2 níveis (`components/card.liquid`), ou 3 em `pages/account/`. ## Arquivos de sistema `tailwind.config.json` e `config/settings_schema.json` são arquivos de sistema: o conteúdo é editável, mas eles só podem existir nesses caminhos. No editor web, eles, a página inicial e os arquivos do tema base aparecem como **travados** (sem apagar/renomear). > [!WARNING] > > Pelo [Editor Local](/editor/editor-local), apagar um arquivo da pasta **apaga do tema**. > Não apague a página inicial: sem ela o tema não publica. ## Componentes Inclua um componente com `{% render %}`: ```liquid theme={null} {% render 'components/navbar' %} {% render 'navbar' %} ``` Com um nome simples (`'navbar'`), a AllBay procura a partir da raiz do tema, depois em `snippets/` e depois em `components/` — com a extensão dada, `.liquid`, `.html` ou sem extensão. Ver [Tags](/editor/tags#render-componentes). ## Layouts Duas formas de envolver as páginas — ver [Páginas](/editor/paginas#layouts): * **Automática:** se existir `layouts/base.liquid`, toda página é renderizada dentro dele, no lugar de `{{ content_for_layout }}`. * **Declarada:** a página começa com `{% layout 'layouts/layout' %}` e o conteúdo dela entra no `{% block %}{% endblock %}` do layout (é o que o Vega usa). ## Resolução de páginas (aliases) Cada rota resolve para um arquivo de entrada, e você não precisa nomear tudo exatamente igual. A AllBay tenta, em ordem: 1. `templates/` (`.liquid`, depois `.html`); 2. `templates/`; 3. `pages/`; 4. `pages/`. Aliases de nome: `product ≡ package`, `collection ≡ category`, `cart ≡ checkout`, `404 ≡ not-found`. O nome canônico sempre vence o alias. Por isso o Vega (que só tem `pages/`) atende a rota de produto com `pages/package.liquid` e a de coleção com `pages/category.liquid`. Ver a tabela completa em [Páginas](/editor/paginas). ## Configuração (schema) O arquivo `config/settings_schema.json` define as opções que aparecem no painel (cores, textos, imagens…). Ver [Schema](/editor/schema). # Filtros Source: https://allbay.mintlify.app/editor/filtros Transforme valores com | — filtros próprios da AllBay e do Liquid. Filtros transformam valores com o operador pipe `|`, e podem ser encadeados: ```liquid theme={null} {{ 29.90 | money }} {{ store.name | upcase | truncate: 20 }} ``` Apenas os filtros desta página existem. Um filtro fora da lista é **erro**: a página não renderiza. ## Filtros da AllBay | Filtro | O que faz | Exemplo | | - | - | - | | `money` | Formata como moeda da loja (`BRL`, `USD` ou `EUR`); recebe o valor **em reais** | `29.90` → `R$ 29,90` | | `format_price` | Alias de `money` | `29.90` → `R$ 29,90` | | `hex_to_hsl` | Hex de 6 dígitos → HSL (sem `hsl()`); valor inválido vira `0 0% 0%` | `#ff0000` → `0 100% 50%` | | `cdn_url` | URL de imagem a partir do **hash** (ver abaixo) | `{{ p.image \| cdn_url: 'products', p.id, 'image' }}` | | `cdn` | Alias de `cdn_url` | | | `asset_url` | Caminho de um arquivo estático | `{{ 'app.js' \| asset_url }}` → `/assets/app.js` | | `compact_number` | Número compacto | `1200` → `1.2K` · `2500000` → `2.5M` | | `stars` | Estrelas (0–5, arredondado) | `4` → `★★★★☆` | | `stock_label` | Rótulo de estoque | `0` → `Esgotado` · `12` → `12 em estoque` · `nil` → `Ilimitado` | | `percent_off` | % de desconto, **só o número** | `{{ 80 \| percent_off: 100 }}` → `20` | | `slugify` | Texto → slug | `Plano VIP Ação` → `plano-vip-acao` | | `time_ago` | Tempo relativo (pt-BR; minutos, horas ou dias) | `→ há 2 dias` | | `date_format` | Data por extenso (pt-BR) | `→ 23 de outubro de 2026` | | `placeholder` | Usa o fallback se o valor for `nil` ou `""` | `{{ x \| placeholder: '—' }}` | | `default` | Fallback para `nil`, `false`, `""` e `[]` (o zero passa) | `{{ 0 \| default: '100+' }}` → `0` | Exemplo de selo de desconto: ```liquid theme={null} {% assign off = product.price | percent_off: product.comparison_price %} {% if off > 0 %}-{{ off }}%{% endif %} ``` ### `cdn_url` Quase todas as imagens já chegam ao tema como **URL pronta** — use direto, sem filtro (ver [Imagens](/editor/imagens)). `cdn_url` só é necessário para as imagens que chegam como **hash**, como as de `{% load "products" %}`, `{% load "product" %}` e `{% load "categories" %}`: ```liquid theme={null} {% load "products", limit: 8 %} {% for p in products %} {% assign img = p.image | cdn_url: 'products', p.id, 'image' %} {% if img != "" %}{{ p.name }}{% endif %} {% endfor %} ``` * Argumentos: `hash | cdn_url: '', , ''` — tipo `products`, `variants` ou `categories`; campo `image` ou `banner`. **Os quatro são necessários.** * Gera uma imagem **WebP de 256 px**. * Devolve **vazio** se a imagem não puder ser servida — sempre teste antes de usar. * Imagens animadas e de galeria não são resolvidas por este filtro. ## Filtros do Liquid * **Texto:** `upcase`, `downcase`, `capitalize`, `truncate`, `truncatewords`, `strip_html`, `strip_newlines`, `escape`, `escape_once`, `newline_to_br`, `replace`, `replace_first`, `replace_last`, `remove`, `remove_first`, `remove_last`, `append`, `prepend`, `split`, `slice`, `strip`, `lstrip`, `rstrip`, `normalize_whitespace`, `number_of_words`. * **URL e codificação:** `url_encode`, `url_decode`, `uri_escape`, `cgi_escape`, `xml_escape`, `base64_encode`, `base64_decode`, `sha256`, `hmac_sha256`. * **Número:** `plus`, `minus`, `times`, `divided_by`, `modulo`, `round`, `floor`, `ceil`, `abs`, `at_least`, `at_most`, `to_integer`. * **Lista:** `size`, `first`, `last`, `join`, `sort`, `sort_natural`, `reverse`, `map`, `where`, `where_exp`, `reject`, `reject_exp`, `find`, `find_exp`, `find_index`, `find_index_exp`, `has`, `has_exp`, `group_by`, `group_by_exp`, `uniq`, `compact`, `concat`, `sum`, `sample`, `array_to_sentence_string`. * **Data:** `date` (ex.: `{{ post.published_at_iso | date: '%d/%m/%Y' }}`), `date_to_string`, `date_to_long_string`, `date_to_rfc822`, `date_to_xmlschema`. * **JSON:** `json` (serializa um objeto — útil para passar dados a um script). * **Outros:** `raw`. > [!NOTE] > > Não existem: `push`, `pop`, `shift`, `unshift`, `jsonify`, `inspect`. # Claude Code Source: https://allbay.mintlify.app/editor/ia/claude Edite seu tema AllBay com o Claude Code, por linguagem natural. O [Claude Code](https://claude.com/claude-code) é o agente de código da Anthropic (terminal ou extensão do VS Code). Com o [Editor Local](/editor/editor-local), você descreve o que quer e o Claude edita os arquivos do tema. ## Pré-requisitos * O [Editor Local](/editor/editor-local) com login feito e rodando na pasta do tema. * Claude Code instalado. ## Passo a passo **1. Baixe o tema e deixe o CLI rodando** ```bash theme={null} mkdir meu-tema && cd meu-tema npx allbay-editor@latest --template SEU_ID_DO_TEMPLATE ``` Deixe esse terminal aberto — ele sincroniza cada save. **2. Abra o Claude Code na pasta** Em outro terminal, na mesma pasta, rode `claude` (ou abra a pasta pela extensão do VS Code). **3. Peça a mudança** Descreva em português: > "Adicione um banner promocional verde no topo da home." O Claude edita os `.liquid`/`.css`/`.js`. Ao salvar, o CLI sincroniza. ## Conecte a documentação ao Claude (MCP) Esta documentação tem um servidor **MCP**: com ele, o Claude consulta as páginas da AllBay sozinho enquanto trabalha, em vez de adivinhar sintaxe e objetos. Rode uma vez, na pasta do tema: ```bash theme={null} claude mcp add --transport http allbay-docs https://allbay.mintlify.app/mcp ``` O servidor oferece busca na documentação e leitura das páginas. Para conferir, rode `/mcp` dentro do Claude Code. > [!TIP] > > Para outras IAs, a documentação inteira também está em texto em > [llms.txt](https://allbay.mintlify.app/llms.txt) (índice) e > [llms-full.txt](https://allbay.mintlify.app/llms-full.txt) (conteúdo completo). ## Dê contexto ao Claude (recomendado) Crie um arquivo **`CLAUDE.md`** na raiz do tema com as regras da plataforma. Ele fica só na sua máquina (o CLI não envia `.md`): ```md CLAUDE.md theme={null} # Tema AllBay (Liquid) - Lógica `{% %}`, saída `{{ }}`. Componentes: `{% render 'components/nome', var: valor %}` (componentes só veem globais e parâmetros). - Falsos: nil, false, 0 e "". Lista vazia [] é verdadeira — use `lista.size > 0`. - Dados: `{% load "packages", limit: 8 %}` (cards com imagens prontas). Alias logo após a entidade: `{% load "product" as p, slug: "x" %}`. Ids sempre entre aspas. - Globais: store, theme, config, settings, user, customer, logged_in, categories, products, packages, product, gateways, socials, order, orders, posts, post, cart, terms, query, pathname. - Preços com `| money` (valores em reais). Desconto: `price | percent_off: comparison_price` → número. - Imagens já vêm como URL pronta: use direto e teste antes (`{% if img %}`). `cdn_url` só para hash de `load "products"/"product"/"categories"`: `{{ x.image | cdn_url: 'products', x.id, 'image' }}`. - Schema: `config/settings_schema.json`; chaves só com letras, números e `_` (sem hífen). - Arquivos novos: só .liquid/.html/.css/.js, nomes em minúsculas até 32 caracteres, nas pastas pages, templates, layouts, components, snippets, sections, styles, scripts, assets. - Login é da plataforma (não crie pages/login). - Página nova: `pages/.liquid` vira `/pages/` (nunca `/`). Nome em minúsculas, sem ponto, sem subpasta e diferente das páginas da plataforma. Sem dados próprios: use `{% load %}`. Comece com `{% layout %}` e ponha um link para ela no tema. - Docs: https://allbay.mintlify.app/editor/introducao (MCP: https://allbay.mintlify.app/mcp) Faça UMA mudança por vez e confira no preview antes de seguir. ``` > [!TIP] > > Referencie as páginas de [Sintaxe](/editor/sintaxe), [Tags](/editor/tags), > [Filtros](/editor/filtros), [Imagens](/editor/imagens) e > [Variáveis Globais](/editor/variaveis-globais) para o Claude acertar de primeira. > [!WARNING] > > Faça mudanças pequenas e confira o preview a cada passo. Antes de mexidas grandes, baixe o > tema em `.zip` pelo painel como backup. # Cursor Source: https://allbay.mintlify.app/editor/ia/cursor Edite seu tema AllBay com o Cursor, por linguagem natural. O [Cursor](https://cursor.com) é um editor de código com IA integrada (baseado no VS Code). Com o [Editor Local](/editor/editor-local), você descreve as mudanças e o Cursor edita os arquivos do tema. ## Pré-requisitos * O [Editor Local](/editor/editor-local) com login feito e rodando na pasta do tema. * Cursor instalado. ## Passo a passo **1. Baixe o tema e deixe o CLI rodando** ```bash theme={null} mkdir meu-tema && cd meu-tema npx allbay-editor@latest --template SEU_ID_DO_TEMPLATE ``` Deixe esse terminal aberto — ele sincroniza cada save. **2. Abra a pasta no Cursor** Use o chat (`Ctrl/Cmd + L`) ou a edição inline (`Ctrl/Cmd + K`). **3. Peça a mudança** > "Deixe o cabeçalho fixo no topo ao rolar a página." O Cursor edita os arquivos; aceite as sugestões e salve — o CLI sincroniza. Para mudanças em vários arquivos, use o chat com `@Codebase`. ## Conecte a documentação ao Cursor (MCP) Esta documentação tem um servidor **MCP**: com ele, o Cursor consulta as páginas da AllBay enquanto trabalha. Crie o arquivo **`.cursor/mcp.json`** na raiz do tema (ele fica só na sua máquina): ```json .cursor/mcp.json theme={null} { "mcpServers": { "allbay-docs": { "url": "https://allbay.mintlify.app/mcp" } } } ``` Depois, confira em **Settings → MCP** que o `allbay-docs` aparece ativo. O servidor oferece busca na documentação e leitura das páginas. > [!TIP] > > Para outras IAs, a documentação inteira também está em texto em > [llms.txt](https://allbay.mintlify.app/llms.txt) (índice) e > [llms-full.txt](https://allbay.mintlify.app/llms-full.txt) (conteúdo completo). ## Dê contexto ao Cursor (recomendado) Crie um arquivo **`.cursorrules`** na raiz do tema (ele fica só na sua máquina): ```md .cursorrules theme={null} Este projeto é um tema AllBay em Liquid. - Lógica {% %}, saída {{ }}. Componentes: {% render 'components/nome', var: valor %} (componentes só veem globais e parâmetros). - Falsos: nil, false, 0 e "". Lista vazia [] é verdadeira — use lista.size > 0. - Dados: {% load "packages", limit: 8 %}. Alias logo após a entidade: {% load "product" as p, slug: "x" %}. Ids sempre entre aspas. - Objetos: store, theme, config, settings, user, logged_in, categories, products, packages, product, gateways, socials, order, orders, posts, post, cart, terms, query, pathname. - Preços com | money. Imagens já vêm como URL pronta (teste antes de usar); cdn_url só para hash de load "products"/"product"/"categories", com 4 argumentos. - Schema: chaves só com letras, números e _ (sem hífen). - Arquivos novos: só .liquid/.html/.css/.js, nomes em minúsculas até 32 caracteres. - Login é da plataforma (não crie pages/login). - Página nova: pages/.liquid vira /pages/ (nunca /). Nome em minúsculas, sem ponto, sem subpasta e diferente das páginas da plataforma. Sem dados próprios: use {% load %}. Comece com {% layout %} e ponha um link para ela no tema. - Docs: https://allbay.mintlify.app/editor/introducao (MCP: https://allbay.mintlify.app/mcp) Faça uma mudança por vez. ``` > [!TIP] > > Referencie [Sintaxe](/editor/sintaxe), [Tags](/editor/tags), [Filtros](/editor/filtros), > [Imagens](/editor/imagens) e [Variáveis Globais](/editor/variaveis-globais). > [!WARNING] > > Faça mudanças pequenas e confira o preview. Antes de mexidas grandes, baixe o tema em `.zip` > pelo painel como backup. # Imagens Source: https://allbay.mintlify.app/editor/imagens Como as imagens chegam ao tema — URLs prontas da CDN e quando usar cdn_url. As imagens da loja (logo, banners, produtos, categorias, imagens do schema) são servidas pela **CDN da AllBay**. Na grande maioria dos casos elas chegam ao tema como **URL pronta**: use direto no `src`, sem filtro. ```liquid theme={null} {% if product.image %} {{ product.name }} {% endif %} ``` ## Regras de ouro 1. **Use a URL como ela vem.** Não monte nem altere URLs de imagem. 2. **Sempre teste antes de usar.** Uma imagem que não pode ser servida chega **vazia** (`""`, `null` ou ausente) — nunca escreva ``. 3. **`cdn_url` só para hash.** Ele existe apenas para as imagens que chegam como hash (ver [abaixo](#quando-usar-cdn_url)). ## Formato ``` https://cdn.allbay.io/i/.webp?w=512 ``` O parâmetro `w` é a largura entregue — a AllBay já escolhe o tamanho certo para cada campo. ## Onde as imagens chegam prontas | Campo | Tamanho entregue | | - | - | | `theme.logo`, `shop.logo_url` | 64 px (ícone) | | `theme.banner`, `shop.banner_url` | 1024 px | | `theme.favicon`, `favicon` | 64 px, estático | | `config.hero_image` · `config.background_image` | 1024 px · 512 px | | `theme.hero_image` · `theme.background_image` | original | | Campos `image`/`images` do [schema](/editor/schema) em `config`/`settings` | original | | `config.hero_banner` / `config.hero_banners` | 2048 px | | Card de produto (`products`, `packages.data`, `category.products`): `image`, `banner`, `image_url`, `banner_url` | 512 px | | Produto da página (`product`): `image`, `banner`, `image_url`, `gallery[]`, `images[]` | até 1024 px | | Categorias: `image`, `banner`, `image_url`, `banner_url`, `icon_url` | — | | `post.image` | original | | Produto em avaliações (`feedbacks`) | 64 px | > [!WARNING] > > * No **card**, `image`, `banner`, `image_url` e `banner_url` são a **mesma** imagem (o banner do > produto, ou a imagem quando não há banner). Na **página do produto**, `image_url` é a imagem > do produto e `images` começa pelo banner, seguido da galeria. > * `gallery[]` e `images[]` podem conter **vídeos** (`.mp4`). Confira a extensão antes de usar > em ``: `{% unless img contains '.mp4' %}…{% endunless %}`. > * O logo vem pequeno. Para um logo grande, crie um campo de imagem no schema. ## Quando usar `cdn_url` Os resultados destes `load` trazem as imagens como **hash**, não como URL: * `{% load "products" %}` * `{% load "product" %}` * `{% load "categories" %}` Converta com `cdn_url`, informando o tipo, o id e o campo: ```liquid theme={null} {% load "products", limit: 8 %} {% for p in products %} {% assign img = p.image | cdn_url: 'products', p.id, 'image' %} {% if img != "" %}{{ p.name }}{% endif %} {% endfor %} ``` | Tipo | Campos | | - | - | | `'products'` | `'image'`, `'banner'` | | `'variants'` | `'image'`, `'banner'` | | `'categories'` | `'image'`, `'banner'` | O resultado é uma imagem WebP de **256 px**. Imagens de galeria e imagens animadas não são resolvidas por `cdn_url`. > [!TIP] > > Prefira `{% load "packages" %}` a `{% load "products" %}` quando for mostrar cards: ele já > devolve os produtos no formato de card, com as **imagens prontas**. ## Imagens do schema Os campos `image` e `images` do [schema](/editor/schema) guardam a imagem enviada pelo dono e chegam em `config`/`settings` já como **URL pronta**: ```liquid theme={null} {% if config.hero_image %}{% endif %} {% for img in config.gallery %} {% if img != "" %}{% endif %} {% endfor %} ``` > [!NOTE] > > Hoje só os campos `image`/`images` **de primeiro nível** do schema viram URL. Um campo > `image` **dentro de um item de `array`** chega como hash e não pode ser exibido — evite > esse formato por enquanto. # Introdução Source: https://allbay.mintlify.app/editor/introducao Personalize a aparência e o comportamento da sua loja AllBay com código. O editor de temas da AllBay permite personalizar por completo a aparência e o comportamento da sua loja usando **Liquid**, com objetos, tags e filtros próprios da plataforma. ## O que você pode fazer * Editar **HTML, CSS e JavaScript** de todas as páginas da loja. * Criar **componentes** reutilizáveis e **layouts** personalizados. * Usar **variáveis dinâmicas** (dados da loja, categorias, produtos, pedidos, termos). * Carregar dados sob demanda com a tag [`{% load %}`](/editor/tags#load-dados-dinâmicos). * Definir opções visuais via **schema**, editáveis no painel sem tocar em código. ## Temas base Toda loja nova já nasce com o tema **Vega** ativo. A galeria traz estes temas prontos, que você pode **usar direto (linked)** ou **personalizar (fork)**: > [card] Vega > [card] Orion > [card] Altair > [card] Lyra > [card] Rigel > [card] Sirius > [card] Antares > [!NOTE] > > **Linked** aponta para o tema da galeria e **acompanha as atualizações** do tema base. **Fork** é uma cópia editável e independente — deixa de receber as atualizações da galeria. Ver [Estrutura](/editor/estrutura). > [!NOTE] > > **Personalizar o código** (criar fork ou tema em branco, salvar, publicar e restaurar versões) é uma vantagem do **nível da loja** (template próprio). Usar um tema da galeria como linked está disponível para todas as lojas. ## Como trocar ou personalizar o tema **1. Abra o painel** Vá em **Aparência** no painel da sua loja e abra **Template**. **2. Escolha um tema** Selecione um tema da galeria (fica **linked**) ou clique em **Personalizar código** para criar um fork editável. **3. Edite e publique** As edições ficam em **rascunho**. **Publicar** grava uma versão; publicar exige a página inicial (`templates/index` ou `pages/index`). **4. Aplique na loja** **Aplicar à loja** (no painel) ou **Ativar** (no Studio) coloca a versão publicada no ar. > [!TIP] > > Cada publicação fica no **histórico** (até 50 versões) e pode ser **restaurada**. Pelo menu do template você também pode **baixar** o tema em `.zip` e **importar** um `.zip`. ## Formas de editar > [card] Editor Web (Studio) > > Editor de código integrado ao painel, com árvore de arquivos, realce de sintaxe, abas, busca e **pré-visualização ao vivo**. Nada pra instalar. > [card] [Editor Local (CLI)](/editor/editor-local) > > Edite os arquivos na sua máquina com o VS Code (ou qualquer editor) via `npx allbay-editor`. Sincronização automática com a loja. ## Editar com IA Com o [Editor Local](/editor/editor-local) você pode usar assistentes de IA pra gerar e ajustar componentes por linguagem natural. Conecte a IA ao **MCP desta documentação** (`https://allbay.mintlify.app/mcp`) para ela consultar as regras da AllBay sozinha — o passo a passo está em cada página: > [card] [Claude Code](/editor/ia/claude) > [card] [Cursor](/editor/ia/cursor) > [!NOTE] > > A AllBay usa a sintaxe Liquid de sempre (`{% %}` e `{{ }}`), o que mantém o tooling (realce, formatadores, IA) funcionando sem configuração especial. Há algumas diferenças de comportamento — ver [Sintaxe](/editor/sintaxe). # Páginas Source: https://allbay.mintlify.app/editor/paginas Cada rota da loja mapeia para um arquivo de página do tema. Quando um visitante acessa uma URL, a AllBay identifica o tipo de página, carrega os dados relevantes e renderiza o arquivo correspondente, com as [variáveis globais](/editor/variaveis-globais) mais as variáveis específicas daquela página. ## Mapa de rotas | Rota | Arquivo (Vega) | Variáveis específicas | | - | - | - | | `/` | `pages/index.liquid` | `products`/`packages` (até 100), `sections`, `showcase`, `recent_feedbacks` | | `/products` | `pages/category.liquid` | todos os produtos (até 100), sem `category` | | `/collections/:slug` · `/category/:slug` | `pages/category.liquid` | `category`, `collection`, produtos da categoria (até 50) | | `/products/:slug` · `/package/:slug` | `pages/package.liquid` | `product`/`package` (produto completo) | | `/search` | `pages/search.liquid` | produtos (até 100) — ver [Busca](#busca) | | `/checkout` | `pages/checkout.liquid` | `cart` | | `/order/:id` | `pages/order.liquid` | `order`, `allowed`, `order_feedback`, `chat_delivery` | | `/payment/:id` | `pages/payment.liquid` | `order` (PIX: `pix_code` + `qr_code`) | | `/blog` | `pages/blog.liquid` | `posts` (página 1, 20 posts) | | `/post/:slug` | `pages/post.liquid` | `post` | | `/account` | `pages/account.liquid` (o Vega não tem — cai no 404) | `orders` | | `/account/orders` | `pages/account/orders.liquid` (ou `pages/account`) | `orders` (`{ data, meta }`, 20 por página, `?page=`) | | `/account/affiliate` | `pages/account/affiliate.liquid` (ou `pages/account`) | `orders` | | `/terms` | `pages/terms.liquid` | `terms` (HTML) | | `/pages/:handle` | `pages/:handle.liquid` | página própria do tema: ver [Páginas próprias](/editor/paginas-custom) | | 404 | `pages/not-found.liquid` | — | > [!NOTE] > > Os nomes seguem os [aliases de resolução](/editor/estrutura#resolução-de-páginas-aliases): > a rota de produto aceita `package` ou `product`, coleção aceita `category` ou `collection`, > checkout aceita `checkout` ou `cart`, 404 aceita `not-found` ou `404`. > [!NOTE] > > Os produtos das listas **não são paginados no servidor**: home, `/products` e busca trazem > até 100; a coleção traz até 50, e só as **24 primeiras** categorias vêm com produtos. Para > paginar ou buscar o resto, use `{% load "packages", category_id: category.id, page: query.page %}` > (ver [Tags](/editor/tags#load-dados-dinâmicos)). ## Busca Na rota `/search`, o servidor entrega o catálogo (até 100 produtos) e filtra por `?category_id=` e `?current_package=` (remove esse produto da lista). O filtro de **texto** (`?q=`) é aplicado no navegador pelo tema/SDK. A página não é indexada por buscadores. ## Página não encontrada (404) * Uma rota inexistente renderiza a sua página 404 com **status HTTP 404** (não indexada). * Um produto inexistente também cai na página 404 (`pathname` = `/404`). * Uma coleção inexistente (`/collections/x`) renderiza a página de coleção **vazia**. * Um post inexistente renderiza a página de post sem `post`. Sem página 404 no tema, o visitante recebe um 404 simples da plataforma. ## Pedido e pagamento `/order/:id` e `/payment/:id` **não exigem login**: abrem com a sessão do cliente **ou** com o link do pedido (que traz o token de acesso). Sem acesso, `order` fica vazio e `allowed` é `false` — mostre uma mensagem nesse caso. ```liquid theme={null} {% if allowed %} Pedido {{ order.status }} — {{ order.price_display }} {% else %}

Não foi possível abrir este pedido.

{% endif %} ``` Quando o pagamento já foi aprovado, `/payment/:id` redireciona para `/order/:id`. ## Login é sempre da plataforma A página `/login` **não** é renderizada pelo tema. Ao acessar `/login`, o visitante vai para a tela de login da AllBay e volta logado. Um `pages/login.liquid` no tema é ignorado. A **área do cliente** (`/account*`) é renderizada pelo tema, mas exige login: sem sessão, o visitante é levado ao login. ## Manutenção Não existe página de manutenção separada. Quando a loja está pausada, `store.maintenance` é `true` e o catálogo vem vazio — trate isso no seu layout: ```liquid theme={null} {% if store.maintenance %}

Voltamos em breve.

{% else %} … {% endif %} ``` ## Layouts Há duas formas de envolver as páginas: * **Layout automático:** crie `layouts/base.liquid` com `{{ content_for_layout }}` onde a página deve entrar. Toda página é renderizada dentro dele. * **Layout declarado:** a página começa com `{% layout 'layouts/layout' %}` e o conteúdo dela entra no `{% block %}{% endblock %}` do layout — é o que o Vega usa. Ver [Tags](/editor/tags#layout-e-block). > [!WARNING] > > Se **alguma** página do tema usa `{% layout %}`, toda página que **não** declarar um layout é > entregue sem ``/`` (como fragmento). Em temas com layout declarado, declare o > layout em todas as páginas. # Páginas próprias (custom) Source: https://allbay.mintlify.app/editor/paginas-custom Crie páginas novas na loja, como Sobre, FAQ, landing ou todas as categorias: um arquivo em pages/ vira /pages/nome. Além das páginas da plataforma (home, produto, categoria, carrinho…), o tema pode ter **páginas próprias**. Cada arquivo `pages/.liquid` vira a página `/pages/` da loja. Use para: Sobre, FAQ, política de troca, landing de campanha, página com **todas as categorias**, página de um jogo ou de uma coleção especial, e o que mais o tema precisar. ## Como criar **1. Tenha uma cópia própria do tema** No painel, em **Aparência**, use **Personalizar** no tema. Uma loja que usa o tema direto da galeria não tem onde guardar arquivos novos: sem a cópia, a página não existe. **2. Crie o arquivo em pages/** Por exemplo `pages/sobre.liquid`, pelo editor do painel ou pelo [Editor Local](/editor/editor-local). **3. Publique** A página fica em `https://sua-loja/pages/sobre`. **4. Ponha um link para ela** Ninguém encontra a página sozinho: adicione um link no menu, no rodapé ou num botão do tema. ## Regras do nome | Regra | Certo | Errado | | - | - | - | | Minúsculas, números, `-` e `_`; começa com letra ou número | `politica-de-troca` | `Politica de Troca`, `-sobre` | | Sem ponto no nome | `faq-2025` | `faq.2025` | | Direto em `pages/`, um nível só | `pages/jogos.liquid` | `pages/jogos/roblox.liquid` | | Não usar nome de página da plataforma | `pages/sobre.liquid` | `pages/index.liquid` (ver abaixo) | A URL é **sempre** `/pages/`: | Arquivo | URL | Funciona? | | - | - | - | | `pages/sobre.liquid` | `/pages/sobre` | Sim | | `pages/sobre.liquid` | `/sobre` | Não: 404 | | `pages/a/b.liquid` | `/pages/a/b` | Não: o editor não aceita subpasta, e a rota dá 404 | > [!WARNING] > > Não crie página própria com o nome de uma página da plataforma: `index`, `package`, `product`, > `category`, `collection`, `checkout`, `cart`, `search`, `terms`, `blog`, `post`, `order`, > `payment`, `login`, `account`, `maintenance`, `not-found`, `404`. Esses arquivos já são as > páginas da loja (ver [Páginas](/editor/paginas)). ## O que a página recebe * As [variáveis globais](/editor/variaveis-globais): `store`, `theme`, `config`, `settings`, `customer`, `logged_in`, `pathname`… * **Nenhum dado próprio da rota.** Para produtos, categorias, avaliações ou posts, use [`{% load %}`](/editor/tags#load-dados-dinâmicos) na própria página (até 20 por página). ## Layout Comece a página declarando o layout, como as outras páginas do tema: ```liquid theme={null} {% layout "layouts/layout", page_title: 'Sobre' %} ``` Se o tema usa `{% layout %}` e a página não declara, ela sai sem ``/``, só como fragmento. Ver [Layouts](/editor/paginas#layouts). ## Exemplo: página com todas as categorias `pages/jogos.liquid`: ```liquid theme={null} {% layout "layouts/layout", page_title: 'Todos os jogos' %} {% load "categories", limit: 50 %}

Todos os jogos

{% for category in categories %} {% if category.hide_category != true %} {% if category.image %}{% endif %} {{ category.name }} {% endif %} {% endfor %}
``` E o botão da home: ```liquid theme={null} Ver todos os jogos ``` `load "categories"` traz até 50 categorias principais, com as subcategorias em `sub_categories`. ## Buscadores (SEO) * A página é indexável e tem link canônico para ela mesma. * Ela **não entra** no `sitemap.xml` da loja: os buscadores a encontram pelos links do tema. ## Página deu 404? 1. O tema publicado é uma **cópia própria** e tem o arquivo? O que vale é o **publicado**, não o rascunho. 2. A URL tem o `/pages/`? `/sobre` não existe; o certo é `/pages/sobre`. 3. O nome segue as regras acima (minúsculas, sem ponto, sem subpasta)? # Schema Source: https://allbay.mintlify.app/editor/schema Defina opções editáveis no painel — sem tocar no código do tema. O schema define as opções de personalização que aparecem no painel. Assim o dono da loja ajusta cores, textos e imagens sem editar código. O arquivo é `config/settings_schema.json`. > [!NOTE] > > Os temas **Vega**, **Orion**, **Altair** e **Lyra** (e os forks deles) usam, no painel, o schema > **mantido pela AllBay** para aquele tema. **Rigel**, **Sirius** e **Antares** usam o próprio > `config/settings_schema.json`. ## Estrutura ```json theme={null} { "settings": [ { "title": "Cores", "fields": [ { "key": "primary_color", "label": "Cor primária", "description": "Cor principal da loja", "type": "color", "default": "#5865F2" } ] } ] } ``` * Cada grupo tem `title` (ou `name`) e `fields` (ou `settings`). * Cada campo tem `key` (ou `id`), `label`, `type`, e opcionalmente `description` e `default`. * Limites: 50 grupos, 200 campos, 100 opções por `select`. ## Chaves dos campos A `key` precisa começar com letra e usar só **letras, números e `_`** (até 64 caracteres). > [!WARNING] > > **Hífen não é permitido.** Um campo com `"key": "primary-color"` é **ignorado**. Use > `primary_color`. ## Acessando os valores Os valores ficam no global `config` (e em `settings`), com a mesma chave do campo: | Chave no schema | Acesso no Liquid | | - | - | | `primary_color` | `config.primary_color` | | `hero_image` | `config.hero_image` | ```liquid theme={null} {% if config.hero_image %}{% endif %} ``` Um campo sem valor usa o `default` — desde que o tema tenha o próprio `config/settings_schema.json`. Sem esse arquivo, os valores chegam como foram salvos; use `| default:` no Liquid. Imagens já chegam como URL pronta (ver [Imagens](/editor/imagens)). ## Tipos de campo | Tipo | Guarda | Observação | | - | - | - | | `text` | texto de uma linha | até 5000 caracteres (`max_length` reduz) | | `textarea` | texto | até 20000 caracteres (`max_length` reduz) | | `wysiwyg` | HTML (editor rico) | até 40000 caracteres | | `color` (`color-picker`) | cor | exatamente `#RRGGBB` | | `number` (`range`) | número **inteiro** | aceita `min`/`max` | | `checkbox` (`boolean`) | verdadeiro/falso | | | `select` | uma opção | requer `options` | | `url` | link | `https://…`, `http://…` ou caminho `/…` | | `image` (`image_picker`) | imagem | chega como URL pronta | | `images` | várias imagens | `max_items` (padrão 5, máx. 20) | | `array` | lista de itens | itens com `fields` próprios (ver abaixo) | | `products` (`product`, `packages`) | seleção de produtos | `max_items` (padrão 12, máx. 100) | > [!NOTE] > > `textarea` hoje **não aceita quebras de linha**. Para textos com parágrafos, use `wysiwyg`. ### `array` Cada item tem até 20 campos, dos tipos `text`, `checkbox`, `number`, `select`, `color`, `url`, `image` e `products`. `max_items`: padrão 50, máximo 200. ```json theme={null} { "key": "faq", "label": "Perguntas frequentes", "type": "array", "fields": [ { "key": "question", "label": "Pergunta", "type": "text" }, { "key": "answer", "label": "Resposta", "type": "text" } ] } ``` ```liquid theme={null} {% for item in config.faq %}

{{ item.question }}

{{ item.answer }}

{% endfor %} ``` > [!WARNING] > > Um campo `image` dentro de um item de `array` hoje **não pode ser exibido** no tema. Use > campos `image`/`images` no primeiro nível do schema. ## Exemplo com vários campos ```json theme={null} { "settings": [ { "title": "Cabeçalho", "fields": [ { "key": "logo", "label": "Logo", "type": "image" }, { "key": "fixed_header", "label": "Cabeçalho fixo", "type": "checkbox", "default": true }, { "key": "layout", "label": "Layout", "type": "select", "options": [{ "value": "wide", "label": "Largo" }, { "value": "boxed", "label": "Caixa" }], "default": "wide" } ] }, { "title": "Destaques", "fields": [ { "key": "featured", "label": "Produtos em destaque", "type": "products", "max_items": 4 } ] } ] } ``` ## Validação O servidor valida cada valor pelo tipo: `color` só aceita `#RRGGBB`, `select` só aceita as `options`, `number` respeita `min`/`max`, `url` não aceita `javascript:`. Valores inválidos ou chaves que não existem no schema são **recusados**, com a lista de erros. # Sintaxe Source: https://allbay.mintlify.app/editor/sintaxe A sintaxe Liquid usada nos temas — lógica, saída de variáveis e as diferenças que importam. Os temas da AllBay são renderizados com **Liquid**, usando os delimitadores de sempre: * `{% ... %}` — **lógica** (tags: condicionais, laços, includes). * `{{ ... }}` — **saída** (imprime o valor de uma variável). ## Saída de variáveis ```liquid theme={null}

{{ store.name }}

Moeda: {{ store.currency }}

``` ## Condicionais ```liquid theme={null} {% if store.maintenance %}

Loja em manutenção.

{% elsif logged_in %}

Olá, {{ user.name }}!

{% else %}

Bem-vindo!

{% endif %} {% unless logged_in %} Entrar {% endunless %} ``` Operadores: `==`, `!=`, `>`, `<`, `>=`, `<=`, `and`, `or`, `contains`, `not`. > [!WARNING] > > **O que é "falso" na AllBay é diferente do Liquid tradicional:** `nil`, `false`, > **`0`** e **`""`** (texto vazio) são falsos. Uma **lista vazia `[]` é verdadeira**. > Para testar se uma lista tem itens, use `{% if lista.size > 0 %}`. ## Laços ```liquid theme={null} {% for category in categories %}
  • {{ category.name }}
  • {% endfor %} ``` Variáveis do laço: `forloop.index` (começa em 1), `forloop.index0` (em 0), `forloop.first`, `forloop.last`, `forloop.length`. ## Variáveis locais ```liquid theme={null} {% assign destaque = "Promoção" %} {{ destaque }} {% capture saudacao %}Olá, {{ user.name }}{% endcapture %} {{ saudacao }} ``` ## Filtros Transforme valores com o operador pipe `|`, encadeável: ```liquid theme={null} {{ 29.90 | money }} {{ store.name | upcase | truncate: 20 }} ``` Ver a lista completa em [Filtros](/editor/filtros). ## Componentes e layouts Use `{% render %}` para incluir um componente e um layout para envolver a página: ```liquid theme={null} {% render 'components/navbar' %} ``` Ver [Tags](/editor/tags) e [Estrutura](/editor/estrutura) para os detalhes de componentes, layouts e o carregamento de dados com `{% load %}`. ## Tags e filtros permitidos * Só existem as **tags** e os **filtros** listados em [Tags](/editor/tags) e [Filtros](/editor/filtros). Uma tag ou filtro fora da lista é **erro**: a página não renderiza. * `{% render %}` e `{% include %}` só leem arquivos **do próprio tema**. * Páginas muito pesadas ou lentas para gerar não são exibidas — mantenha laços e `load` enxutos. # Tags Source: https://allbay.mintlify.app/editor/tags Tags de lógica e as tags próprias da AllBay — load, section, render, tailwindcss. Tags ficam entre `{% %}`. Apenas as tags desta página existem — qualquer outra é **erro** e a página não renderiza. ## Controle de fluxo `if`, `elsif`, `else`, `unless`, `case`/`when`, `for`, `tablerow`, `cycle`, `break`, `continue`, `assign`, `capture`, `increment`, `decrement`, `echo`, `liquid`, `comment`, `#` (comentário de linha) e `raw`. Ver exemplos em [Sintaxe](/editor/sintaxe). ## `render`: componentes Inclui um componente, com variáveis próprias: ```liquid theme={null} {% render 'components/product-card', package: p %} {% render 'product-card', package: p %} ``` Com um nome simples, a busca é: raiz do tema → `snippets/` → `components/`. O componente enxerga as variáveis globais, os resultados de `{% load %}` e os parâmetros que você passar. Variáveis criadas na página com `assign`/`capture` **não** chegam ao componente — passe como parâmetro. `{% include %}` também existe e compartilha todas as variáveis da página. ## `layout` e `block` A página declara o layout na primeira linha; o resto dela entra no `{% block %}` do layout. Parâmetros depois da vírgula viram variáveis dentro do layout: ```liquid layouts/layout.liquid theme={null} {{ page_title }} · {{ store.name }}
    {% block %}{% endblock %}
    ``` ```liquid pages/index.liquid theme={null} {% layout "layouts/layout", page_title: 'Home' %}

    Bem-vindo

    ``` Blocos com nome (`{% block conteudo %}`) só funcionam se o layout declarar um bloco com o mesmo nome. Ver também o layout automático `layouts/base.liquid` em [Páginas](/editor/paginas#layouts). ## `section`: blocos de layout Renderiza `sections/`. O nome usa letras minúsculas, números, `_` e `-`. Profundidade máxima de aninhamento: 6. ```liquid theme={null} {% section 'hero' %} ``` Se o tema não tiver o arquivo, a AllBay usa a seção da plataforma de mesmo nome, quando existe: `hero`, `product-grid`, `benefits`, `announcement`, `category_carousel`, `category_with_products`. Uma seção que não existe ou que falha **não aparece** (sem erro). ## `tailwindcss` Insere o `` do CSS do Tailwind gerado a partir do `tailwind.config.json` do tema: ```liquid theme={null} {% tailwindcss %} ``` ## `load`: dados dinâmicos Carrega dados da loja direto no template. O resultado vira uma variável com o nome da entidade, ou com o nome dado por `as`: ```liquid theme={null} {% load "products", limit: 8, category_id: "1538117695638261760" %} {% for p in products %} {{ p.name }} {% endfor %} {% load "product" as produto, slug: "plano-vip" %} {% if produto.name %}{{ produto.name }}{% endif %} ``` > [!WARNING] > > * O `as` vem **logo depois do nome da entidade**: `{% load "product" as produto, slug: "x" %}`. > * **Ids são texto**: escreva `category_id: "123..."` (entre aspas). Um número faz o `load` falhar. > * Os parâmetros são separados por vírgula — um texto com vírgula não funciona como valor. Comportamento: * Se o `load` falhar (parâmetro inválido, tempo esgotado), a variável **não é alterada**. * `product` e `post` **não encontrados** viram uma lista vazia `[]`, que é verdadeira em `{% if %}` — teste um campo: `{% if produto.name %}`. * Até **20** `load` por página, contando o layout declarado com `{% layout %}` (só o `layouts/base.liquid` tem os seus próprios 20). Os excedentes são ignorados. * O resultado vale na página, no layout, em `{% section %}` e dentro de `{% render %}`. ### Entidades disponíveis | Entidade | Parâmetros | Retorna | | - | - | - | | `products` | `limit` (padrão 12, máx. 50), `page`, `category_id` | lista de produtos **com imagens em hash** (ver [Imagens](/editor/imagens)) | | `packages` | `limit`, `page`, `category_id`, `id` (lista de ids) | `{ data, size, total, meta }` com produtos no formato de card, imagens prontas; `id:` traz uma lista em destaque | | `product` | `slug` | um produto pelo slug | | `categories` | `limit` (padrão 20, máx. 50 categorias principais) | árvore de categorias | | `product_reviews` | `slug`, `limit` (padrão 10, máx. 50) | `{ summary: { total, average, distribution }, items }` | | `package_feedbacks` | `package_id`, `limit` (padrão e máx. 100) | cria `feedback_settings`, `package_feedback_summary` e `package_feedbacks` | | `feedbacks` | `limit` (padrão 10, máx. 50) | cria `feedback_settings` e `feedbacks` | | `posts` | `limit` (padrão 20, máx. 50), `page` | `{ data, meta }` do blog | | `post` | `slug` | um post pelo slug | | `gateways` | — | métodos de pagamento ativos (`{ gateway, method }`) | | `variables` | `limit` (padrão e máx. 100) | campos de checkout da loja | | `checkout_fields` | `limit` | alias de `variables` | > [!NOTE] > > Em `packages`, `size` e `total` contam os itens **desta página**; o total do catálogo está > em `meta.total`. `package_feedbacks` e `feedbacks` criam variáveis com nomes fixos e > ignoram o `as`. > [!NOTE] > > **`orders`** (pedidos do cliente) não é carregado por `load` — é preenchido pela AllBay > nas páginas `/account/*`. Um `{% load "orders" %}` não altera esse valor. # Variáveis Globais Source: https://allbay.mintlify.app/editor/variaveis-globais Objetos disponíveis nas páginas do tema — e em quais páginas cada um tem dados. Estas variáveis existem em **todas** as páginas. Algumas só têm dados em certas rotas (indicado em cada uma); cada página também recebe variáveis próprias (ver [Páginas](/editor/paginas)). > [!NOTE] > > Campos sem valor costumam vir **ausentes** ou `null`. Teste antes de usar: > `{% if store.custom_domain %}…{% endif %}`. ## `store`: a loja ```liquid theme={null} {{ store.name }} · {{ store.currency }} ``` | Campo | Tipo | Descrição | | - | - | - | | `name` | string | Nome da loja | | `currency` | string | Moeda (`BRL`, `USD`, `EUR`) | | `subdomain` | string? | Subdomínio | | `custom_domain` | string? | Domínio próprio — só quando está **ativo** e o nível da loja inclui domínio próprio | | `canonical_origin` | string? | Endereço principal da loja | | `type` | string | Sempre `STANDALONE` | | `maintenance` | bool | Loja pausada | | `auth` / `show_login` | bool | Login habilitado | | `require_document` | bool | Exige documento no checkout | | `require_address` | bool | Exige endereço | | `require_discord` | bool | Exige Discord | | `phone_mode` | string | `DISABLED` / `OPTIONAL` / `REQUIRED` (`phone_mode_id`: 0/1/2) | | `terms` | string? | Termos da loja (HTML) | | `theme` | objeto | O mesmo objeto de [`theme`](#theme-aparência) | > [!NOTE] > > Existe também `shop` (`name`, `slug`, `id`, `logo_url`, `banner_url`). Prefira **`store`**, > que traz os dados completos. ## `theme`: aparência | Campo | Tipo | | - | - | | `primary_color`, `secondary_color`, `accent_color`, `buttons_color` | `#rrggbb` (sempre presentes) | | `theme_mode` | `light` / `dark` | | `logo`, `banner`, `favicon` | URL de imagem pronta (ver [Imagens](/editor/imagens)) | | `description` | string? | | `background_image`, `hero_image` | URL de imagem pronta (ausente se não configurada) | | `floating_categories`, `show_search`, `show_sales` | bool | | `fixed_aspect_ratio`, `contact_link` | — | Campos que o dono não configurou ficam **ausentes**. > [!WARNING] > > `theme.logo` vem em tamanho pequeno (64 px). Para mostrar o logo grande, use um campo de > imagem do [schema](/editor/schema). ## `config` e `settings` `config` junta, nesta ordem (o seguinte vence o anterior): a paleta do tema, as seções da home e os valores do [schema](/editor/schema). A chave em `config` é **exatamente** a chave do campo no schema — use só letras, números e `_` (`primary_color`). Quando o tema tem o próprio `config/settings_schema.json`, `settings` traz os valores já validados: chaves não declaradas são descartadas e os `default` preenchidos. Sem esse arquivo (como no Vega), `settings` traz os valores salvos como estão — sem `default`. Os termos da loja também ficam em `settings.terms_content` quando o tema não define esse campo. ```liquid theme={null} {{ config.headline }} {% if config.hero_image %}{% endif %} ``` Imagens do schema já chegam como **URL pronta** — não passe por `cdn_url`. ## `user`, `customer`, `logged_in` | Global | Tipo | Descrição | | - | - | - | | `logged_in` | bool | Cliente autenticado? | | `customer` | objeto? | `id`, `name`, `avatar_url`, `initial`, `email`?, `discord_id`? | | `user` | objeto? | O mesmo que `customer`, mais `avatar` (= `avatar_url`) | `user`/`customer` são `null` sem login; `email` e `discord_id` ficam ausentes quando vazios. ```liquid theme={null} {% if logged_in %}Olá, {{ user.name }}{% else %}Entrar{% endif %} ``` ## `categories` e `category` `categories` é a árvore de categorias (2 níveis); `category` é a categoria atual na página de coleção. | Campo | Descrição | | - | - | | `id`, `name`, `slug`, `emoji`, `parent_id` | Identificação | | `image`, `banner`, `image_url`, `banner_url`, `icon_url` | Imagens prontas (ver [Imagens](/editor/imagens)) | | `product_count` / `packages_count` | Quantidade de produtos | | `sub_categories[]` | Subcategorias | | `products[]` | Produtos (cards) — preenchido só nas **24 primeiras** categorias, até 50 cada | | `hide_category`, `hide_subcategory`, `display_limit` | Opções de exibição | > [!NOTE] > > Se houver produtos sem categoria, aparece no fim uma categoria **"Todos"** (`slug: "todos"`). ## Produtos: `products`, `packages`, `product` * `products` — **lista** de produtos (cards). * `packages` — **envelope** `{ data: [...], size, total }` com a mesma lista. * `product` / `package` — o produto da página de produto (mesmo objeto). Com dados em: home, `/products` e busca (até **100** produtos) e coleção (até **50**), sem paginação no servidor. **Card de produto** (`products`, `packages.data`, `category.products`): | Campo | Tipo | | | - | - | - | | `id`, `name`, `slug` | string | | | `description` | resumo curto | | | `price`, `comparison_price` | número (em reais, para \` | money\`) | | `pricing` | `{ price, min, compare_at, percent_discount }` | | | `stock` | `{ quantity, available, min_amount }` (`quantity` é `null` se ilimitado) | | | `available`, `stock_count`, `stock_unlimited` | estoque simplificado | | | `image`, `banner`, `image_url`, `banner_url` | imagem pronta | | | `has_variants`, `is_auto_delivery`, `sales_count` | — | | | `feedback_stats` | `{ average, total }` ou `null` | | | `category_ids` | categorias do produto | | **Produto completo** (`product` / `package`, só na página de produto) — tudo do card, mais: | Campo | Tipo | | - | - | | `description`, `short_description` | HTML / texto | | `gallery[]`, `images[]` | imagens (podem conter **vídeo**) | | `variants[]`, `default_variant` | variações | | `variables[]` (alias `fields[]`) | campos de checkout do produto | | `auto_deliver` | bool | ## `socials` e `gateways` * `socials` — todas as redes, `null` quando não configurada: `instagram`, `discord`, `youtube`, `twitter`, `facebook`, `tiktok`, `whatsapp`, `telegram`. * `gateways` — métodos de pagamento **disponíveis agora** na loja. Campos: `name` (`PIX` ou `CREDITCARD`), `display`, `method`, `provider`, `fee`, `fee_percent`, `fee_fixed`, `is_percentage_fee`, `require_document`, `require_address`, `require_phone`, `max_installments`. ```liquid theme={null} {% assign pix = gateways | where: "name", "PIX" | first %} ``` ## Rotas específicas | Global | Onde tem dados | | - | - | | `sections`, `showcase`, `recent_feedbacks` | home | | `collection` (`{ handle }`), `active_filters` | coleção | | `cart` (`{ items, items_count, total }`, vazio no servidor; o SDK preenche no navegador) | `/checkout` | | `order`, `allowed`, `order_feedback`, `chat_delivery` | pedido e pagamento | | `orders` (`{ data, meta }`) | `/account/*` | | `posts` (`{ data, meta }`) | `/blog` | | `post` | `/post/:slug` | | `terms` (HTML ou `null`) | todas | **`order`:** `status` (`APPROVED`, `PENDING`, `REJECTED`, `CANCELED`, `REFUNDED`, `CHARGEDBACK`), `price`, `price_display`, `gateway`, `gateway_display`, `pix_code`, `qr_code` (imagem SVG em data-URI), `packages[]`, `deliveries[]`, `client_name`, `client_email`, `promo_code`, `created_at`, `access_token`. **`posts`:** `{ data, meta }`, com `meta` = `total`, `per_page`, `current_page`, `last_page`, `first_page`, `next_page_url`, `previous_page_url`. **`post`:** `title`, `slug`, `content` (HTML), `image`, `excerpt`, `author`, `reading_time`, `published_at` (data por extenso, pt-BR) e `published_at_iso`. ## Requisição * `query` — parâmetros da URL (`query.page`, …; o primeiro valor de cada chave). * `pathname` — o caminho **canônico** da página (ex.: `/collections/x` mesmo que o visitante tenha aberto `/category/x`; `/404` na página de erro). ## Scripts e estilos da plataforma O SDK da AllBay é **injetado automaticamente** em toda página. Se quiser controlar a posição: ```liquid theme={null} ``` Para o CSS do Tailwind do tema, use a tag [`{% tailwindcss %}`](/editor/tags#tailwindcss).