Módulos personalizados na HubSpot: o guia para fazer peças que o marketing edita sozinho

Existe um sintoma clássico de site mal construído no HubSpot, e talvez você reconheça. Toda vez que o marketing quer trocar um texto, ajustar uma imagem ou mudar a ordem de uns cards, alguém precisa chamar o desenvolvedor. O time de conteúdo fica refém de quem programa, e o desenvolvedor vira um gargalo para mudanças que deveriam levar dois minutos.

A causa quase sempre é a mesma: módulos mal feitos. Um bom módulo personalizado é uma peça reutilizável, leve e fácil de editar, que dá autonomia ao marketing dentro de limites seguros. Um módulo ruim é um bloco rígido, amarrado a uma página só, que só o desenvolvedor entende. Neste guia, vou te mostrar como fazer o primeiro tipo: a estrutura de um módulo, os tipos de campo, os campos repetidores e as boas práticas de reuso e performance.

O que é um módulo personalizado

Na HubSpot Content Hub, módulos são as peças que o marketing arrasta para dentro de uma página ou template para montar o conteúdo. Um banner de destaque, uma seção de depoimentos, uma faixa de logos de clientes: cada um desses é um módulo. Eles são a unidade de construção do site, e a qualidade deles define o quanto o time consegue tocar o site sem ajuda técnica.

A graça do módulo é separar a estrutura do conteúdo. O desenvolvedor define como a peça se comporta e qual a aparência, e expõe ao marketing apenas os campos que fazem sentido variar, como o título e a imagem. Assim, o conteúdo muda sem que o layout quebre. Essa separação é o coração de um site sustentável na HubSpot.

A anatomia de um módulo

Cada módulo é uma pasta com a extensão .module e três arquivos centrais que conversam entre si. Entender o papel de cada um é o primeiro passo para construir módulos bons.

• module.html: o template em HubL e o HTML da peça. É aqui que os campos definidos viram, de fato, o conteúdo que aparece na tela.
• fields.json: a definição dos campos editáveis, ou seja, tudo o que o marketing vê e pode mexer no editor visual.
• meta.json: os metadados do módulo, como o rótulo que aparece no editor, o ícone e em quais tipos de template ele pode ser usado.

O CSS e o JavaScript da peça ficam em arquivos próprios, module.css e module.js, e o HubSpot os carrega só quando o módulo está presente na página, e uma única vez mesmo que o módulo apareça várias vezes. Esse carregamento sob demanda é um detalhe importante de performance, porque evita que o estilo e o script de uma peça pesem em páginas onde ela nem aparece.

Campos: dê controle sem dar caos

Os tipos de campo cobrem texto, rich text, imagem, link, cor, escolha entre opções e grupos. O segredo de um bom módulo está no equilíbrio: expor o que precisa variar e travar o resto. Exponha o título, a imagem e o link do botão, mas mantenha o espaçamento, o comportamento e o alinhamento fixos no template. Assim o marketing edita o conteúdo livremente sem nunca quebrar o layout.

O erro mais comum aqui é expor campos demais, na ilusão de dar flexibilidade. Quando o marketing pode mexer em espaçamento, cor de fundo, tamanho de fonte e dez outras coisas por peça, cada página acaba com um visual diferente, e a identidade do site se perde. Menos campos, bem escolhidos, geram mais consistência e menos suporte.

Campos repetidores para listas

Quando o módulo mostra uma lista de itens iguais, como vários depoimentos, cards ou logos, a ferramenta certa é o campo de grupo repetidor. Em vez de criar dez campos fixos para dez cards, você cria um grupo repetidor, e o marketing adiciona ou remove itens à vontade. O template percorre todos eles com um laço, gerando o HTML de cada um automaticamente.

Isso muda completamente a experiência de quem edita. Com campos fixos, adicionar um card exige o desenvolvedor. Com um repetidor, o marketing faz sozinho, na hora. É a diferença entre um módulo que envelhece mal, sempre precisando de ajuste técnico, e um que cresce com o conteúdo sem fricção.

Reuso: o segredo de um tema sustentável

Um módulo genérico e bem nomeado é usado em muitas páginas. Um módulo amarrado a uma página específica é usado uma vez e esquecido. A diferença entre os dois define se o seu tema vira uma biblioteca enxuta de peças reaproveitáveis ou uma coleção inchada de blocos de uso único que ninguém mais entende.

Na hora de criar um módulo, pergunte: essa peça poderia servir em outras páginas? Se sim, generalize o nome e os campos para que ela sirva. Um módulo de conteúdo dividido em texto e imagem, por exemplo, serve numa página de serviço, numa de sobre e numa landing page. Investir em peças genéricas é investir na manutenção barata do site no longo prazo.

Performance e versionamento

Cada módulo carrega seu CSS e JS, e peças pesadas somam no tempo de carregamento das páginas onde aparecem. Mantenha o estilo e o script enxutos, evite bibliotecas grandes para efeitos simples, e lembre que velocidade de página afeta tanto o ranqueamento quanto a conversão. Um site rápido começa em módulos leves.

E trate os arquivos do módulo como código de verdade, porque são. Mudanças devem passar por revisão antes de chegar à produção, e não ser editadas direto no site no ar. Um módulo é reutilizado em muitas páginas, então um erro nele se multiplica. Versionar e revisar é o que evita que um ajuste pequeno quebre o site inteiro de uma vez.

Erros comuns ao criar módulos

Alguns deslizes aparecem com frequência e cobram caro depois. O mais comum é o módulo de uso único: uma peça criada para uma página específica, com nome e campos amarrados àquele contexto, que nunca mais é reaproveitada. Em pouco tempo o tema acumula dezenas dessas peças quase iguais, e ninguém sabe mais qual usar. Outro erro é jogar todo o conteúdo em campos de rich text soltos, abrindo mão da estrutura e deixando o marketing colar HTML que quebra o layout.

Há também o erro de não pensar na responsividade da peça desde o começo, criando um módulo que fica bom no desktop e desmorona no celular. Como boa parte do tráfego é mobile, um módulo que não responde bem a telas pequenas compromete a experiência justamente onde mais gente acessa. O antídoto para todos esses erros é o mesmo: pensar o módulo como uma peça reutilizável, estruturada e responsiva desde o primeiro rascunho, e não como uma solução pontual para a página da vez.

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.

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.

Por que isso importa para a sua operação

Módulos bem feitos não são só uma questão técnica, são uma questão de velocidade do negócio. Um time de marketing que consegue lançar uma landing page, ajustar uma seção ou trocar um depoimento sozinho, sem fila com o desenvolvedor, é um time que se move na velocidade da campanha, não na velocidade da agenda técnica. A autonomia que um bom módulo dá se traduz diretamente em mais conteúdo no ar, mais rápido.

Do outro lado, módulos ruins criam um gargalo invisível que custa caro. Cada mudança simples vira um chamado, cada chamado entra numa fila, e ideias de campanha morrem esperando uma alteração que deveria ser trivial. Investir em módulos bem desenhados é, no fundo, investir na agilidade de marketing da empresa inteira.

Na prática: o site que dependia do desenvolvedor para tudo

Uma empresa tinha um site na HubSpot onde cada página era um módulo único, gigante, com o conteúdo todo chumbado no código. Para trocar uma frase na home, o marketing abria um chamado, e o ajuste levava dias na fila do time técnico. A frustração era grande dos dois lados: o marketing travado, o desenvolvedor afogado em micro-tarefas.

A reconstrução foi quebrar aqueles blocos gigantes em módulos genéricos e reutilizáveis, com campos editáveis bem escolhidos e repetidores para as listas. Depois disso, o marketing passou a montar e ajustar páginas sozinho, e o desenvolvedor voltou a focar no que só ele podia fazer. O mesmo site, com a estrutura certa, deixou de ser um gargalo e virou uma ferramenta.

Checklist de um módulo bem feito

1. A peça tem os três arquivos centrais, module.html, fields.json e meta.json?
2. Os campos expõem o que precisa variar e travam o que precisa ser consistente?
3. Listas de itens usam um campo de grupo repetidor, não campos fixos?
4. O CSS e o JS estão em arquivos próprios e enxutos, carregados sob demanda?
5. O módulo é genérico e bem nomeado, pensado para reuso em várias páginas?
6. As mudanças passam por revisão antes de chegar à produção?

Perguntas frequentes

Qual a diferença entre module.html e fields.json?

O fields.json define os campos que o marketing edita no editor visual. O module.html usa esses campos em HubL para gerar o HTML final que aparece na página. Um declara os campos, o outro os renderiza.

Quando devo usar um campo repetidor?

Sempre que o módulo exibe uma lista de itens iguais, como cards, depoimentos ou logos. O repetidor deixa o marketing adicionar e remover itens sem mexer no código nem chamar o desenvolvedor.

Por que separar CSS e JS em arquivos do módulo?

Porque assim eles carregam só quando o módulo está presente na página, em vez de pesarem em todas. Esse carregamento sob demanda ajuda na performance do site.

Quantos campos um módulo deve ter?

O mínimo que dá controle sobre o que precisa variar. Expor campos demais, como espaçamento e cor por peça, faz cada página ficar diferente e quebra a identidade do site. Menos campos bem escolhidos geram mais consistência.

Posso reutilizar o mesmo módulo em páginas diferentes?

Sim, e esse é o objetivo de um módulo bem feito. Uma peça genérica e bem nomeada serve em várias páginas, o que mantém o tema enxuto e a manutenção barata.

Módulo personalizado exige saber programar?

Criar o módulo exige conhecimento de HubL, HTML e CSS. Mas, uma vez criado, ele é editado pelo marketing no editor visual, sem nenhum código. Esse é justamente o valor do módulo: programar uma vez para o time usar sempre.

Quer módulos que o seu time de marketing edita sozinho, sem quebrar o layout nem pesar o site? Na Insight Sales, como parceiros HubSpot, desenvolvemos temas e módulos sob medida. Fale com a gente e descubra como podemos ajudar.