Visão geral dos campos de módulo e tema

Last updated:

Nos módulos e temas, os campos são usados para permitir que os criadores de conteúdo controlem o estilo e a funcionalidade de módulos e temas em seu site. Ao desenvolver um módulo ou tema, você incluirá campos em um arquivo fields.json, que será traduzido para os editores de tema e conteúdo.

theme-settings-fields

Saiba mais sobre como criar e gerenciar opções para campos de módulo e tema. Para saber mais sobre tipos de campos específicos, confira o guia de referência de tipos de módulos e campos. 

Criar e gerenciar campos

Você pode adicionar campos ao arquivo fields.json de um módulo localmente através da CLI do HubSpot e no editor de módulos no aplicativo. Para adicionar campos a um tema, você deve atualizar o arquivo fields.json do tema localmente usando a CLI. 

CLI da HubSpot

Ao desenvolver localmente, os campos de módulo e tema podem ser editados no arquivo fields.json dentro da pasta do módulo ou tema. Para os módulos, esse arquivo será criado automaticamente ao usar o comando hs create module. Todas as opções de campo disponíveis no editor de módulo estão disponíveis como propriedades que você pode adicionar ou editar no arquivo fields.json. Isso inclui campos repetidores, grupos e condições. Um dos benefícios da edição local é que ela facilita a inclusão de módulos em sistemas de controle de versão como o git.

Editor de módulo

O gerenciador de design tem uma IU de editor de módulos incorporado que permite criar, agrupar e editar campos de módulo. O editor de módulos contém uma visualização do módulo que permite ver a aparência do módulo, bem como testar seus campos. Como os módulos não vivem no vácuo, você deve sempre testá-los no modelo que planeja usar para ver quais estilos em nível de modelo podem afetá-lo. Saiba que, se um módulo estiver contido em uma pasta bloqueada, ele não poderá ser editado desta forma.

Editor de módulos do gerenciador de design

Observação: se você trabalha localmente na maior parte do tempo, mas quer usar o editor de módulo para configurar os campos, certifique-se de buscar suas alterações. Isso é especialmente importante para quem usa sistemas de controle de versão como o git.

Campos lado a lado

Por padrão, os campos dos módulos nos editores de conteúdo são empilhados verticalmente. No entanto, você pode exibir os campos do módulo lado a lado adicionando uma propriedade display_width aos campos no arquivo fields.json com um valor de half_width. 

side-by-side-modules0

Um único campo com display_width de half_width aparecerá como meia-largura no editor de conteúdo. Quando o campo acima ou abaixo desse campo no arquivo fields.json estiver definido para half_width, ele será exibido lado a lado.

// Example module fields.json file [ { "name": "number_field", "label": "Number", "required": false, "locked": false, "display": "slider", "min": 1, "max": 10, "step": 1, "type": "number", "prefix": "", "suffix": "", "default": null, "display_width":"half_width" }, { "label": "Description", "name": "description", "type": "text", "required": true, "default": "Add a description", "display_width": "half_width" } ]

Grupos de campos

Quando os campos estão relacionados entre si, muitas vezes faz sentido que sejam exibidos agrupados visualmente. Módulos e Temas suportam o agrupamento de vários campos. 

Grupo de campos sem grupos de campos aninhados

Grupos de campos sem grupos de campos aninhados são exibidos basicamente com divisores acima e abaixo do grupo, sendo que o rótulo é exibido na parte superior do grupo.

Grupo de campos aninhados

Os grupos de campos podem ser aninhados. Um grupo de campos que contenha outro grupo de campos será exibido como um botão. Clicar no botão para ver o grupo mostrará o conteúdo desse grupo.

Os grupos de campos podem ser agrupados com três níveis de profundidade. Ou seja, os campos dos módulos podem ter quatro níveis de profundidade, o que facilita a criação de interfaces de usuário que expressam relações de campo e apresentam profundidade mais granular.

Grupos de campo em fields.json

Os objetos de grupos de campos podem ser listados como secundários a outros grupos de campos. Sua estrutura é muito semelhante à dos próprios campos, sendo o único parâmetro especial o parâmetro "children", que é o conjunto de campos e grupos que eles contêm.

// Field group example { "type": "group", "name": "typography", "label": "Typography", "expanded": true, "children": [ { "type": "font", "name": "h1_font", "label": "Heading 1", "load_external_fonts": true, "default": { "color": "#000", "font": "Merriweather", "font_set": "GOOGLE", "variant": "700", "size": "48" } } ] } // Field group inside of a field group { "type": "group", "name": "header", "label": "Header", "children": [ { "type": "font", "name": "h1_font", "label": "Heading 1", "load_external_fonts": true, "default": { "color": "#000", "font": "Merriweather", "font_set": "GOOGLE", "variant": "700", "size": "48" } { "type": "group", "name": "navigation", "label": "Navigation", "expanded": false, "children": [ { "name" : "bg_color", "label" : "Background color", "sortable" : false, "required" : false, "locked" : false, "type" : "color", "default" : { "color" : "#ff0000", "opacity" : 100 } } ] } } ] }

Expandir os grupos de campo por padrão

Grupos de campos podem ser definidos para serem expandidos por padrão configurando a propriedade booleana expanded para true nas propriedades do grupo fields.json, como mostrado no código do exemplo acima. Os grupos de campos não são expandidos por padrão e, ao utilizar grupos de campos aninhados, o grupo principal não pode usar essa propriedade.

Emitir valores de campo dentro de grupos de campos

Os grupos de campos criam dicionários que contêm os valores de campo que se deseja emitir. Se você aninhar grupos de campos, o grupo de campos aninhados será um dicionário dentro do dicionário do grupo de campos externo. Para acessar esses dados, você precisará percorrer a árvore a partir do tema raiz ou da variável do módulo, dependendo do contexto.

<div> {# printing a value from a field group `recipe_summary` is the field group, `title` is the text field. #} {{module.recipe_summary.title}} </div>/* Printing a Font field's color value, when the font field is within a field group. `typography` is the field group, `h1_font` is the field */ h1{ color: {{ theme.typography.h1_font.color }}; }

Campos de estilo

Campos de estilo são um tipo especial de grupo de campos em um módulo ou arquivo fields.json do tema que fornece aos criadores de conteúdo controle sobre o estilo de um módulo ou tema na página e no editor de temas. Abaixo, saiba como adicionar campos de estilo para um módulo ou tema. Conheça as práticas recomendadas para a utilização e organização de campos de estilo.

Campos de estilo de módulo

Os campos de estilo adicionados a um módulo aparecerão na guia Estilos do editor de páginas ao editar o módulo:

style-field-module-editor0

Ao adicionar campos de estilo ao arquivo fields.json de um módulo, você os adiciona dentro de um grupo de estilos. Esse grupo, no entanto, pode conter vários grupos, como mostrado abaixo:

// Module style fields [ { "type": "group", "name": "styles", "tab": "STYLE", "children": [{ "name": "img_spacing", "label": "Spacing around image", "required": false, "type": "spacing", "default": { "padding": { "top": { "value": 10, "units": "px" }, "bottom": { "value": 10, "units": "px" }, "left": { "value": 10, "units": "px" }, "right": { "value": 10, "units": "px" } }, "margin": { "top": { "value": 10, "units": "px" }, "bottom": { "value": 10, "units": "px" } } } }] } ]

Os seguintes campos podem ser usados como campos de estilo nos módulos. Saiba mais sobre cada um dos tipos de campo no guia de tipos de campos e módulos.

Saiba mais sobre os tipos de campos de módulo e tema.

Consulte o boilerplate do CMS para ver um exemplo de campos de estilo dentro do arquivo fields.json de um módulo.

Campos de estilo do tema

Os campos de estilo adicionados a um tema aparecerão na barra lateral esquerda do editor de temas:

style-field-theme-editor0

Todos os campos de estilo dentro do arquivo fields.json de um tema serão adicionados à barra lateral esquerda do editor de temas, ao invés de precisar colocá-los sob um grupo de estilos, como mostrado abaixo:

// Theme style fields [ { "label": "Global colors", "name": "global_colors", "type": "group", "children": [ { "label": "Primary", "name": "primary", "type": "color", "visibility": { "hidden_subfields": { "opacity": true } }, "default": { "color": "#494A52" } }, { "label": "Secondary", "name": "secondary", "type": "color", "visibility": { "hidden_subfields": { "opacity": true } }, "default": { "color": "#F8FAFC" } } ] }, { "label": "Global fonts", "name": "global_fonts", "type": "group", "children": [ { "label": "Primary", "name": "primary", "type": "font", "visibility": { "hidden_subfields": { "size": true, "styles": true } }, "inherited_value": { "property_value_paths": { "color": "theme.global_colors.primary.color" } }, "default": { "fallback": "sans-serif", "font": "Lato", "font_set": "GOOGLE" } }, { "label": "Secondary", "name": "secondary", "type": "font", "visibility": { "hidden_subfields": { "size": true, "styles": true } }, "inherited_value": { "property_value_paths": { "color": "theme.global_colors.primary.color" } }, "default": { "fallback": "serif", "font": "Merriweather", "font_set": "GOOGLE" } } ] }, { "name": "branding_color", "label": "branding_color", "type": "color", "default": { "color": "#3b7bc0", "opacity": 60 }, "inherited_value": { "property_value_paths": { "color": "brand_settings.primaryColor" } } }, { "name": "secondary_branding_color", "label": "Secondary Branding color", "type": "color", "default": { "color": "#ff6b6b", "opacity": 60 }, "inherited_value": { "property_value_paths": { "color": "brand_settings.colors[2]" } } } ] } ]

Os seguintes campos podem ser usados como campos de estilo nos módulos. Saiba mais sobre cada um dos tipos de campo no guia de tipos de campos e módulos.

Saiba mais sobre os tipos de campos de módulo e tema.

Consulte o boilerplate do CMS para ver um exemplo de campos de estilo dentro do arquivo fields.json de um tema. 

Observação: se você é um provedor de marketplace, não substitua os campos de conteúdo existentes por campos de estilo nos módulos existentes. A modificação da hierarquia dos campos em um arquivo fields.json pode resultar na perda de dados de instâncias de módulos existentes. Em vez disso, você deve adicionar novos campos de estilo, ou criar uma nova listagem que tenha os campos devidamente agrupados. Isso evitará que as suas atualizações sejam um problema para os clientes que utilizam os seus temas. Para promover caminhos de migração para módulos antigos, confira o fórum de ideias da HubSpot.

CSS gerado

Alguns campos de estilo permitem gerar o css diretamente com base no valor do campo. Isso é especialmente útil em campos que podem controlar estilos mais complexos, como gradientes. Os seguintes campos de estilo têm uma propriedade .css gerada:

{% require_css %} <style> {% scope_css %} .team-member { {% if module.style.gradient.css %} background: {{ module.style.gradient.css }}; {% endif %} {{ module.style.bg_img.css }} {{ module.style.spacing.css }} {{ module.style.border.css }} } {% end_scope_css %} </style> {% end_require_css %}

Repetidores

Ao criar módulos que formatam informações, muitas vezes há tipos de informações que se repetem. Um módulo de receita, por exemplo, pode ter um campo para "Ingredientes". Bem, a maioria das receitas inclui mais de um ingrediente. Você poderia fornecer um campo rich text, mas perderia a capacidade de forçar um estilo consistente e de adicionar funcionalidade sobre cada ingrediente. Por isso, os repetidores são usados. O HubSpot tem duas formas de repetidores: Campos de repetição e Grupos de repetição.

Campos de repetição

Campos de repetição são campos normais, mas nos quais os criadores de conteúdo podem adicionar, remover e reorganizar instâncias. Usando o exemplo do módulo de receita acima, cada ingrediente pode ser um campo de texto de repetição. 

repeater field

Isso faz com que o criador de conteúdo possa adicionar tantos ingredientes quanto quiser. Do ponto de vista do desenvolvedor, você obtém uma matriz que pode ser analisada para imprimir essa lista de ingredientes, aplicando a formatação e a funcionalidade desejada. 

Os campos de repetição são melhor utilizados em situações muito simples. Muitas vezes, faz mais sentido usar grupos de repetição.

Observação: não é possível definir a ordem padrão dos campos de repetição.

Campos de repetição em fields.json

// Repeating field example { "name" : "ingredient", "label" : "Ingredient", "required" : false, "locked" : false, "occurrence" : { "min" : 1, "max" : null, "sorting_label_field" : null, "default" : 1 }, "allow_new_line" : false, "show_emoji_picker" : true, "type" : "text", "default" : [ "1 cup water" ] }

Executar itens em loop no módulo HTML+HubL

<!--Looping through a repeating field--> <ul> {% for item in module.ingredient %} <li>{{ item }}</li> {% endfor %} </ul>

Grupos de repetição

Os grupos de repetição são grupos de campo com a opção de repetição ativada. Os grupos de repetição permitem aos criadores de conteúdo adicionar, remover e reorganizar grupos de campos. Usando como exemplo o módulo de receitas, suponha que você queira integrar na sua lista de ingredientes uma funcionalidade de lista de compras.

Repetição de grupos de campos

A quantidade de um ingrediente seria fundamental na lista de compras. Mesmo que alguém fornecesse isso no campo de texto, o módulo precisaria analisar o campo de texto, na esperança de separar com sucesso a quantidade do ingrediente. É aqui que entram os grupos de repetição. A saída desses campos é um objeto que pode ser executado em loop.

Grupos de repetição em fields.json

// Repeating field group example { "id" : "ingredients", "name" : "ingredients", "label" : "Ingredients", "required" : false, "locked" : false, "occurrence" : { "min" : 1, "max" : null, "sorting_label_field" : "ingredients.ingredient", "default" : null }, "children" : [ { "id" : "ingredients.ingredient", "name" : "ingredient", "label" : "Ingredient", "required" : false, "locked" : false, "validation_regex" : "", "allow_new_line" : false, "show_emoji_picker" : false, "type" : "text", "default" : "Water" }, { "id" : "ingredients.quantity", "name" : "quantity", "label" : "Quantity", "required" : false, "locked" : false, "display" : "text", "min" : 0, "step" : 1, "type" : "number", "default" : 1 }, { "id" : "ingredients.measurement", "name" : "measurement", "label" : "Measurement", "help_text" : "Unit of measurement (cups, tbsp, etc.)", "required" : false, "locked" : false, "allow_new_line" : false, "show_emoji_picker" : false, "type" : "text", "default" : "cups" } ], "type" : "group", "default" : [ { "ingredient" : "Water", "quantity" : 1, "measurement" : "cups" } ] }

Executar campos de repetição em loop nos módulos

<h2>Ingredients</h2> <ul> {% for ingredient in module.ingredients %} <li> <button data-quantity="{{ ingredient.quantity }}" data-unit="{{ ingredient.measurement }}" data-ingredient="{{ ingredient.ingredient }}"> Add to cart </button> {{ ingredient.quantity }} {{ ingredient.measurement }} {{ ingredient.ingredient }} </li> {% endfor %} </ul>

Opções de repetidores

Para melhorar a experiência de edição e evitar que os editores de conteúdo forneçam valores que você não tenha programado, permitimos definir valores mínimos e máximos para o número de itens que os criadores de conteúdo podem adicionar a um campo ou grupo de repetição. 

Para os grupos de repetição, você também pode definir qual campo atua como rótulo para aquele item ao visualizar o repetidor.

Número máximo de ocorrências
"occurrence" : { "min" : 1, "max" : 4, "sorting_label_field" : "ingredients.ingredient", }
Opções de repetidores
ParameterTypeDescription Default
max
Inteiro

Número máximo de ocorrências deste grupo. Evita que o criador do conteúdo adicione mais do que este número de itens na IU.

 null
min
Inteiro

Número mínimo de ocorrências deste grupo de campos. Evita que os usuários tenham menos do que este número de itens na IU.

 null
sorting_label_field
String

Este é o ID do campo do qual obter o texto para mostrar na IU nos cartões arrastáveis. A configuração padrão é o primeiro campo do grupo.

Campos herdados

A propriedade inherited_value pode ser configurada para fazer com que um campo herde seu valor padrão de outros campos. Para definir o valor padrão de um campo a partir do valor de outro campo, defina default_value_path para o caminho do nome do campo de destino. Se default_value_path estiver definido, qualquer default definido no campo será ignorado.

Para acessar os valores de outros campos, os caminhos devem incluir o prefixo  module., como se você estivesse acessando o valor no código HubL do módulo.

// Inherited fields { "name": "body_font", "type": "font", "default": { "font": "Helvetica", "color": "#C27BA0" } }, { "name": "h1_font", "type": "font", "default": {}, "inherited_value": { "default_value_path": "module.body_font" } }

Para campos complexos (campos cujos valores são objetos), os usuários podem ter mais granularidade sobre quais propriedades são herdadas por meio de property_value_path. Quaisquer caminhos referidos em inherited_value também podem incluir chaves do valor de um campo para campos complexos — por exemplo, campos de cor têm valores de objeto que contêm a própria cor, bem como a opacidade. Para obter o valor real da cor sem a opacidade, o caminho terminaria em .color. Por exemplo, um campo de fonte pode herdar apenas a sua cor de um campo de cor separado:

// Inherited fields with objects { "name": "secondary_color", "type": "color", "default": { "color": "#C27BA0", "opacity": 100 } }, { "name": "h1_font", "type": "font", "default": { "font": "Helvetica", "size": 12, "size_unit": "px" }, "inherited_value": { "property_value_paths": { "color": "module.secondary_color.color" } } }

Você também pode combinar os efeitos def default_value_path e property_value_paths para herdar um valor padrão de um campo enquanto herda um valor de propriedade específico de outro campo:

// combining the effects of default_value_path and property_value_paths { "name": "body_font", "type": "font", "default": { "font": "Helvetica", "color": "#000000" } }, { "name": "secondary_color", "type": "color", "default": { "color": "#C27BA0", "opacity": 100 } }, { "name": "h1_font", "type": "font", "default": {}, "inherited_value": { "default_value_path": "module.body_font", "property_value_paths": { "color": "module.secondary_color.color" } } }

Se um campo é herdado de outro campo mas depois é diretamente substituído no nível da página ou nas configurações do tema, a conexão com o campo de controle é desfeita. Quaisquer outros campos anexados por meio de default_value_path ou property_value_paths não afetarão mais o valor do campo.

Visibilidade do campo

Ao definir campos de módulo e tema personalizados, você pode configurar quando um campo é exibido, adicionando o objeto de visibility ao campo no arquivo fields.json. Por exemplo, você pode definir um módulo de formulário para exibir uma área de rich text quando a mensagem de agradecimento for selecionada, mas um seletor de página quando um redirecionamento for selecionado.

Você pode definir a visibilidade com base no valor de um controlling_field_path ou em uma propriedade específica dentro desse campo usando o parâmetro property.

Você também pode aplicar a visibilidade a um campo individual ou a um grupo de campos para controlar a visibilidade de todos os elementos no grupo.

"visibility" : { "controlling_field_path" : "field_name", "controlling_value_regex" : "regular_expression_in_controlling_field", "property": "src", "operator" : "EQUAL" }
Use this table to describe parameters / fields
ParameterTypeDescription
controlling_field_path
String

O caminho doth do campo que controla a condição de exibição.

  • Se o campo não estiver aninhado dentro de um grupo de campos, use o nome do campo (ou seja, field_name).
  • Para campos aninhados em grupos, o caminho deve corresponder à sua estrutura de agrupamento, separada por um período. Por exemplo:
    • field_group_name.field_name
    • parent_group.child_group.field_name
controlling_value_regex
String

A expressão regular no campo de controle que precisa estar presente para o campo ser exibido. A regex deve corresponder a toda a string (não a um subconjunto) e será executada diferenciando letras maiúsculas de minúsculas. 

operator
String

O operador que define como o valor controlling_value_regex precisa ser atendido. Os operadores podem ser um dos seguintes: 

  • NOT_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX
property
String

Define a visibilidade com base em uma propriedade específica do campo de destino. Por exemplo, você pode ativar a visibilidade quando a propriedade src de um campo de imagem for igual a um valor específico. Por padrão, se nenhum valor for fornecido para esse campo, a visibilidade será baseada no valor de controlling_value_regex da string.

O atributo de visibilidade pode suportar apenas um critério por vez. Para incluir vários critérios com vários operadores, bem como a ordem das operações, você pode usar advanced_visibility.

"visibility_rules" : "ADVANCED", "advanced_visibility" : { "boolean_operator" : "AND", "criteria" : [{ "controlling_field_path" : "field_name", "controlling_value_regex" : "regular_expression_in_controlling_field", "operator" : "MATCHES_REGEX" }, { "controlling_field_path" : "field_name", "controlling_value_regex" : "regular_expression_in_controlling_field", "operator" : "EQUAL" }] }
Use this table to describe parameters / fields
ParameterTypeDescription
visibility_rules
String

Por padrão, esse valor é definido como SIMPLE. Para usar a advanced_visibility, defina como ADVANCED.

boolean_operator
String

O operador booleano para os critérios condicionais. Pode ser AND ou OR.

criteria
Array

Uma matriz de objetos de visibilidade que define os critérios condicionais que precisam ser atendidos para que o campo seja exibido.

controlling_field_path
String

O caminho separado por ponto do campo que controla a condição de exibição.

  • Se o campo não estiver aninhado dentro de um grupo de campos, use o nome do campo (ou seja, field_name).
  • Para campos aninhados em grupos, o caminho deve corresponder à sua estrutura de agrupamento, separada por um período. Por exemplo:
    • field_group_name.field_name
    • parent_group.child_group.field_name
controlling_value_regex
String

O valor no campo de controle que precisa ser atendido para exibir o campo. Ao usar o operador MATCHES_REGEX, a regex deve corresponder à string inteira (não a um subconjunto) e será executada diferenciando letras maiúsculas de minúsculas.

Um campo com um controlling_field_path, mas sem controlling_value_regex, é visível se o campo de controle tiver qualquer valor não nulo e não em branco.

operator
String

O operador que define como o valor controlling_value_regex precisa ser atendido. Os operadores podem ser um dos seguintes: 

  • NOT_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX

A sintaxe de regex é obrigatória ao usar MATCHES_REGEX.

Por exemplo, a seguir está a primeira parte do código do módulo de pagamentos padrão. Para revisar o código completo, você pode clonar o módulo no HubSpot e baixá-lo para seu ambiente local para visualizar o arquivo de fields.json do módulo.

[ { "id" : "payment", "name" : "payment", "display_width" : null, "label" : "Payment", "required" : true, "locked" : false, "type" : "payment", "default" : { "id" : null, "properties" : { } } }, { "id" : "checkout_location", "name" : "checkout_location", "display_width" : null, "label" : "Checkout behavior", "required" : false, "locked" : false, "visibility" : { "controlling_field_path" : "payment", "controlling_value_regex" : "id\":\\d+", "operator" : "MATCHES_REGEX" }, "display" : "radio", "choices" : [ [ "new_tab", "Open in a new tab" ], [ "overlay", "Sliding overlay" ] ], "type" : "choice", "default" : "new_tab" }, { "id" : "button_text", "name" : "button_text", "display_width" : null, "label" : "Button text", "required" : true, "locked" : false, "validation_regex" : "", "visibility" : { "controlling_field_path" : "payment", "controlling_value_regex" : "id\":\\d+", "operator" : "MATCHES_REGEX" }, "allow_new_line" : false, "show_emoji_picker" : false, "type" : "text", "default" : "Checkout" }, { "id" : "icon", "name" : "icon", "display_width" : null, "label" : "Icon", "required" : false, "locked" : false, "visibility_rules" : "ADVANCED", "advanced_visibility" : { "boolean_operator" : "AND", "criteria" : [ { "controlling_field_path" : "payment", "controlling_value_regex" : "id\":\\d+", "operator" : "MATCHES_REGEX" }, { "controlling_field_path" : "add_icon", "controlling_value_regex" : "true", "operator" : "EQUAL" } ], "children" : [ ] }, "children" : [ { "id" : "icon.icon", "name" : "icon", "display_width" : null, "label" : "Icon", "required" : true, "locked" : false, "icon_set" : "fontawesome-5.0.10", "type" : "icon", "default" : { "name" : "hubspot", "type" : "SOLID", "unicode" : "f3b2" } }, { "id" : "icon.position", "name" : "position", "display_width" : null, "label" : "Position", "required" : true, "locked" : false, "display" : "select", "choices" : [ [ "left", "Left" ], [ "right", "Right" ] ], "type" : "choice", "default" : "left" } ], "tab" : "CONTENT", "expanded" : false, "type" : "group" }, // rest of fields.json code ]

O código acima resulta no seguinte comportamento:

  • O primeiro campo (payment) é um campo obrigatório (menu suspenso), que permite ao criador de conteúdo selecionar um link de pagamento específico. No HubSpot, um criador de conteúdo verá o seguinte ao adicionar o módulo à página pela primeira vez:

payment-link-selector

  • Quando um link de pagamento for selecionado, os três campos a seguir (checkout_location, button_text e icon) serão exibidos. Isso ocorre porque os campos têm um atributo de visibility que é controlado pelo campo de payment e exige um valor de ID no parâmetro de id do campo de pagamento.

O próprio campo de icon usa a advanced_visibility para ser exibido somente quando houver um link de pagamento presente no campo de payment E quando a caixa de seleção add_icon estiver selecionada.

Além de definir a visibilidade dentro de fields.json, também é possível fazer isso no gerenciador de design, editando as opções de Condições de exibição de um campo.
display-conditions-property

Depois de definir a visibilidade no gerenciador de design, você pode buscar o módulo usando a CLI para exibir o atributo de visibility no arquivo fields.json do módulo.

Desativação de campo condicional

Você pode adicionar condições a um campo para impedir a edição quando as condições especificadas forem atendidas. Você também pode definir uma mensagem para exibir acima do campo quando este estiver desativado para fornecer contexto no editor de conteúdo. 

Captura de tela 2023-05-23 às 16:10:28

As condições e a mensagens são definidas no objeto disabled_controls. As condições para tornar um campo editável são definidas no objeto rules, que segue o mesmo formato de advanced_visibility.

O código abaixo mostra uma implementação simples e avançada dos critérios rules:

  • O campo simple_page inclui lógica para ser desativado se o campo text_field estiver definido como testing.
  • O campo fancy_page inclui lógica para ser desativado se text_field ou text_field_2 estiver definido como qualquer valor diferente de testing e testing2, respectivamente.
// example fields.json [ { "type": "text", "name": "text_field", "label": "Text field", }, { "type": "text", "name": "text_field_2", "label": "Text field 2", }, { "type": "page", "label": "Simple Page", "name": "simple_page", "disabled_controls": { "message": "This field is disabled", "rules": { "criteria": [ { "controlling_field_path": "text_field", "operator" :"EQUAL", "controlling_value_regex": "testing" } ] } } }, { "type": "page", "label": "Fancy Page", "name": "fancy_page", "disabled_controls": { "message": "This field is disabled", "rules": { "boolean_operator": "OR", "criteria": [ { "controlling_field_path": "text_field", "operator" :"NOT_EQUAL", "controlling_value_regex": "testing" }, { "controlling_field_path": "text_field_2", "operator" :"NOT_EQUAL", "controlling_value_regex": "testing2" }, ] } } } ]
Use this table to describe parameters / fields
ParameterTypeDescription
message
String

A mensagem a ser exibida no editor de conteúdo quando o campo estiver desabilitado.

rules
Objeto

As condições para habilitar o campo para edição.

criteria
Array

Um array de objetos de condição que define os critérios que precisam ser atendidos para que o campo seja exibido. Este array pode conter vários objetos de condição separados pela lógica AND ou OR por meio do parâmetro boolean_operator.

boolean_operator
String

O operador booleano para os critérios condicionais. Pode ser AND ou OR. Quando não especificado, assume o padrão AND.

controlling_field_path
String

O caminho separado por ponto do campo que controla a condição de exibição.

  • Se o campo não estiver aninhado dentro de um grupo de campos, use o nome do campo (ou seja, field_name).
  • Para campos aninhados em grupos, o caminho deve corresponder à sua estrutura de agrupamento, separada por um período. Por exemplo:
    • field_group_name.field_name
    • parent_group.child_group.field_name
controlling_value_regex
String

O valor no campo de controle que precisa ser atendido para exibir o campo. Ao usar o operador MATCHES_REGEX, a regex deve corresponder à string inteira (não a um subconjunto) e será executada diferenciando letras maiúsculas de minúsculas.

Um campo com um controlling_field_path, mas sem controlling_value_regex, é visível se o campo de controle tiver qualquer valor não nulo e não em branco.

operator
String

O operador que define como o valor controlling_value_regex precisa ser atendido. Os operadores podem ser um dos seguintes: 

  • NOT_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX

A sintaxe de regex é obrigatória ao usar MATCHES_REGEX.

Destaque de campos no editor de temas

No editor de temas, o recurso de destaque pode ajudar os criadores de conteúdo a entender quais campos controlam os elementos da página. O recurso de destaque funciona mapeando os campos do tema aos seletores CSS que eles afetam, adicionando uma caixa em torno desses elementos ao passar o mouse sobre o campo no editor de temas.

Para configurar o recurso de destaque para campos de tema, você inclui um arquivo editor-preview.json no diretório raiz do tema para mapear os campos a uma lista de seletores CSS. No arquivo, você incluirá uma matriz para cada campo de estilo que deseja destacar e que contém os seletores CSS relevantes, usando o seguinte formato:

// editor-preview.json { "selectors": { "theme.settings.path.1": [ <CSS selectors> ], "theme.settings.path.2": [ <CSS selectors> ], } }

Por exemplo, o código abaixo destacará os elementos da página que são controlados pelo campo de fonte principal. Você pode visualizar o exemplo completo no arquivo editor-preview.json do tema Growth padrão.

// editor-preview.json { "selectors": { "fonts.primary": [ "button, .button, .hs-button", "form input[type='submit'], form .hs-button", ".error-page:before", "p", "blockquote > footer", "form td.is-today .pika-button", "form .is-selected .pika-button", "th, td", ".blog-listing__post-tag", ".blog-listing__post-author-name, .blog-post__author-name", ".pagination__link-icon svg", ".tabs__tab", "a", ".button.button--simple", ".pagination__link .pagination__link-icon svg", ".card--dark", ".card--light", ".card--light summary, .card--light p, .card--light h1, .card--light h2, .card--light h3, .card--light h4, .card--light h5, .card--light h6, .card--light a:not(.button), .card--light span, .card--light div, .card--light li, .card--light blockquote", ".card--light .accordion__summary:before", "tfoot th, tfoot td", ".header__language-switcher-current-label > span", ".header__language-switcher-child-toggle svg", ".header__language-switcher .lang_list_class a:not(.button)", ".header__menu-link", ".header__menu-item--depth-1 > .header__menu-link:not(.button)", ".header__menu-item--depth-1 .header__menu-child-toggle svg", ".header__menu-toggle svg", ".header__language-switcher .header__language-switcher-current-label > span", ".header p, .header h1, .header h2, .header h3, .header h4, .header h5, .header h6, .header a:not(.button), .header span, .header li, .header blockquote, .header .tabs__tab, .header .tabs__tab, .header .tabs__tab, .header .tabs__tab", ".footer .hs-menu-wrapper a", ".footer h1, .footer h2, .footer h3, .footer h4, .footer h5, .footer h6, .footer p, .footer a:not(.button), .footer span, .footer div, .footer li, .footer blockquote, .footer .tabs__tab, .footer .tabs__tab, .footer .tabs__tab, .footer .tabs__tab", ".footer hr", "form label", "#email-prefs-form, #email-prefs-form h1, #email-prefs-form h2", "form legend", "form input[type='text'], form input[type='email'], form input[type='password'], form input[type='tel'], form input[type='number'], form input[type='search'], form select, form textarea", ".backup-unsubscribe input[type='email']", "form .legal-consent-container, form .legal-consent-container .hs-richtext, form .legal-consent-container .hs-richtext p", "form .hs-richtext, form .hs-richtext *, form .hs-richtext p, form .hs-richtext h1, form .hs-richtext h2, form .hs-richtext h3, form .hs-richtext h4, form .hs-richtext h5, form .hs-richtext h6", "button, button, button, .button, .button, .button, .hs-button, .hs-button, .hs-button", "button, .button, .hs-button", ".button.button--secondary, .button.button--secondary, .button.button--secondary", ".button.button--secondary", ".header__menu-item--depth-1 > .header__menu-link, .header__menu-item--depth-1 > .header__menu-link", ".header__menu-item--depth-1 > .header__menu-link", ".header__menu-submenu .header__menu-link, .header__menu-submenu .header__menu-link", ".header__language-switcher .lang_list_class a, .header__language-switcher .lang_list_class a", ".header__menu-submenu .header__menu-link:not(.button)", ".footer .hs-menu-wrapper a, .footer .hs-menu-wrapper a", ".footer .hs-menu-wrapper a", "form .hs-richtext a", ".header__menu-item--depth-1 > .header__menu-link--active-link:not(.button)", ".footer .hs-menu-wrapper .active > a" ] } }

growth-theme-hover

Para começar a gerar esse arquivo, execute o comando da CLI a seguir para criar o arquivo. Durante a criação do arquivo, um script será executado para configurar os mapeamentos iniciais dos seletores de campo.

hs theme generate-selectors <theme-directory-path>
ParameterDescription
theme-directory-path

O caminho para o diretório de temas.

Depois de executar o comando, você precisará revisar e refinar o arquivo editor-preview.json para garantir que os campos e os seletores sejam mapeados corretamente. Embora o comando generate-selectors faça uma suposição rudimentar sobre os campos que afetam os seletores, você precisará fazer correções com base em como seu tema é construído. Por exemplo, este comando não detecta quando os módulos substituem o estilo ou quando você usa macros.

Para testar esses mapeamentos, carregue o tema em uma conta e exiba o editor de temas nessa conta (Configurações > Site > Temas > Exibir tema). 

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