Programando com Liquid

Liquid é a linguagem de templates que combina seu HTML com dados da loja. A LojaVirtual usa LiquidJS com filtros e contratos próprios. Objetos de outras plataformas não ficam disponíveis automaticamente aqui.

Exibir valores e aplicar filtros

{{ ... }} escreve um valor; | aplica um filtro. Estes exemplos usam objetos disponíveis na referência:

<h1>{{ shop.name }}</h1>
<span>{{ product.price | money }}</span>

Use a expressão de preço somente quando product existir naquele contexto e o preço estiver disponível. O engine escapa a saída HTML por padrão. Não aplique raw a textos arbitrários de produtos, nomes ou dados enviados por visitantes.

Condições e valores ausentes

{% ... %} executa uma instrução. Não assuma que todos os produtos possuem imagem ou preço público:

{% if product.priceVisible and product.price %}
  <span>{{ product.price | money }}</span>
{% else %}
  <span>Consulte as condições deste produto</span>
{% endif %}

Em Liquid, uma string vazia ou um array vazio não deve ser tratado como false. Para listas, verifique size ou use o ramo else do for.

Repetição e componentes

{% for product in page.products %}
  {% render 'product_card', product: product %}
{% else %}
  <p>Nenhum produto disponível.</p>
{% endfor %}

Esse exemplo é para a Home e exige components/product_card.liquid. Para vitrines declaradas em dataSources, os itens ficam em section.data.products.items. Para categoria e busca, consulte listing.

Variáveis locais

Para selecionar produtos antes da paginação, use a tag query_products conforme o exemplo de consulta pelo Liquid. Um if dentro do loop apenas esconde o card já consultado: não recalcula totais nem completa a página. dataSources continua disponível para declarar vitrines pelo template JSON.

{% assign titulo = 'Conheça nossos produtos' %}
<h2>{{ titulo }}</h2>

Variáveis locais organizam a apresentação. Preços, descontos, estoque e autorização continuam sendo calculados pela plataforma.

Na página de cadastro, o tema pode omitir campos como telefone e sexo. O servidor aceita sua ausência mesmo quando eles aparecem como habilitados no painel; campos que o formulário enviar continuam sujeitos à validação. Consulte o contrato da conta do comprador.

HTML editorial

Alguns campos têm uma flag que informa que o HTML já foi sanitizado, como product.descriptionIsHtml e page.contentIsHtml. Só nesses contratos use a saída sem escape para o campo correspondente. Veja Produto e página institucional.

SEO cadastrado no painel

A descrição e as palavras-chave cadastradas no painel chegam em shop.seo. O renderer monta as tags no HTML inicial e aplica a precedência da página em page.seo, inclusive em temas que ainda não incluíam essas tags. Não é necessário inserir scripts nem duplicar o cadastro nos arquivos do tema.

Veja o contrato de SEO no HTML para canonical, Open Graph, Twitter Cards e páginas que não devem ser indexadas.

Próximos passos

Consulte os filtros da LojaVirtual e o exemplo executável de vitrine. Para sintaxe adicional, use a documentação do LiquidJS; a disponibilidade na LojaVirtual depende também da validação e da política de execução do tema.