Arquivos de módulos

Last updated:

Ao construir um módulo para páginas, blogs e orçamentos, ele conterá três arquivos relacionados ao front-end que controlam o conteúdo, o estilo e a funcionalidade do módulo:

  • module.html
  • module.css
  • module.js

Os módulos de e-mail não suportam module.css e module.js. Isso porque os clientes de e-mail não suportam JavaScript e o suporte a arquivos CSS vinculados é limitado.

Esses arquivos serão sempre renderizados na página quando uma instância do módulo estiver na página.

Quando uma página inclui várias instâncias de um mesmo módulo, o HubSpot carrega o module.css e o module.js do módulo uma única vez. Por padrão, module.css e module.js não são carregados de forma assíncrona, mas você pode alterar isso incluindo css_render_options e js_render_options no meta.json do módulo.

Os módulos podem ser criados dentro do gerenciador de design ou localmente, usando a CLI da HubSpot. No gerenciador de design, os arquivos dos módulos são exibidos em um editor multipainel.

cms-dev-custom-module1Ao visualizar um módulo localmente, os arquivos estão contidos dentro das pastas module-name.module.

cms-dev-custom-module0Se você usa o gerenciador de design ou a CLI, a criação e o gerenciamento dos módulos depende das preferências da sua equipe. Veja criar um fluxo de trabalho eficiente para desenvolvedores para obter recomendações.

HTML + HubL (module.html)

O arquivo module.html é destinado ao HTML e HubL. Em geral, o local em que um módulo é colocado no editor de páginas ou no arquivo de modelo determina onde o conteúdo do arquivo module.html será renderizado. 

Esse arquivo atua como um elemento include do HubL na página em que o módulo deve ser colocado. O arquivo module.html pode acessar os valores de campo do módulo por meio do HubL.

CSS (module.css)

Use o arquivo module.css para adicionar CSS a um módulo.

Em geral, o module.css suporta um subconjunto muito limitado do HubL. No entanto, você pode usar module_asset_url("my-image.png") para imagens adicionadas como ativos vinculados ao módulo. Isso permite vincular ativos como imagens, empacotadas no próprio módulo. Por exemplo:

.testimonial-module__wrapper{ background: url("{{ module_asset_url("bg-pattern.png") }}"); background-repeat:repeat; min-height:200px; width:100%; display:block; }

Abaixo, aprenda como configurar o CSS de um módulo para mudar dinamicamente com base nos campos do módulo.

Estilo com base em valores de campo de módulo

Existem algumas formas de influenciar o estilo do seu módulo com base nos campos do módulo. Escolha a forma que melhor se adapta ao seu caso de uso específico.

Classes de CSS

Para configurar um estilo predefinido para o módulo com a possibilidade de os editores escolherem entre opções, você pode adicionar um campo de módulo para definir classes em seu arquivo module.html que correspondem às classes CSS em seu arquivo module.css.

Por exemplo, você pode ter um módulo de imagem e texto. Você quer que os criadores de conteúdo sejam capazes de posicionar a imagem à direita ou à esquerda do texto com base em um campo de escolha. Para fazer isso, você pode definir seus arquivos module.html e module.css da seguinte forma:

<!-- module.html --> <section class="img-text__wrapper img-text--{{ module.positioning }}" aria-label="{{ module.heading }}"> {# module.position is a choice field with two values "img-left" or "img-right". This dictates the order they appear on desktop. Controlled by CSS #} <div class="img-text__img"> <img src="{{ module.image.src }}" alt="{{ module.image.alt }}"> </div> <div class="img-text__text"> <h2> {% inline_text field="heading" value="{{ module.heading }}" %} </h2> {% inline_rich_text field="text" value="{{ module.text }}" %} </div> </section>
/* module.css */ /* CSS that makes the image show adjacent to the text, and positioned based on the positioning field.*/ /* The media query ensures that on mobile the image will always appear above the text for visual consistency. */ @media(min-width:768px){ .img-text__wrapper{ display:flex; align-items:row; } .img-text__img,.img-text__text{ flex:1; padding:10px; } .img-text--img-right{ flex-direction:row-reverse; } }

Bloco require_css

Quando as classes não são ideais e você precisa fornecer aos criadores de conteúdo controle direto sobre propriedades específicas, as tags de estilo com blocos require_css são a melhor opção. 

Para fornecer aos criadores de conteúdo controle direto sobre propriedades específicas sem usar classes, você pode adicionar estilo ao arquivo module.html dentro das tags required_css. Por exemplo:

<div class="img__wrapper"> {% if module.image.src %} {% set sizeAttrs = 'width="{{ module.image.width }}" height="{{ module.image.height }}"' %} {% if module.image.size_type == 'auto' %} {% set sizeAttrs = 'style="max-width: 100%; height: auto;"' %} {% elif module.image.size_type == 'auto_custom_max' %} {% set sizeAttrs = 'width="100%" height="auto" style="max-width: {{ module.image.max_width }}px; max-height: {{ module.image.max_height }}px"' %} {% endif %} <img src="{{ module.image.src }}" alt="{{ module.image.alt }}" {{ sizeAttrs }}> {% endif %} </div> {% require_css %} <style> img { border-width:{{ module.border_width }}px; border-color:rgba({{ module.border_color.color|convert_rgb}},{{ module.border_color.opacity/100 }}); border-style: solid; } </style> {% end_require_css %}

Como o module.html pode renderizar HubL, você pode usar os valores de campo do módulo como variáveis CSS. Quando um criador de conteúdo atualiza o campo no editor de páginas, o CSS é atualizado de acordo. Esses blocos movem as tags <style> para o <head> da sua página dentro da instrução standard_header_includes.

Você também pode definir o CSS abrangido apenas à instância do módulo, envolvendo o CSS com as tags scope_css. Por exemplo, você poderia atualizar o código do módulo acima da seguinte forma:

<div class="img__wrapper"> {% if module.image.src %} {% set sizeAttrs = 'width="{{ module.image.width }}" height="{{ module.image.height }}"' %} {% if module.image.size_type == 'auto' %} {% set sizeAttrs = 'style="max-width: 100%; height: auto;"' %} {% elif module.image.size_type == 'auto_custom_max' %} {% set sizeAttrs = 'width="100%" height="auto" style="max-width: {{ module.image.max_width }}px; max-height: {{ module.image.max_height }}px"' %} {% endif %} <img src="{{ module.image.src }}" alt="{{ module.image.alt }}" {{ sizeAttrs }}> {% endif %} </div> {% require_css %} <style> {% scope_css %} img { border-width:{{ module.border_width }}px; border-color:rgba({{ module.border_color.color|convert_rgb}},{{ module.border_color.opacity/100 }}); border-style: solid; } {% end_scope_css %} </style> {% end_require_css %}

Adicionar estilos integrados

Quando as classes não são ideais e você precisa dar aos criadores de conteúdo controle granular apenas sobre algumas propriedades, pode adicionar diretamente os valores a um atributo de estilo no HTML.

{# Module.html #} <div style="background: rgba({{ module.bg_color.color|convert_rgb }},{{ module.bg_color.opacity/100 }});"> {% inline_rich_text field="richtext" value="{{ module.richtext }}" %} </div>

Se você tiver muitas propriedades e o código se tornar difícil de ler, considere mudar para o método de bloco require_css.

Importar arquivos CSS específicos

O require_css é uma função do HubL que pode ser adicionada ao module.html para informar ao HubSpot que um determinado módulo ou modelo requer um determinado arquivo CSS para ser exibido. Uma tag de link apontando para o arquivo css é adicionada ao <head> da página dentro de standard_header_includes. 

A função require_css só carregará esse arquivo CSS uma vez, independentemente do número de vezes que esse mesmo arquivo seja exigido pelos módulos e modelos em uma determinada página. Isso o torna ideal para situações em que os estilos são compartilhados entre os módulos, mas não faz sentido adicionar o CSS diretamente às folhas de estilo principais utilizadas em cada página do seu site.

O require_css e os arquivos CSS associados fazem a mesma coisa, mas o require_css pode ser executado de forma condicional com base nos valores do campo. Isso evita o carregamento de códigos desnecessários.

<!-- module.html --> {{ require_css(get_asset_url("/modules/shared_layout_styles.css")) }}

JavaScript (module.js)

Use o arquivo module.js para adicionar JavaScript a um módulo.

Assim como o arquivo module.css, o arquivo module.js não suporta HubL.

Scripting baseado em valores de campo

Existem algumas formas de criar módulos em que o JavaScript atua de forma diferente com base nos valores de campo. Compreender que método utilizar e quando pode trazer benefícios de desempenho para todas as páginas em que o módulo é utilizado. 

Por exemplo, você tem um módulo de imagem personalizado e quer fornecer aos criadores de conteúdo a capacidade de fazer a imagem abrir em uma lightbox. Os criadores de conteúdo só querem isso em imagens específicas, e não em todas as instâncias do módulo.

Atributos de dados

Os atributos de dados são atributos personalizados padrão HTML 5 que os desenvolvedores adicionam aos elementos. Todos os elementos suportam tanto class="yourClassName" quanto data-your-attribute="yourValue".

<!-- module.html--> <div class="img-module img-module__wrapper" data-lightbox="{{ module.is_lightbox_enabled }}" data-caption="above"> <!-- module.is_lightbox_enabled is a boolean field, module.caption_position is a choice field. --> {% if module.image.src %} {% set sizeAttrs = 'width="{{ module.image.width }}" height="{{ module.image.height }}"' %} {% if module.image.size_type == 'auto' %} {% set sizeAttrs = 'style="max-width: 100%; height: auto;"' %} {% elif module.image.size_type == 'auto_custom_max' %} {% set sizeAttrs = 'width="100%" height="auto" style="max-width: {{ module.image.max_width }}px; max-height: {{ module.image.max_height }}px"' %} {% endif %} <img src="{{ module.image.src }}" alt="{{ module.image.alt }}" {{ sizeAttrs }}> {% endif %} </div>

Você pode usar atributos de dados para passar os valores de campo das instâncias do seu módulo a serem tratadas pelo arquivo module.js.

Para usar os valores no arquivo module.js, você precisará executar em loop todas as instâncias do módulo. Adicionar um nome de classe específico do módulo ao wrapper mais externo do seu módulo lhe dará um alvo para usar, para que você possa executar em loop cada uma das instâncias do seu módulo.

// module.js let imgModules = document.getElementsByClassName('img-module'); Array.from(imgModules).forEach(function(element) { // loop through each of the instances of the module // set data attributes to variables to make it easy to work with let isLightboxEnabled = element.dataset.lightbox; let captionStyle = element.dataset.caption; if(isLightboxEnabled){ element.addEventListener('click', function(){ showLightbox(captionStyle); // Execute your code for the action you want to take, you can pass your data attributes into functions from libraries. }); } });

Os atributos de dados permitirão recuperar os valores de campo para cada instância do módulo no module.js. 

Bloco require_js

Em situações avançadas, talvez ao usar uma biblioteca de modelos JavaScript ou um framework reativo como Vue.js ou React.js, você pode preferir emitir apenas os dados, enquanto o framework trata da renderização.

Neste caso, use uma tag de script entre require_js para fornecer variáveis que você pode acessar do script de modelagem.

{% require_js %} <script> let myArray = [ {%- for item in module.repeating_text_field -%}"{{ item }}",{%- endfor -%} ]; </script> {% end_require_js %}

Esta técnica pode ser útil para fornecer aplicações avançadas com um conjunto inicial de dados do qual se pode renderizar. Isso elimina uma chamada inicial por JavaScript para recuperar os dados.

require_js

O require_js é uma função do HubL que informa ao HubSpot que um determinado módulo ou modelo requer um determinado arquivo JavaScript para ser carregado corretamente. A função tem dois parâmetros: o caminho para o arquivo e o local onde o arquivo deve ser adicionado ("head" ou "footer"). 

Em um módulo, o require_js somente pode ser adicionado ao módulo.html. O arquivo JavaScript referido na instrução require_js somente será carregado uma vez por página, independentemente do número de vezes que seja requerido pelos módulos e modelos dentro da página. Isso reduz o número de solicitações HTTP e evita a duplicação de código. 

Algumas situações em que isso se torna útil:

  • Se você tem vários módulos ou modelos que requerem o mesmo JavaScript, você pode usar o require_js para compartilhar esse script entre os módulos.
  • Se você estiver trabalhando com um bundler JavaScript, como um webpack, pode ser mais fácil enviar os arquivos js para um local específico. Usando require_js, você pode associar o JavaScript ao módulo.

O require_js e os arquivos javascript associados fazem a mesma coisa, mas o require_js pode ser executado de forma condicional com base nos valores do campo. Isso evita que códigos desnecessários sejam carregados. Você também tem a opção de carregar o JavaScript no cabeçalho, caso você precise disso.

Como o JavaScript pode causar bloqueio de renderização, o require_js coloca o JavaScript no "footer" por padrão. Saiba mais sobre como optimizar o desempenho.

Informações relacionadas

Este artigo foi útil?
Este formulário deve ser usado apenas para fazer comentários sobre esses artigos. Saiba como obter ajuda para usar a HubSpot..