Vitrines de produtos

Use este guia quando uma seção ou componente global precisar carregar produtos por tag e exibi-los com o Product Block selecionado pela loja.

A Skill de Componentes Customizados, distribuída separadamente, pode auxiliar na criação e revisão de vitrines. O contrato deste guia continua sendo a referência para a implementação.

Configuração, produtos e cards

Estes valores têm funções diferentes:

Valor	Função
component_configs	Configuração da própria seção ou componente global.
product_block_config	Configuração do Product Block selecionado pela loja.
products	Lista de produtos carregada pela tag Liquid.
product	Um produto individual da lista, usado para renderizar um card.

product_block_config contém as configurações que o lojista definiu para o Product Block selecionado. Ele não busca produtos e não é um produto. Preserve component_configs para ler a configuração da sua seção e passe product_block_config somente ao renderizar o card.

Carregar produtos por tag

Use {% load_products %} com uma tag preenchida. A lista resultante fica disponível em products.

{% load_products tag: content.tag_name %}

Quando a vitrine precisar limitar a quantidade carregada, informe per_page:

{% load_products tag: content.tag_name per_page: 10 %}

Não crie o container da vitrine antes de confirmar que a tag existe e que há produtos. O carregamento não define ordenação, filtros adicionais nem interação em JavaScript.

Renderizar o Product Block selecionado

Para cada produto, renderize o Product Block da loja e passe sua configuração no parâmetro component_configs:

{% render 'partials/components/product_block',
  product: product,
  mobile: mobile,
  component_configs: product_block_config
%}

Essa chamada reutiliza o Product Block selecionado para toda a loja e respeita suas opções. Não copie esse markup quando a intenção for reutilizar o card global. Se a seção precisar de um card exclusivo, crie um auxiliar da própria seção e use {% partial 'card_produto', product: product, settings: component_configs.settings %} em vez de render.

Contextos disponíveis

Contexto	Configuração do Product Block	Produto individual	Como montar uma vitrine
Seções de home, página, produto e categoria	product_block_config	Apenas quando já existir no contexto	Use {% load_products %} e percorra products.
Componente global	product_block_config	Não inicialmente	Use {% load_products %} e percorra products.
Arquivo do tipo product_block	Recebida em component_configs	product	É renderizado por uma seção, lista ou vitrine.

Em uma seção de produto, product representa o produto da página atual. Para uma vitrine com vários cards, carregue a lista por tag da mesma forma.

Vitrine com tag estática

Uma seção com conteúdo externo static recebe automaticamente a tag efetiva em content.tag_name quando é adicionada.

{% assign content = component_configs.content %}

{% if content.tag_name != blank %}
  {% load_products tag: content.tag_name per_page: 10 %}

  {% if products.size > 0 %}
    <section class="vitrine-produtos">
      {% if content.title != blank %}
        <h2>{{ content.title }}</h2>
      {% endif %}

      <div class="vitrine-produtos__lista">
        {% for product in products %}
          {% render 'partials/components/product_block', product: product, mobile: mobile, component_configs: product_block_config %}
        {% endfor %}
      </div>
    </section>
  {% endif %}
{% endif %}

Abas com tags dinâmicas

Em conteúdo externo dynamic, cada item possui sua própria tag em item.tag_name. Carregue e renderize os produtos dentro do loop de cada item.

{% for item in component_configs.content.items %}
  {% if item.tag_name != blank %}
    {% load_products tag: item.tag_name per_page: 10 %}

    {% if products.size > 0 %}
      <section class="aba-produtos" data-product-tag="{{ item.tag_name }}">
        <h2>{{ item.title }}</h2>

        <div class="aba-produtos__lista">
          {% for product in products %}
            {% render 'partials/components/product_block', product: product, mobile: mobile, component_configs: product_block_config %}
          {% endfor %}
        </div>
      </section>
    {% endif %}
  {% endif %}
{% endfor %}

Veja como gerar as tags em Schema, os schemas completos em Exemplos e o contrato do card em Bloco de produto.