Tema, layouts e navegação

A aparência de cada loja da Venddor é dado, não código: cores, fontes, o desenho de cada página (quais blocos aparecem e em que ordem) e os menus são cadastrados no painel e lidos pelo front-end por rotas públicas. Um front-end headless usa estas rotas para pintar a loja do jeito que o lojista configurou, sem hospedar tema algum.

São todas rotas de leitura, públicas e sem login, que respondem Cache-Control: no-store (exceto o ícone, que tem cache de 5 minutos). Quem edita tudo isto é o painel do lojista, em rotas próprias.

Como funciona

1. Leia o tema

   Tema e variáveis de CSS devolve cores, fontes e medidas. A rota theme/css já vem pronta para virar :root { --color-primary: ... }.

2. Leia o layout da página

   Para cada página, chame Layout da página com o identificador da página (categories.view, products.view...). A resposta é uma árvore: contêineres, linhas, colunas e blocos.

3. Leia os blocos compartilhados e os menus

   Cabeçalho, rodapé e painel superior vêm de shared-layout, e os menus de Navegação.

4. Prévia de edição (opcional)

   O editor visual usa as rotas de prévia para mostrar o rascunho antes de publicar.

Conceitos-chave

Dispatch

Dispatch é o nome interno de uma página: index.index (home), categories.view, products.view e products.list, search.view, checkout.cart, auth.login, auth.register, vendors.view, vendors.profile, blog.view, blog.post. A lista exata depende da loja; um dispatch sem layout próprio usa o layout default (catch-all).

Contêiner, linha, coluna, bloco

Um layout avançado é uma grade. Cada página tem contêineres por posição (top_panel, header, content, footer); cada contêiner tem linhas, cada linha tem colunas com largura numa grade de 12 colunas por tamanho de tela (width_desktop, width_tablet, width_mobile), e cada coluna tem blocos (block_type: breadcrumbs, main_content, banners, listas de produtos...). main_content é o lugar onde o front-end encaixa o conteúdo real da página (produto, categoria...).

Tema ativo e estilo

A loja pode ter vários temas instalados, mas só um está ativo. As cores e a tipografia devolvidas já vêm do estilo ativo desse tema. O campo active_theme_slug identifica o tema para quem usa componentes específicos por tema.

Rotas

Erros comuns

• Esperar 404 para um dispatch desconhecido. page-layout/{dispatch} devolve o layout catch-all; só responde 204 quando a loja não tem layout algum.
• Tratar 204 como erro. É a resposta normal de "nada configurado": o corpo vem vazio, então não chame .json() sem checar o status.
• Usar o motor errado. Se rendering_engine for theme_builder, page-layout pode estar desatualizado. Confira o campo em Aparência.
• Cachear o layout por muito tempo. As rotas respondem no-store porque o lojista pode publicar a qualquer momento. Prefira revalidar curto.
• Passar um id inválido em navigation-menu/{id}. Um valor que não é UUID responde 500, não 400.

Próximos passos