HubL na prática: loops, repeater fields e JSON sem mistério

O HubL parece simples até o dia em que você precisa percorrer uma lista de itens, contar quantos são ou transformar um texto em estrutura de dados. Aí, de repente, aquela linguagem de template que parecia só preencher campos vira um quebra-cabeça, e você fica preso num erro bobo que consome a tarde inteira.

A boa notícia é que os padrões que você mais precisa no dia a dia são poucos e, depois de entendidos, resolvem a maioria dos casos. Neste guia, vou cobrir os quatro que mais aparecem quando se desenvolve no HubSpot Content Hub: o laço for, os campos repetidores, o filtro de tamanho e a conversão de JSON. Com exemplos prontos para você copiar e adaptar.

O que é o HubL e por que ele importa

O HubL é a linguagem de template da HubSpot, inspirada em linguagens como o Jinja. É ela que transforma os campos definidos num módulo e os dados do CRM e do CMS em HTML pronto para a página. Sem HubL, um módulo seria estático; com ele, o módulo ganha lógica: percorre listas, decide o que mostrar conforme uma condição, formata valores.

Dominar o HubL é o que separa quem monta páginas simples de quem constrói temas que aguentam conteúdo dinâmico de verdade. Os quatro padrões a seguir são a base desse domínio, e juntos cobrem a esmagadora maioria das necessidades reais de quem desenvolve no Content Hub.

O laço for: percorrendo listas

O for é o laço que percorre qualquer lista no HubL. O caso mais comum é iterar sobre um campo repetidor, gerando um bloco de HTML para cada item. É assim que um módulo de depoimentos transforma uma lista de itens editáveis numa sequência de citações na tela.

Dentro do laço, cada item expõe os seus próprios subcampos, que você acessa com a notação de ponto, como item.texto e item.autor. Essa é a ponte entre o que o marketing edita no campo repetidor e o que aparece renderizado na página. Entender essa relação é o que destrava a construção de qualquer módulo com lista.

Campos repetidores: listas dinâmicas sem campos fixos

Um campo de grupo com repetição vira, no HubL, uma lista que você percorre com o for. Em vez de criar dez campos fixos para dez cards, você cria um grupo repetidor, e o marketing adiciona quantos itens quiser. Cada item carrega seus subcampos, acessíveis dentro do laço, o que torna o módulo flexível sem nenhuma intervenção técnica a cada novo item.

Essa combinação de campo repetidor com laço for é, provavelmente, o padrão mais útil de todo o desenvolvimento no Content Hub. Praticamente toda seção que mostra uma coleção de coisas, recursos, etapas, perguntas frequentes, clientes, usa esse padrão por baixo. Dominar essa dupla resolve metade dos módulos que você vai construir.

Contar itens com o filtro length

O filtro |length devolve o número de itens de uma lista. Ele é útil para duas coisas: mostrar um contador na tela, como o número de resultados, e mudar o layout conforme a quantidade de itens. Por exemplo, aplicar uma grade de três colunas quando há três cards e de duas quando há quatro.

Esse padrão de adaptar o layout ao número de itens é o que faz um módulo parecer caprichado em qualquer quantidade de conteúdo. Sem ele, três cards podem ficar espremidos numa grade pensada para seis, ou um card solitário pode parecer perdido. O |length dá ao template a informação que ele precisa para se ajustar sozinho.

Transformar string em JSON com fromjson

Às vezes um campo guarda uma estrutura mais rica do que os campos simples comportam, na forma de um texto em JSON. O filtro fromjson transforma essa string numa estrutura navegável dentro do HubL, dando acesso aos valores por nome. É útil para configurações complexas que não cabem bem em campos individuais.

Use esse recurso com parcimônia, porém. Guardar JSON em texto é poderoso, mas torna o campo menos amigável para quem edita, porque o marketing precisa escrever JSON válido na mão. Na maioria dos casos, campos próprios e repetidores são mais claros. Reserve o fromjson para quando a estrutura é realmente complexa demais para os campos nativos.

Escopo de variáveis: a pegadinha do HubL

Aqui está o ponto que mais confunde quem vem de linguagens de programação tradicionais. Uma variável criada com set dentro de um laço não se comporta fora dele como muita gente espera. Para acumular um valor ao longo de um laço, por exemplo somar algo a cada volta, você precisa entender que o HubL trata o escopo de forma própria, e nem sempre intuitiva.

A regra prática é simples: na dúvida, teste com um valor pequeno antes de confiar no resultado. Em vez de assumir que a variável vai se comportar como em JavaScript ou Python, monte um caso mínimo, veja o que o HubL faz, e só então construa em cima. Esse hábito de testar o escopo antes evita horas de depuração de um valor que "deveria" estar certo mas não está.

Quando você realmente precisa acumular, o caminho confiável é declarar uma estrutura mutável fora do laço, um dicionário ou uma lista, e alterá-la dentro do laço com o do, como ou . Isso persiste, porque você está mutando o objeto, e não recriando a variável a cada volta.

Condições com if para mostrar o que importa

Além de percorrer listas, o HubL decide o que mostrar com a condição if. Isso é o que permite um módulo se adaptar ao conteúdo: mostrar um botão só quando há um link preenchido, exibir um título alternativo quando o principal está vazio, esconder uma seção inteira quando o campo correspondente não foi usado. Sem isso, o template renderiza estruturas vazias, com botões sem texto e blocos sem conteúdo, que sujam a página e passam impressão de descuido.

O padrão é simples e poderoso: antes de renderizar um elemento, verifique se o campo que o alimenta tem valor. Combinada com os laços e o filtro de tamanho, a condição if dá ao módulo a inteligência de mostrar exatamente o que faz sentido para o conteúdo que o marketing colocou, e nada além. É o que separa um template rígido de um que se molda ao que recebe, parecendo sempre intencional e bem acabado.

Por que isso importa para a sua operação

HubL bem escrito é o que permite que o time de marketing tenha módulos flexíveis sem precisar de um desenvolvedor a cada ajuste. Um módulo que percorre uma lista, conta itens e adapta o layout é um módulo que o marketing usa em mil situações diferentes sozinho. A lógica que você escreve uma vez em HubL se paga em autonomia para o time todo, repetidamente.

Do contrário, módulos com HubL mal feito viram caixas-pretas frágeis, que quebram quando o conteúdo varia e exigem o desenvolvedor a cada situação nova. A diferença entre os dois é exatamente o domínio desses padrões básicos. Investir em HubL limpo é investir em módulos que duram e que o time consegue operar sem fricção.

Na prática: a grade que quebrava com poucos itens

Um time tinha um módulo de cards bonito, mas que só ficava bem com exatamente seis itens, o número para o qual a grade foi pensada. Quando o marketing colocava quatro, ou sete, o layout desmoronava, com cards espremidos ou sobrando espaço. A cada campanha com um número diferente de cards, lá ia um chamado para o desenvolvedor ajustar a grade na mão.

A correção foi usar o filtro |length para contar os itens e aplicar uma classe de grade conforme a quantidade. Com poucas linhas de HubL, o módulo passou a se ajustar sozinho a qualquer número de cards. Os chamados pararam, e o marketing ganhou a liberdade de usar a peça com a quantidade de conteúdo que a campanha pedia, sem depender de ninguém.

Checklist do HubL bem usado

1. As listas são percorridas com for, acessando os subcampos por ponto?
2. Listas dinâmicas usam campos repetidores em vez de campos fixos?
3. O layout se adapta à quantidade de itens com o filtro |length quando faz sentido?
4. O fromjson é reservado para estruturas realmente complexas, não para o trivial?
5. O escopo de variável dentro de laços foi testado antes de se confiar nele?
6. O HubL está enxuto e legível, sem lógica desnecessária no template?

Perguntas frequentes

Como percorro um campo repetidor no HubL?

Com um laço for item in module.nome_do_campo. Dentro do laço, cada item expõe seus subcampos, acessados por ponto, como item.texto e item.autor.

Como conto quantos itens uma lista tem?

Com o filtro |length, por exemplo module.cards|length. Ele devolve o número de itens, útil para mostrar contadores e para variar o layout conforme a quantidade.

Para que serve o fromjson?

Para transformar uma string que contém JSON numa estrutura navegável dentro do HubL, dando acesso aos valores por nome. É útil para configurações complexas, mas reserve-o para casos que os campos nativos não resolvem bem.

Por que minha variável de laço não funciona como espero?

O HubL trata o escopo de variáveis dentro de laços de forma própria, diferente de linguagens como JavaScript. Teste com um caso simples antes de confiar no comportamento, especialmente ao acumular valores ao longo do laço.

HubL é uma linguagem de programação?

É uma linguagem de template, inspirada no Jinja. Ela tem lógica, como laços e condições, mas é voltada para gerar HTML a partir de campos e dados, não para programação de propósito geral.

Posso usar JavaScript dentro de um módulo em vez de HubL?

Sim, o JavaScript roda no navegador para interatividade. Mas o HubL roda na geração da página, no servidor, e é o que monta o HTML a partir dos campos. Os dois se complementam: HubL para estruturar, JS para interagir.

Precisa de templates HubL que aguentam listas dinâmicas e configurações complexas sem virar bagunça? Na Insight Sales desenvolvemos no HubSpot CMS com código limpo e reaproveitável. Fale com a gente e descubra como podemos ajudar.