Skip to content

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:

liquid
<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:

liquid
{% 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 ​

liquid
{% 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.

liquid
{% 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.

Artes do banner padrão ​

Os vinte temas oficiais têm título, subtítulo e chamada incorporados à imagem, com versões próprias para computador e celular. O banner não tem texto em HTML: para mudar a frase desenhada, substitua a arte. O primeiro slide da Home descreve a mensagem em alt:

json
{
  "id": "slide-1",
  "image": "images/banner.webp",
  "mobileImage": "images/banner-mobile.webp",
  "url": "/busca",
  "alt": "Seu espaço. Seu jeito. Design para viver bem."
}

O <picture> seleciona mobile até 767 px e mantém a proporção natural das artes, sem recortar palavras. A imagem inteira é o link para /busca. Texto alternativo e nome acessível vêm de alt; no banner inicial, o H1 visualmente oculto mantém o nome da loja.

Na criação da loja, a IA gera um banner novo com a mensagem escrita na imagem e a plataforma preenche alt. Revisões anteriores que exibiam título, subtítulo e botão em HTML (slideText) continuam funcionando como foram publicadas.

Nexo e Vela usam settings.title, subtitle, button_label e url na seção editorial; Orbe usa esses campos em collage, junto às opções de categorias. Os textos também ficam vazios no padrão, e a imagem inteira recebe o link. URL vazia remove o link. Orbe preserva suas categorias e Vela permanece depois dos produtos. As mudanças ficam no rascunho até a publicação; lojas existentes não são atualizadas automaticamente.

Tarja editável por JSON ​

Nos 20 temas oficiais atualizados, components/announcement.liquid desenha a faixa acima do cabeçalho em todas as páginas. A mensagem, o link e o alinhamento ficam em editor.json, dentro de shared.header.settings. No editor visual, selecione Cabeçalho → Tarja, ajuste e aplique para conferir a prévia.

Para editar o arquivo, mescle estes valores com os demais campos já existentes em shared.header.settings; preserve fields, os outros valores e o restante do arquivo. Este trecho não é um editor.json completo:

json
{
  "show_announcement": true,
  "announcement": "Conheça nossa seleção de produtos",
  "announcement_url": "/busca",
  "announcement_link_label": "Explorar produtos",
  "announcement_alignment": "center",
  "announcement_custom_colors": true,
  "announcement_background": "#17355c",
  "announcement_color": "#ffffff"
}

Use show_announcement: false para ocultar a tarja. Mensagem vazia mostra o nome atual da loja; URL ou texto do link vazio remove o link. O destino aceita caminho interno ou HTTPS externo. O texto é simples, sem interpretar HTML.

Com announcement_custom_colors: false, prevalecem as cores próprias do tema. O alinhamento aceita left, center ou right; cores personalizadas exigem #RRGGBB. A tarja adapta as linhas no celular. As alterações ficam no rascunho até publicar. Revisões antigas não recebem esses campos automaticamente: é necessária uma revisão que já contenha o componente, o CSS e suas definições.

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.

Chamada editável por JSON ​

Nos vinte temas oficiais compatíveis, adicione esta ocorrência ao array sections do template desejado. Ela pode ser movida, duplicada ou ocultada com os controles normais de composição. Cada ocorrência precisa de um id próprio.

json
{
  "id": "minha-chamada",
  "type": "cta",
  "settings": {
    "eyebrow": "Conheça a coleção",
    "title": "Encontre o que combina com você",
    "body": "Explore os produtos e descubra novas possibilidades.",
    "button_text": "Explorar produtos",
    "button_link": "/busca",
    "layout": "split",
    "alignment": "left",
    "content_width": "wide",
    "spacing": "normal",
    "tone": "surface",
    "title_size": "normal",
    "color_background": { "source": "default" },
    "color_text": { "source": "default" },
    "color_title": { "source": "default" },
    "color_button_background": { "source": "default" },
    "color_button_text": { "source": "default" },
    "color_button_hover": { "source": "default" }
  }
}

Mantenha todos os campos de settings. Textos são simples e escapados; body aceita quebras de linha. Deixe o valor de button_text ou button_link vazio para uma apresentação sem botão, preservando as chaves no JSON. Uma chamada sem nenhum conteúdo não ocupa espaço.

layout aceita centered (uma coluna) e split (duas colunas no computador). alignment aceita left e center; content_width, narrow e wide; spacing, compact, normal e airy; title_size, normal e large. tone aceita plain (fundo da página com separadores) e surface (destaque). As fontes e as cores no modo padrão vêm do tema. Os campos color_* também aceitam vínculo com a paleta ou cor própria, conforme o contrato de cores abaixo. No celular, as duas colunas são empilhadas.

No editor visual, use Adicionar seção → Chamada / CTA, preencha os campos, aplique e confira a prévia. Publicar continua sendo uma ação separada. Lojas existentes não recebem a seção automaticamente: precisam de uma revisão compatível. Este componente não muda os blocos Texto e HTML nem o banner.

Faixa de benefícios editável por JSON ​

Nos vinte temas oficiais atualizados, adicione a seção benefits ao array sections do template desejado, por exemplo templates/home.json. O exemplo abaixo é uma ocorrência completa; use um id diferente se adicionar outra faixa na mesma página. Os valores são os mesmos editados em Adicionar seção → Faixa de benefícios. As definições dos controles ficam em editor.json, e o desenho em sections/benefits.liquid e assets/theme.css.

json
{
  "id": "beneficios-da-loja",
  "type": "benefits",
  "settings": {
    "items": [
      {
        "id": "entrega",
        "icon": "truck",
        "title": "Opções de entrega",
        "description": "Consulte as opções no carrinho.",
        "url": ""
      },
      {
        "id": "contato",
        "icon": "chat",
        "title": "Fale com a loja",
        "description": "Tire suas dúvidas antes de comprar.",
        "url": "/contato"
      }
    ],
    "spacing": "normal",
    "dividers": true,
    "icon_color": {
      "source": "default"
    },
    "color_background": {
      "source": "default"
    },
    "color_text": {
      "source": "default"
    }
  }
}

São permitidos até oito itens. Cada um tem ID único, título obrigatório (até 100 caracteres), descrição opcional (até 240) e link opcional (caminho interno ou HTTPS). Use strings vazias para descrição/link ausentes. Ícones: none, truck, package, card, shield, clock, exchange, chat ou gift. Lista vazia oculta a seção. Os textos são escapados: HTML digitado aparece como texto.

spacing aceita compact, normal ou airy; dividers mostra as divisórias. color_background, color_text e icon_color aceitam { "source": "default" } para manter o padrão, { "source": "palette", "key": "primary" } para acompanhar uma cor da paleta ou { "source": "custom", "value": "#112233" } para uma cor própria. O valor hexadecimal direto também é aceito. No computador são até quatro colunas, e no celular duas. É possível mover, duplicar e ocultar a seção pelo editor; cada ocorrência guarda seus próprios valores.

Troque os textos apenas por condições reais da loja. Esta faixa divulga informações; não altera o cálculo de frete, prazos ou pagamento. O componente não usa JavaScript na vitrine. Revisões antigas precisam incluir o Liquid, CSS e a definição compatível; copiar somente o JSON não instala o recurso. Confira a prévia e publique uma nova revisão.

Cores vinculadas à paleta ​

Nas revisões compatíveis, um campo theme_color pode acompanhar a paleta ou usar uma cor própria. Exemplo de valor em uma ocorrência de vitrine:

json
{
  "color_card_price": { "source": "palette", "key": "primary" },
  "color_card_button_text": { "source": "custom", "value": "#ffffff" },
  "color_card_background": { "source": "default" }
}

Esse trecho é parcial: preserve os demais campos obrigatórios da ocorrência. O motor resolve as cores antes de entregar section.settings ao Liquid. O JSON continua guardando os vínculos. Um padrão sem substituição resulta em nil; nesse caso o Liquid omite o atributo e a variável local, conservando o CSS original.

liquid
{% if section.settings.color_card_price %}
  <span style="color: {{ section.settings.color_card_price }}">Exemplo</span>
{% endif %}

O tema deve declarar o campo e usá-lo no elemento real. A paleta só contém cores concretas; vínculos inexistentes são recusados. Veja o guia de organização e o uso das cores no editor.

Dados do rodapé ​

shop.contact fornece telefone, e-mail e WhatsApp como { label, url } ou null, e hours como texto. shop.socialLinks contém redes cadastradas com { id, label, url }. shop.company fornece nome empresarial (name), CNPJ (document) e endereço público (address). CPF do titular não é exposto. Valores vazios devem ser omitidos pelo tema, e textos usam o escape padrão do Liquid.

O filtro footer_links resolve categorias e menus do bloco dentro do contexto da loja. Exemplo: {% assign links = block | footer_links: catalog.categories, content.pages, theme.settings.header, capabilities, buyer %}. O tema escolhe como renderizar a lista; não invente destinos para IDs removidos.

Temas V3 · Liquid estrutura, CSS desenha, JSON compõe.