Introdução aos módulos

Neste tutorial, você usará o tema do HubSpot CMS Boilerplate para aprender como criar um módulo e usá-lo em modelos e páginas como parte de um tema. No final do tutorial, você terá criado um módulo de depoimentos que inclui um campo de imagem, um campo de texto e um campo de rich text. 

Antes de começar com este tutorial:

• Configure um Ambiente de testes para desenvolvedores do HubSpot CMS. Você pode usar sua conta existente, mas o ambiente de testes permitirá o desenvolvimento sem afetar os ativos da sua conta principal.
• Instale o Node.js, que habilita as ferramentas de desenvolvimento local da HubSpot. As versões 10 ou superior são compatíveis.

Se quiser avançar, você pode visualizar os arquivos do projeto concluídos. Como o código do tema do CMS Boilerplate pode mudar com o tempo, apenas os arquivos mais críticos que os desenvolvedores precisarão criar ou editar durante o tutorial são incluídos. Esses campos incluem:

1. Testimonial.module: a pasta que contém os arquivos que compõem o módulo personalizado que você criará como parte do tutorial.
2. homepage.html: o modelo que você editará para incluir o módulo personalizado.
3. images: a pasta que contém as imagens de perfil que você usará no módulo. 

Durante este tutorial, você fará o desenvolvimento do módulo localmente. Para interagir com o HubSpot na interface da linha de comando, você precisará instalar a CLI do HubSpot e configurá-la para acessar sua conta.

• No terminal, execute o comando a seguir para instalar a CLI globalmente. Para instalar a CLI apenas no seu diretório atual, execute o  npm install @hubspot/cli.

Com o boilerplate de CMS em seu ambiente local, você criará um novo módulo para o tema.

• Faça login na sua conta da HubSpot e acesse o gerenciador de design, navegando até Marketing > Arquivos e modelos > Ferramentas de design.
• Na barra lateral esquerda do gerenciador de design, abra a pasta de temas que você acabou de fazer o upload. 
• Na pasta de temas, abra a pasta de módulos.
• No canto superior esquerdo, clique em Arquivo > Novo arquivo para criar um novo módulo nesta pasta.
• Na caixa de diálogo, clique no menu suspenso, selecione Módulo e clique em Próximo.
  
• Marque a caixa de seleção Páginas para disponibilizar o módulo para o site e as landing pages.
• Nomeie o módulo como Depoimentos e clique em Criar.

Em seguida, você adicionará três campos ao módulo:

• Um campo de texto para armazenar o nome do cliente que está fornecendo o depoimento.
• Um campo de imagem que armazenará a imagem de perfil do cliente.
• Um campo de rich text que armazenará o depoimento do cliente.

Adicionar campo de texto para nome do cliente

• Na barra lateral direita do editor de módulos, clique no menu suspenso Adicionar campo e selecione Texto.
  
• Na barra lateral direita, clique no ícone de lápis no canto superior direito para dar um nome para o campo. Para este tutorial, insira o Nome do cliente. Você verá a mudança do nome da variável do HubL para customer_name.
• Defina o Texto padrão para Sally.

• Na barra lateral direita, clique no ícone de trilha de navegação para retornar ao menu do módulo principal.

Adicionar o campo de imagem para a foto de perfil do cliente

• Adicione outro campo usando o mesmo método, desta vez, selecionando o tipo de campo de Imagem.
• Rotule o campo de imagem Imagem do perfil, em seguida, defina o nome da variável do HubL como profile_pic.
• Em Imagem padrão, selecione a imagem do perfil fornecida para sally na pasta de imagens dos arquivos do projeto concluídos.
• Defina o Texto alternativo como Imagem de perfil de Sally.

Adicionar o campo de rich text para o depoimento de Sally

• Adicione outro campo usando o mesmo método, desta vez selecionando o tipo de campo de Rich text.
• Rotule o campo de rich text Depoimentos.
• Clique na caixa de Rich text padrão e digite "Não tive nada além de experiências maravilhosas com esta empresa".

Até agora, você adicionou dados em vários campos de módulo. Neste momento, porém, o módulo não contém nenhum HTML para renderizar esses dados. No editor de módulos, isso é refletido pelo estado vazio da seção module.html. 

Em seguida, você adicionará o HubL ao module.html para exibir os dados do campo.

Para exibir dados dos campos criados anteriormente, adicione o seguinte HubL ao painel module.html:

Os tokens HubL acima usam notação de ponto para acessar os dados de cada campo. Nesse caso, como queremos extrair os dados dos campos do módulo, cada token começa com module, seguido pelo nome da variável HubL do campo. Você pode usar a notação de ponto para acessar ainda mais propriedades específicas de um campo, o que você pode ver nos tokens profile_pic na linha 3 acima.

• Com o HubL adicionado ao módulo, clique em Visualizar no canto superior direito para ver como o módulo está até agora.

• No canto superior direito, clique em Publicar alterações.

Depois de criar e publicar o módulo no HubSpot, você usará a CLI para enviá-lo para o ambiente local, de modo a poder visualizar seu conteúdo e fazer quaisquer alterações necessárias.

Para exibir o módulo localmente, primeiro você precisará baixá-lo para o tema local:

• No terminal, execute o seguinte comando: hs fetch <hs_src> <destination>:
  • <hs_src> representa o caminho do arquivo do módulo no HubSpot. Para obter o caminho do arquivo, clique com o botão direito do mouse no módulo, na barra lateral esquerda do gerenciador de design, e selecione Copiar caminho. 
    
  • <destination> representa o caminho para o diretório local onde se encontra o tema. Se omitido, o comando será o padrão para o diretório de trabalho atual.

Por exemplo, se você já estiver no diretório de trabalho, o comando de busca pode ser semelhante ao seguinte:

No seu editor de códigos preferido, acesse a pasta do módulo que você acabou de baixar da sua conta da HubSpot. Dentro da pasta do módulo, você verá cinco arquivos diferentes:

Você pode encontrar informações mais detalhadas em nossa documentação sobre a estrutura de arquivos do módulo, principalmente as relacionadas aos arquivos fields.json e meta.json. Neste tutorial, vamos nos concentrar nos arquivos fields.json, module.css e module.html e como eles são gerados, baixados e enviados para o editor de módulos no Gerenciador de design.

Abra o arquivo fields.json do módulo. Além de alguns dos números de id, o atributo src do campo de imagem e, potencialmente, a ordem dos campos, o arquivo deve conter um objeto JSON semelhante ao seguinte:

Os valores para os seguintes campos corresponderão aos valores adicionados na etapa 3:

• name: o nome do campo.
• label: o rótulo do campo.
• default: o valor padrão do campo.  

O arquivo module.html deve conter o HubL e o HTML que você escreveu anteriormente no editor de módulos do HubL + HTML.

Para tornar este código mais interessante e pronto para estilo CSS, copie e cole o seguinte código no arquivo:

O arquivo module.css deve estar vazio neste momento. Para adicionar estilo, copie e cole o seguinte código no arquivo:

Após adicionar o código, salve o arquivo.

Depois de salvar as alterações locais, envie-as à sua conta da HubSpot.

• Acesse o terminal e verifique se você está no diretório correto.
• Execute o comando watch para enviar alterações para o HubSpot ao salvar: hs watch <src> <destination>. 

• Na sua conta da HubSpot, acesse Marketing > Arquivos e modelos > Ferramentas de design.
• Na barra lateral esquerda, acesse o tema que você criou, abra a pasta de módulos e selecione o módulo Depoimentos.
• Com o módulo aberto, você deve ver suas alterações nos painéis module.html e module.css 
• No canto superior direito, clique em Visualizar. Uma nova guia será aberta para exibir a visualização do módulo. 

Recapitulando este tutorial até agora, você:

• criou um módulo no HubSpot.
• Baixou esse módulo para o seu ambiente local.
• Fez alterações no HubL + HTML e CSS usando suas ferramentas de desenvolvimento local.

Na próxima parte deste tutorial, saiba como usar o módulo em um modelo.

Para esta parte do tutorial, você trabalhará principalmente com as pastas modules e templates nos arquivos do tema local. 

Por sua definição mais básica, os módulos são áreas editáveis de modelos e páginas da HubSpot. Você pode inserir módulos em modelos no HubSpot usando o gerenciador de design, mas aqui usaremos o HubL para adicionar módulos a um modelo em seu ambiente local.   

• No editor de códigos, abra a pasta de templates e, em seguida, o arquivo home.html. 
• No arquivo home.html, acesse a dnd_section final, que começa na linha 28. Você adicionará o seu novo módulo a esta seção.
  
• Em dnd_section e acima dos outros dnd_modules, copie e cole a seguinte tag de módulo HubL:

Essa tag HubL faz referência ao seu novo módulo pelo caminho relativo de arquivo. Para que o módulo se ajuste de forma uniforme aos outros dois módulos na dnd_section, também atribui valores de width e offset ao módulo:

• O CMS da HubSpot usa um sistema de grade de 12 colunas; portanto, para espaçar este módulo de forma uniforme com os outros dois, você precisará atualizar a dnd_section de cada módulo para uma largura igual a 4.
• Em seguida, o primeiro dnd_module no grupo (testimonial) terá um deslocamento de 0 para posicioná-lo primeiro em lugar.
• O segundo dnd_module (linked_image) terá um deslocamento de 4 para posicioná-lo em segundo lugar.
• O terceiro dnd_module (rich_text) terá um deslocamento de 8 para posicioná-lo em terceiro lugar.

Depois de definir offset e width para cada dnd_module, seu código será semelhante ao seguinte:

• Se você não tiver mantido o comando watch em execução para rastrear seu trabalho automaticamente, execute hs watch <src> <dest>. Certifique-se de que esse comando continue em execução ao concluir as próximas etapas. 
• Na sua conta da HubSpot, abra o gerenciador de design (Marketing > Arquivos e modelos > Ferramentas de design.
• Na barra lateral esquerda do gerenciador de design, selecione o arquivo home.html.
• No canto superior direito, clique em Visualizar e selecione Visualização em tempo real com opções de exibição para abrir a visualização do modelo em uma nova janela.

• Na nova guia, confira a visualização do modelo, que deve conter o módulo de depoimentos recém-adicionado.

Para tornar o modelo da página inicial mais interessante:

• Retorne ao editor de códigos e abra o arquivo home.html.
• Adicione os seguintes parâmetros à tag do módulo de depoimentos:

Os parâmetros acima substituem os valores padrão que você atribuiu originalmente aos três campos. Cada parâmetro usa o nome da variável do HubL que você atribuiu a cada campo anteriormente:

• customer_name: este parâmetro passa o nome Mary para o campo de nome do cliente, substituindo o valor de Sally.
• profile_pic: este parâmetro é um objeto que contém duas propriedades.
  • A propriedade src usa a função do HubL get_asset_url para recuperar o URL da nova imagem de perfil. Observe que o caminho do arquivo de imagem é relativo ao seu diretório de trabalho. Primeiro, você precisará adicionar essa imagem à pasta images nos arquivos do tema local. Você pode encontrar a imagem na pasta images nosarquivos do projeto concluído.
  • A propriedade alt atribui o texto alternativo da imagem.
• testimonial: este parâmetro passa um novo texto para o campo de depoimentos.

Alternativamente, para o campo de rich text, você pode usar a sintaxe de bloco do HubL para escrever um grande bloco de HTML ou texto:

Saiba mais sobre a sintaxe de bloco do módulo.

Se você manteve o comando watch em execução no seu terminal, salve as alterações para enviá-las para o HubSpot. Você pode voltar ao gerenciador de design para visualizar o modelo.

Nesta etapa, você adicionará mais dois módulos de depoimentos ao modelo usando as mesmas etapas anteriores:

• Acesse o editor de códigos e, em seguida, abra o arquivo home.html.
• No módulo de depoimentos que você adicionou anteriormente, adicione outra instância do módulo, copiando e colando o código desse módulo. No novo módulo de depoimentos, especifique os seguintes detalhes usando as mesmas etapas acima:
  • O nome do cliente é Ollie.
  • O depoimento de Ollie diz: I can't believe that I ever conducted business without the use of this product!
  • Para a imagem de Ollie, adicione o caminho de arquivo relativo para o arquivo dentro da pasta de images. Você pode obter a imagem nos arquivos do projeto concluído. Em seguida, dê à imagem de Ollie o atributo alt de Ollie Profile Picture.
  • Para manter o espaçamento, defina offset para 4 e width para 4.
• Abaixo do segundo módulo de depoimento, adicione um terceiro com os seguintes detalhes:
  • O nome do cliente é Erin.
  • O depoimento de Erin diz: My business has nearly tripled since I began to use this product! Don't wait, start now!
  • Para a imagem de Erin, adicione o caminho de arquivo relativo para o arquivo dentro da pasta de images. Em seguida, dê à imagem de Erin o atributo alt de Erin Profile Picture.
  • Para manter o espaçamento, defina offset para 8 e width para 4.

• Salve suas alterações.

Se você manteve o comando watch em execução no seu terminal, volte ao Gerenciador de design para visualizar as alterações no modelo. A visualização do modelo deve conter todos os três módulos de depoimentos.

Como etapa final, você preparará o tema para uso em uma página ativa, modificando o arquivo theme.json.

Se quiser modificar o nome padrão do tema, você pode fazer isso configurando os campos name e label no arquivo theme.json.

Depois de adicionar esse código, salve suas alterações para que o comando watch envie suas alterações para o HubSpot.

Agora que você criou um módulo personalizado, adicionou-o ao modelo home.html e, opcionalmente, personalizou o nome do tema, está pronto para criar uma página ativa a partir do tema. 

Se quiser seguir um tutorial semelhante criado especificamente para temas, confira o tutorial Introdução aos temas a seguir. Caso contrário, você pode saber mais sobre como criar e personalizar páginas na Central de conhecimento da HubSpot.

Ou, se você quiser saber mais sobre os módulos, confira os seguintes guias:

• Configurar um módulo
• Usar módulos em modelos
• Módulos padrão

• Introdução aos temas
• Introdução às funções sem servidor
• Criar um fluxo de trabalho de desenvolvedor eficaz
• Introdução à acessibilidade
• Como usar estruturas JavaScript no CMS Hub
• Como usar componentes da Web em módulos personalizados
• Como criar um módulo baseado em componentes da Web com bloco de código