Requisitos para módulos do Marketplace de modelos da HubSpot

Last updated:

Saiba mais sobre os requisitos para enviar um módulo para o Marketplace de modelos. Esses requisitos se aplicam aos módulos de um tema e aos módulos independentes. 

Restrições de módulo

Os módulos não devem conter HubDB, chamadas para funções sem servidor ou o campo de objeto do CRM.

Os seguintes tipos de módulos não devem ser criados como módulos independentes

  • HTML
  • Módulos de largura inteira
  • Formulários e formulários de várias etapas
  • Módulos espaçadores ou que criam uma estrutura de página não relacionada à interface do usuário
  • Módulos que duplicam a funcionalidade do módulo padrão
  • Módulos específicos de comércio

Conteúdo do módulo

Saiba mais sobre os requisitos para rótulos do módulo e texto de ajuda, campos e conteúdo padrão.

Rótulos do módulo e texto de ajuda

  • Os módulos devem ter rótulos descritivos que transmitam sua finalidade. O rótulo Hero Banner com rolagem Parallax é descritivo, ao contrário dos rótulos Hero Banner e Galeria
  • Os rótulos do módulo não devem conter números, como em Hero Banner 01.
  • Os rótulos do módulo não devem conter abreviações, como Col em vez de Coluna.
  • Os módulos devem conter texto de ajuda em linha (quando aplicável) para informar melhor como usar o módulo.
  • O módulo não deve ser nomeado da mesma forma que um módulo padrão.

Conteúdo padrão

  • O campo padrão não pode incluir texto Lorem ipsum
  • O conteúdo padrão do campo deve representar o propósito do campo:
    • Ao incluir campos de menu, os módulos devem usar Selecionar um menu como opção de conteúdo padrão.
    • Ao incluir campos de formulário, os módulos devem usar Selecionar um formulário como opção de conteúdo padrão.
    • Ao incluir campos de seletor de blog, os módulos devem usar Selecionar um blog como a opção de conteúdo padrão.
  • Se não fizer sentido adicionar conteúdo padrão a um módulo, use um espaço reservado para ajudar o criador de conteúdo a visualizar o espaço que ele preencherá com conteúdo.

Ícones do módulo

Os módulos devem incluir um ícone personalizado atribuído ao módulo (substituindo o ícone padrão). Não use logotipos de empresas como ícones, como logotipos da Apple ou da Amazon. Saiba mais sobre ícones do módulo.

Campos do módulo

Revise os requisitos específicos para os módulos de um tema e os módulos independentes abaixo
  • Para módulos de um tema:
    • Por exemplo, os módulos devem conter texto de ajuda integrado e conteúdo padrão específico para determinados campos.
    • Uma parte da cor e do logotipo do tema deve ser herdada das configurações de marca da conta.
      • Pelo menos três campos de cor devem herdar cores das configurações de marca da conta. Campos de cor adicionais podem ser predefinidos para outras cores, incluindo preto e branco.
      • Pelo menos um campo de logotipo deve ser herdado das configurações de marca da conta. Se estiver usando um campo de imagem para renderizar um logotipo, o campo de imagem não precisa ser herdado das configurações da marca. 
  • Para ambos os módulos em um tema e módulos independentes:
    • Os nomes dos campos do módulo devem descrever a intenção do campo. Por exemplo, se um campo de texto é usado para incluir o cargo de uma pessoa, Cargo seria uma descrição adequada, ao contrário de Título.
    • Todos os módulos padrão da HubSpot devem ser estilizados e exibidos corretamente em todos os modelos enviados.

Configuração de fields.json e module.html

Para garantir uma funcionalidade compatível entre temas e módulos independentes, os módulos devem herdar os campos de cor e fonte com a definição de default_value_path ou property_value_paths, ou ambos, no arquivo fields.json, e uma referência aos campos do tema no arquivo module.html deve ser adicionada. Saiba mais sobre esses requisitos.

Qualidade do código do módulo

Os módulos devem ser autônomos

Módulos do tema

Todos os arquivos necessários para o módulo do tema, como CSS ou JavaScript, devem estar contidos na pasta do tema e incluídos no diretório do tema. Você pode usar o recurso Arquivado vinculado no gerenciador de design. Como alternativa, inclua os arquivos usando as funções require_js() ou require_css() com um caminho relativo para o arquivo.

Para bibliotecas comuns, como slick.js, você pode incluí-las usando as funções require_js() ou require_css() com um URL absoluto para a CDN onde estão hospedadas. 

Observação: não use URLs absolutos para ativos contidos no seu portal de desenvolvimento, pois as referências entre portais não serão resolvidas. 

Módulos independentes

Para módulos independentes, todos os arquivos CSS e Javascript devem estar contidos em module.css ou module.js. Como alternativa, inclua os arquivos usando as funções require_js() ou require_css() com um URL absoluto para a CDN onde eles estão hospedados. Não é possível usar o recurso Arquivos vinculados no Gerenciador de design, pois ele está disponível apenas para módulos de tema. 

Como module.js está incluído no DOM antes de qualquer arquivo require_js ou require_css, o JavaScript contido na seção module.js deve ser adiado usando a anotação abaixo:

JavaScript
document.addEventListener("DOMContentLoaded", function(){
// Put Javascript here
});

Todos os scripts e arquivos devem ser renderizados no cabeçalho do HTML do módulo. 

Restrições de código para módulos independentes

As restrições a seguir se aplicam apenas a módulos independentes:

  • É recomendado usar Vanilla JS sempre que possível. Adicionar uma biblioteca jQuery a um site que não usa jQuery pode causar conflitos e tornar a página mais lenta.
  • Ao usar uma biblioteca jQuery, use a função require_js() para incluir a biblioteca, caso a caixa de seleção (Booleano) para jQuery esteja desmarcada nas configurações do portal, para evitar conflitos de várias bibliotecas. 
{% if not site_settings.include_jquery %} {{ require_js("https://code.jquery.com/jquery-3.7.0.min.js", "footer") }} {% endif %}

Categorias

  • Todos os módulos independentes devem ter pelo menos uma categoria. Os módulos enviados como parte de um tema não precisam ter categorias, mas é recomendado incluir pelo menos uma. Saiba mais sobre como adicionar categorias aos módulos

Seletores de nome de classe

  • Qualquer seletor de nome de classe deve incluir como prefixo o nome do módulo, substituindo espaços por hifens. Por exemplo, abaixo está o arquivo  module.html de um botão chamado  example-button, com cada nome de classe e seletor CSS refletindo seu nome.
<style> {% scope_css %} {# Button wrapper #} {% if module.styles.group_alignment.alignment %} .example-button-wrapper { text-align: {{ module.styles.group_alignment.alignment.horizontal_align }}; } {% endif %} {# Button #} .example-button { {% if module.styles.group_background.color.color %} background-color: rgba({{ module.styles.group_background.color.color|convert_rgb }}, {{ module.styles.group_background.color.opacity / 100 }}); {% endif %} } {% end_scope_css %} </style> {% end_require_css %} {##### Module HTML #####} <div class="example-button-wrapper"> <a href="{{ href }}" class="example-button" {% if module.button_link.open_in_new_tab %}target="_blank"{% endif %} {% if rel %}rel="{{ rel|join(" ") }}"{% endif %} > {{ module.button_text }} </a> </div>

Estilos e JavaScript

  • Estilos:
    • Os módulos devem ter um grupo de estilos não vazio.
    • Não é recomendável codificar estilos inline dentro de módulos. Em vez disso, use estilos inline dinâmicos, permitindo que os campos controlem o estilo.
  • JavaScript:
    • O JavaScript deve poder representar as várias instâncias de um módulo. O Javascript no Painel JS só carregará uma vez por página, independentemente do número de ocorrências do módulo.
    • O Javascript deve fazer referência aos elementos DOM pelos nomes de classe específicos do módulo para garantir que os elementos externos não sejam afetados acidentalmente.
Ao criar módulos, você pode usar uma variável interna chamada LATAM BR (PT) Asset Marketplace | Module requirements. Essa variável obtém o ID da instância do módulo (que pode ser usado somente no painel HTML+HubL) para ajudar na marcação CSS e JS em módulos complexos. Saiba mais sobre isso na documentação para desenvolvedores.

Organização de campo

Os requisitos de organização e agrupamento de campos a seguir devem ser atendidos.

Guia Conteúdo

  • Quando houver pelo menos um controle dentro de um grupo de campos, todos os controles devem ser agrupados em categorias rotuladas por função.
  • Os campos do módulo adicionados à guia Conteúdo devem permitir personalizar o conteúdo de um módulo. Por exemplo, controles para imagem, ícone, texto alternativo e controles de link.

Guia Estilos

Os grupos de campos de estilo do módulo devem ser consistentes e seguir um padrão. Veja abaixo uma ordem recomendada para grupos de campos de estilo. Esses grupos podem estar no nível superior ou aninhados em um grupo. Grupos vazios também podem ser removidos:
  • Predefinições
  • Texto
  • Plano de fundo
  • Borda
  • Passar o mouse
  • Canto
  • Espaçamento
  • Alinhamento
  • Grupos de estilos personalizados que não se encaixam nos itens acima
  • Avançado

Os seguintes tipos de campos devem estar contidos na guia de Estilos, se presente:

Ao mover campos da guia Conteúdo para a guia Estilos, aprenda como usar o mapeamento de alias para preservar o estilo dos módulos que já estão em uso nas páginas ativas.
  • As opções de animação devem estar sempre posicionadas na parte inferior da lista de grupos de campos.
  • As opções que permitem que os criadores de conteúdo adicionem snippets de código ou CSS devem ser agrupadas no final da lista de grupos de campos em um campo rotulado como Avançado
  • Os controles devem ser padronizados em todos os módulos. Por exemplo, todos os elementos que podem ter um controle de raio de borda devem oferecer esse controle. Evite oferecer controles em alguns módulos que estão ausentes em outros.
  • Os campos do módulo adicionados à guia Estilo devem permitir adicionar estilos ao módulo. Por exemplo:
    • Opções de estilo, como cor, estilo de texto, alinhamento, espaçamento, borda e raio de canto.
    • Animações como, por exemplo, efeitos deslizantes e ao passar o mouse.
    • Predefinições como temas escuros e claros que devem alterar muitos estilos ao mesmo tempo.

Exemplos de organização de campo

Predefinições

As predefinições podem ser usadas para fornecer aos criadores de conteúdo um conjunto limitado de opções, muitas vezes vinculadas às configurações do tema. Por exemplo, o módulo Ícone incluído no tema Crescimento contém predefinições para cores EscurasClaras, o que permite manter a consistência quando usado em todo o site. 

Agrupamento multinível

Ao decidir se deseja manter os campos de estilo no nível superior ou aninhá-los, considere o exemplo a seguir.

O módulo Ícone incluído no tema Crescimento lista todos os estilos no nível superior porque trata-se de um componente e, portanto, suas opções de estilo afetam somente ele. 

growth-theme-icon-module

O módulo de Cartão do palestrante incluído no tema Crescimento contém vários componentes: a imagem do cartão e seu conteúdo de texto. Os estilos dos módulos são, portanto, agrupados por componente para que o criador de conteúdo tenha um processo mais claro para aplicar estilos a cada componente.

growth-theme-speaker-card

Agrupamento de campos individuais

O módulo de botão abaixo contém agrupamentos para Predefinições, Texto, Plano de fundo e muito mais. Embora o grupo de campos Canto contenha apenas o controle de raio do canto, ele ainda está agrupado para criar uma experiência de criação de conteúdo uniforme.

module-requirements-2_1button-styles

 

Aliases

O mapeamento de aliases permite criar mapeamentos de campo em um módulo para que você possa mover, renomear ou substituir seus campos sem impactar as páginas que estão usando o módulo. 

Por exemplo, um módulo está sendo usado em uma página ativa. Você deseja mover alguns campos para a guia Estilos, como cor ou fonte, mas um criador de conteúdo já selecionou valores para esses campos no editor. Se você movesse esses campos sem configurar o mapeamento de aliases, o HubSpot não seria capaz de realocar esses campos e eles seriam revertidos para seus valores padrão, o que iria desfazer o estilo na página ativa.

Em vez disso, você pode adicionar uma propriedade aliases_mapping a um campo para mapeá-la para outro. Então, quando um valor não houver sido definido para o campo original, o HubSpot verificará se existe um valor no campo mapeado. Se também não existir nenhum valor no campo mapeado, ele usará o valor padrão. Essa propriedade pode ser usada para mapear valores de campo entre versões diferentes de um módulo somente quando o tipo de dados armazenado do campo antigo for igual ao tipo de dados armazenado do novo campo.

Para um passo a passo visual desse recurso, confira o vídeo abaixo.

Para migrar campos existentes para aliases:

  1. Crie novos campos e mapeie-os para campos antigos usando a propriedade aliases_mapping.
  2. Remova a definição do campo antigo.
  3. Atualize o arquivo module.html para usar a definição dos campos novos.

Observação:

  • Você não pode mapear campos que são de um tipo de dados diferente entre si. Por exemplo, você não pode mapear um campo de gradiente de plano de fundo para um campo de imagem. O valor armazenado tem que ser um valor válido para o tipo do novo campo.
  • Ao criar um novo campo com um mapeamento de alias para um campo antigo, os valores padrão e as propriedades necessárias de ambos os campos devem ser os mesmos.

Veja abaixo exemplos de implementação disso para mudanças simples e complexas:

Implementação simples

Em situações simples, o tipo de campo do campo antigo e o tipo de campo do novo campo devem ser os mesmos. Por exemplo:

  • Campo de cor antigo para novo campo de cor. 
  • Campo de texto antigo para novo campo de texto.
  • Campo de espaçamento antigo para novo campo de espaçamento.

Veja abaixo um exemplo de uso de aliases_mapping ao mover um campo de cor da guia Conteúdo do módulo para a guia Estilos.

Example of a v0 module

[ { "label": "Button Color", "name": "old_button_color_field", "type": "color", "required": true, "default": { "color": "#FFFFFF", "opacity": 100 } } ]

Example of a v1 module

[ { "label": "Styles", "name": "styles", "type": "group", "tab": "STYLE", "children": [ { "label": "Button Color", "name": "new_button_color_field", "type": "color", "required": true, "aliases_mapping": { "property_aliases_paths": { "new_button_color_field": ["old_button_color_field"] } }, "default": { "color": "#FFFFFF", "opacity": 100 } } ] } ]

Complex implementation

Em situações mais complexas, você também pode mapear campos para subcampos ou outros tipos de campo de módulos, desde que o tipo de dados seja o mesmo e o tipo de subcampo do novo campo corresponda. Subcampos são as propriedades dentro do objeto de valor armazenado do campo. Por exemplo:

  • Mapear um campo de Rich text para um campo de Texto, pois os valores em ambos os campos são armazenados como strings.
  • Consolidar campos de tipografia, como mudar de um campo numérico para tamanho de fonte, para usar um campo de fonte (que possui um subcampo de tamanho de fonte). Você pode adicionar um alias para o subcampo de tamanho para mapeá-lo para o campo numérico antigo usando a notação de ponto.

Veja abaixo um exemplo de alteração da opção de tamanho de fonte de um campo numérico para um campo de fonte que possui um subcampo de tamanho de fonte.

Example of a v0 module

[ { "name": "my_number_field", "label": "Number field", "required": false, "locked": false, "display": "text", "step": 1, "type": "number", "min": null, "max": null, "inline_help_text": "", "help_text": "", "default": null } ]

Example of a v1 module

[ { "name": "my_font_field", "label": "font_field", "required": false, "locked": false, "inline_help_text": "", "help_text": "", "load_external_fonts": true, "type": "font", "aliases_mapping": { "property_aliases_paths": { "my_font_field.size": ["my_number_field"] } }, "default": { "size": 12, "font": "Merriweather", "font_set": "GOOGLE", "size_unit": "px", "color": "#000", "styles": {} } } ]

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..