Os novos Themes (baseados em seções e blocos) compõem as páginas da loja a partir de seções e blocos que os usuários podem reorganizar a partir do Brand Editor, em vez de estarem fixadas em templates .tpl estáticos. Esse modelo desacopla o conteúdo da estrutura do código: o JSON template define o que é exibido, o schema define o que o usuário pode editar, e os arquivos .tpl definem como é renderizado.
Conceitos-chave
Section
Uma section é um arquivo .tpl que renderiza como uma unidade de largura total dentro de uma página. Cada section declara ao final um bloco {% schema %} com os settings que o usuário pode configurar, os tipos de bloco que aceita e os presets disponíveis no editor.
As sections ficam em sections/. As que têm o prefixo main- (por exemplo, main-product.tpl, main-cart.tpl) representam o conteúdo principal de um tipo de página específico e não são reutilizáveis entre páginas.
Block
Um block é um componente reutilizável usado dentro de uma section. Também tem seu próprio {% schema %} com settings, blocos filho aceitos e presets. Os usuários podem adicionar, remover e reordenar blocos dentro de uma section a partir do Brand Editor.
Os blocks ficam em blocks/ e se dividem em duas categorias:
- Genéricos (
heading.tpl,text.tpl,image.tpl,button.tpl,group.tpl, …) — podem ser usados em qualquer section que os aceite. - Específicos de uma section (
slide.tpl,banner.tpl,product-info.tpl,header-logo.tpl, …) — estão vinculados a uma section específica.
Snippet
Um snippet é um partial sem schema. Os snippets gerenciam a lógica de experiência de compra — carrinho, pagamentos, envios, formulários, variações de produto, filtros — e são reutilizáveis, mas não editáveis a partir do Brand Editor.
Os snippets ficam em snippets/ e são incluídos com:
{%include snippets/cart/cart-totals.tpl %}Opcionalmente pode-se passar um objeto de contexto:
{% include snippets/notification.tpl with { type: add_to_cart } %}JSON template
Um JSON template fica em templates/ (por exemplo, templates/pages/home.json ou templates/layout/header.json). É o blueprint de uma página ou região de layout: quais sections aparecem, em que ordem, com quais settings, e quais blocos contêm. O usuário pode personalizá-lo a partir do editor sem tocar no código.
Há dois tipos:
| Tipo | Localização | Renderizado por |
|---|---|---|
| Page templates | templates/pages/*.json | {{ page_template_content }} dentro de <main> |
| Layout templates | templates/layout/header.json, templates/layout/footer.json |
|
Schema
O schema é o bloco JSON ao final de cada section e block (entre {% schema %} e {% endschema %}). É o que impulsiona a UI do editor: tipos de input, valores padrão, visibilidade condicional, presets e quais blocos cada section ou block aceita.
É a peça de maior impacto em um novo Theme (baseado em seções e blocos): a experiência de edição que o usuário recebe depende diretamente de quão rico e bem tipado estiver o schema.
Fluxo de renderização
templates/pages/<página>.json
└── declara quais sections aparecem e seus settings
└── sections/<tipo>.tpl lê section.settings.* e section.blocks
└── blocks/<tipo>.tpl lê block.settings.* (e opcionalmente block.blocks)
└── pode incluir snippets/<...>.tpl para lógica de compra
layouts/layout.tpl envolve tudo:
<head> → fontes, CSS crítico, tokens de estilo
<body>
{% layout_template 'header' %} ← templates/layout/header.json
<main>{{ page_template_content }}</main> ← templates/pages/<página>.json
{% layout_template 'footer' %} ← templates/layout/footer.json
modais, notificações, scripts
Em síntese: o JSON template é o blueprint, os arquivos .tpl de sections e blocks são os renderers, o schema determina o que o usuário pode editar, e os snippets gerenciam a lógica de experiência de compra que não precisa ser editável.
Artigos desta série
- Estrutura de pastas — árvore de pastas completa e detalhe por pasta.
- JSON templates — estrutura do arquivo JSON, page templates e layout templates.
- Sections e Blocks — anatomia de arquivos
.tpl, schema, iteração de blocos e aninhamento. - Schema reference — tipos de setting, global settings e traduções.
- Integração com apps de plataforma — Nube SDK slots e atributos
data-store.