Exemplos práticos

Os exemplos abaixo usam dados disponíveis no tema e preservam a liberdade de apresentação.

Posicionar o reCAPTCHA v2 mostra o ponto de montagem nos formulários. Mostrar “Está acabando” usa uma condição de estoque no Liquid.

Uma vitrine completa

Criar uma vitrine reúne template JSON, section, component e CSS. Os arquivos mostrados nesse tutorial também são usados pelos testes automatizados do projeto.

Uma seção de banner

Acrescente a instância abaixo ao array sections da Home, preservando as outras seções. id e type aceitam letras minúsculas ASCII, números e os separadores _ ou - entre grupos alfanuméricos. O id deve ser único no template.

{
  "sections": [
    {
      "id": "banner-promo",
      "type": "banner-promocional"
    }
  ]
}

Crie sections/banner-promocional.liquid com o mesmo type declarado:

<section id="{{ section.id }}" aria-label="Banner promocional">
  <h2>Conheça nossa coleção</h2>
  <img src="{{ 'images/banner.webp' | asset_url }}" alt="" width="1536" height="1024" loading="lazy" decoding="async">
</section>

Este exemplo usa a imagem existente no Aura. Em outro tema, informe o caminho real de uma imagem do bundle em asset_url e ajuste suas dimensões. Textos ficam no HTML e a apresentação pode ser definida livremente em assets/theme.css. No editor, a IA cria a seção no rascunho; ela entra na loja após a publicação.

Benefícios na compra

Para busca e categoria, veja Consultar produtos pelo Liquid, com estoque filtrado no servidor e paginação sobre o mesmo resultado.

Exibir metas e créditos mostra um exemplo Liquid executado com dados fictícios nos testes.

Categorias no menu

Use o exemplo em uma section ou passe catalog explicitamente ao component do menu:

<nav aria-label="Categorias">
  {% for category in catalog.categories %}
    <a href="{{ category.url | storefront_url }}">{{ category.name }}</a>
  {% endfor %}
</nav>

A estrutura visual é livre. Para subcategorias, percorra category.children.

Categorias com imagem de capa

category.image é a capa cadastrada pelo lojista para representar a categoria em vitrines; pode ser null. Defina a alternativa no próprio tema, como a inicial do nome:

<div class="category-cards">
  {% for category in catalog.categories limit: 6 %}
    <a href="{{ category.url | storefront_url }}">
      {% if category.image %}
        <img src="{{ category.image.url }}" alt="" loading="lazy"
          {% if category.image.width and category.image.height %}width="{{ category.image.width }}" height="{{ category.image.height }}"{% endif %}>
      {% else %}
        <span aria-hidden="true">{{ category.name | slice: 0, 1 }}</span>
      {% endif %}
      <span>{{ category.name }}</span>
    </a>
  {% endfor %}
</div>

Na página da categoria, category.banner é o banner largo cadastrado para o topo da página. Prefira category.banner.originalUrl, pois url é a variação média:

{% if category.banner %}
  <figure class="category-banner">
    <img src="{{ category.banner.originalUrl }}" alt="">
  </figure>
{% endif %}

Em product.categories, image e banner são sempre null; localize a categoria pelo id em catalog.categories quando precisar da imagem.

Logo com alternativa de texto

<a href="{{ '/' | storefront_url }}">
  {% if shop.logo %}
    <img src="{{ shop.logo.url }}" alt="{{ shop.name }}">
  {% else %}
    <span>{{ shop.name }}</span>
  {% endif %}
</a>

shop.logo é a identidade global da loja. Para imagens próprias do tema, consulte asset_url.

Páginas institucionais no rodapé

<nav aria-label="Informações da loja">
  {% for item in content.pages %}
    <a href="{{ '/pagina/' | append: item.slug | storefront_url }}">{{ item.title }}</a>
  {% endfor %}
</nav>

Ao colocar esse trecho em um component, passe content: content na chamada render.

Paginação

{% if listing.pagination.hasNextPage %}
  <a href="{{ listing.pagination.nextUrl }}">Próxima página</a>
{% endif %}

URLs de paginação já vêm prontas, incluindo filtros e namespace da prévia. Não monte a query novamente nem aplique o prefixo duas vezes.

Categoria e busca com filtros compactos

Os temas oficiais oferecem uma barra com Filtrar, quantidade e ordenação. As opções começam recolhidas; os filtros aplicados e a ação de limpeza continuam visíveis abaixo da barra. O painel abre no lugar, com rolagem própria, e os campos ficam em uma coluna no celular. A ordenação pode ocupar uma segunda linha.

A interação e a preservação da consulta estão descritas na referência de categoria e busca. Essa é a apresentação dos temas oficiais, não uma exigência para outros layouts.

Ao compor sua listagem, mantenha os filtros ativos fora do elemento recolhido. Este trecho ilustra a remoção com a URL fornecida pelo servidor:

{% if listing.activeFilters.size > 0 %}
  <nav aria-label="Filtros ativos">
    {% for filter in listing.activeFilters %}
      <a href="{{ filter.removeUrl }}">Remover {{ filter.label }}</a>
    {% endfor %}
    <a href="{{ listing.clearFiltersUrl }}">Limpar filtros</a>
  </nav>
{% endif %}

Na prévia, confira categoria e busca: abra e feche pelo acionador, use Tab e Escape, aplique filtros, altere a ordenação, avance a página e remova um filtro. Repita com lista vazia e no celular. A busca deve conservar o termo e as URLs precisam permanecer na mesma sessão de prévia. Para lojas instaladas, siga o fluxo de revisão e publicação; atualizar o bundle oficial não reescreve uma revisão já publicada.

Informações adicionais do produto

Marca, modelo, garantia e entrega estão em product.specifications, com os títulos personalizados no painel. Use este trecho na section do produto:

{% if product.specifications.size > 0 %}
  <dl>
    {% for specification in product.specifications %}
      <div>
        <dt>{{ specification.label }}</dt>
        <dd>{{ specification.value }}</dd>
      </div>
    {% endfor %}
  </dl>
{% endif %}

A lista já omite campos vazios. O Liquid escapa títulos e valores; não use raw. Entrega é um texto informativo do produto, e a cotação do frete continua por CEP. A apresentação entra na loja após publicar a revisão do tema.

Quando a loja exige login para preços, use product.priceVisible e os valores fornecidos pelo servidor. A sessão válida libera os preços nas páginas públicas; a prévia permanece sem autenticação de comprador. Não tente autorizar preços usando dados fornecidos pelo tema.

Pagamento com PicPay

Na confirmação autorizada do pedido, o mesmo runtime oferece a Carteira PicPay quando o cadastro da loja está habilitado. O tema pode posicionar a região do link com data-payment-wallet; sem ela, o runtime cria o container.

{% if confirmation.orderId %}
<section data-payment-pix data-payment-order="{{ confirmation.orderId | escape }}">
  <p data-payment-message role="status" aria-live="polite"></p>
  <form data-payment-form hidden>
    <fieldset data-payment-options><legend>Forma de pagamento</legend></fieldset>
    <button data-payment-start type="submit" disabled>Continuar</button>
  </form>
  <p data-payment-total></p>
  <div data-payment-wallet hidden></div>
  <div data-payment-details hidden>
    <label>Código Pix <textarea data-payment-code readonly></textarea></label>
  </div>
  <button data-payment-check type="button" hidden>Consultar pagamento</button>
</section>
{% endif %}

O link abre o checkout PicPay em outra aba e esta página acompanha o resultado. Não é um código Pix Copia e Cola. Não coloque tokens ou URLs fixas de cobrança no Liquid, nem confirme o pedido por retorno do navegador. Prévia não cria pagamentos. Consulte o contrato do runtime para os demais métodos e o fluxo de publicação para aplicar CSS.