Última modificação: 28 de agosto de 2025
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 igual a 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, geralmente faz sentido que eles sejam agrupados visualmente. Você pode fazer isso criando grupos de campos, que são suportados tanto em módulos quanto em temas. Para criar um grupo de campo localmente, em fields.json crie um objeto com o type de "group". Em seguida, inclua uma matriz children para conter os campos que você deseja agrupar.
simple-field-group-example
[
  {
    "id": "9c00985f-01db-ac5d-73f5-80ed6c0c7863",
    "name": "my_text",
    "display_width": null,
    "label": "Text",
    "required": true,
    "locked": false,
    "validation_regex": "",
    "allow_new_line": false,
    "show_emoji_picker": false,
    "type": "text",
    "default": "Add text here"
  },
  {
    "type": "group",
    "name": "recipe_summary_group",
    "label": "Recipe summary",
    "expanded": true,
    "inline_help_text": "Summarize the recipe (title and description)",
    "children": [
      {
        "type": "text",
        "label": "Recipe title",
        "name": "recipe_title",
        "placeholder": "Burrata salad"
      },
      {
        "type": "text",
        "label": "Recipe description",
        "name": "recipe_description",
        "placeholder": "fig mostarda, hazelnuts, arugula, vincotto, prosciutto, toasted sourdough"
      }
    ]
  }
]
Você pode criar mais agrupamentos de campos dentro de um grupo adicionando outro tipo de objeto "group" dentro do primeiro parâmetro children. Em seguida, construa o grupo de campo da mesma forma que acima, usando children para conter os campos. Você pode aninhar grupos de campos até uma profundidade de três.
field-group-with-secondary-grouping
[
  {
    "type": "group",
    "name": "recipe_summary_group",
    "label": "Recipe summary",
    "inline_help_text": "Summarize the recipe (title and description)",
    "display": "inline",
    "children": [
      {
        "type": "text",
        "label": "Recipe title",
        "name": "recipe_title",
        "placeholder": "Burrata salad"
      },
      {
        "type": "text",
        "label": "Recipe description",
        "name": "recipe_description",
        "placeholder": "fig mostarda, hazelnuts, arugula, vincotto, prosciutto, toasted sourdough"
      },
      {
        "type": "group",
        "name": "secondary_group",
        "label": "Secondary group",
        "expanded": false,
        "children": [
          {
            "name": "bg_color",
            "label": "Background color",
            "sortable": false,
            "required": false,
            "locked": false,
            "type": "color",
            "default": {
              "color": "#ff0000",
              "opacity": 100
            }
          }
        ]
      }
    ]
  }
]

​
Opções de exibição do grupo de campos

Você pode personalizar o seguinte comportamento de exibição do grupo de campos:
  • Expansão: por padrão, os grupos de campos serão exibidos recolhidos no editor. Grupos que contêm grupos aninhados serão exibidos como botões de detalhamento que abrem o grupo em sua própria exibição, com o grupo mais interno exibindo divisores.
default-collapsed-group
  • Tipo de exibição: por padrão, grupos que não contêm grupos aninhados serão exibidos como seções recolhíveis com divisores visuais ao redor de seus filhos. Os grupos que contêm grupos aninhados serão exibidos como botões de detalhamento que abrem o grupo em sua própria exibição, com o grupo mais interno sendo exibido com divisores.
  • Ícone do grupo: se desejar, você pode incluir um ícone Font Awesome que é exibido à esquerda do rótulo.
ícone-exemplo
[
  {
    "type": "group",
    "name": "recipe_summary_group",
    "label": "Recipe summary",
    "display": "drilldown",
    "inline_help_text": "Summarize the recipe (title and description)",
    "icon": {
      "name": "star",
      "set": "fontawesome-5.14.0",
      "type": "SOLID"
    },
    "children": [
      {
        "type": "text",
        "label": "Recipe title",
        "name": "recipe_title",
        "placeholder": "Burrata salad"
      },
      {
        "type": "text",
        "label": "Recipe description",
        "name": "recipe_description",
        "placeholder": "fig mostarda, hazelnuts, arugula, vincotto, prosciutto, toasted sourdough"
      }
    ]
  }
]
ParâmetroTipoDescrição
displayStringO estilo de exibição do grupo de campos. Pode ser um dos seguintes:
  • drilldown: exibe o grupo recolhido com um botão para abrir os filhos do grupo em seu próprio painel. Esta é a exibição padrão para grupos que contêm grupos aninhados.
  • accordion: exibe o grupo recolhido com um botão para expandir os filhos do grupo abaixo como uma seção expansível. Esta é a exibição padrão para grupos sem grupos aninhados.
  • inline: exibe o grupo e seus filhos em linha, sem opção para recolher o grupo.
iconObjetoAdiciona um ícone à esquerda do rótulo. Contém os seguintes parâmetros:
  • name: o identificador de ícone do Font Awesome.
  • set: Font Awesome conjunto de ícones.
  • type: estilo de ícone (por exemplo, SOLID, REGULAR).
expandedBooleanoSe o grupo de campos é expandido por padrão.

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

​
Itens em destaque em grupos de campos

Para situações em que um grupo de campos é repetido, você pode especificar uma ou mais dessas ocorrências como em destaque, permitindo estilizar o item separadamente para destacá-lo. Por exemplo, isso pode ser particularmente útil para uma página de produto na qual você pode ter um produto que deseja destacar. Você pode especificar um número máximo de itens em destaque por grupo de campos. No editor, os criadores de conteúdo podem marcar itens em destaque conforme necessário.
cms-field-group-featured-in-app (1)
Para habilitar itens em destaque em um grupo de campos, inclua a propriedade group_occurrence_meta na configuração do grupo de campos. Esta propriedade armazena as seguintes propriedades:
  • featured_enabled: defina como true para habilitar itens em destaque.
  • featured_limit: o número máximo de itens em destaque permitidos.
O grupo de campos também deve incluir a propriedade occurrence. 
// Field group example
{
  "label": "Card",
  "name": "card",
  "type": "group",
  "occurrence": {
    "default": 2,
    "min": 1,
    "sorting_label_field": "card.title"
  },
  "group_occurrence_meta": {
    "featured_enabled": true,
    "featured_limit": 3
  },
  "children": [
    {
      "label": "Image",
      "name": "image",
      "type": "image",
      "responsive": true,
      "resizable": true,
      "show_loading": true,
      "default": {
        "loading": "lazy"
      }
    },
    {
      "label": "Content",
      "name": "text",
      "type": "richtext",
      "enabled_features": [
        "advanced_emphasis",
        "alignment",
        "block",
        "emoji",
        "font_family",
        "font_size",
        "lists",
        "standard_emphasis"
      ],
      "default": "<h3>This is a title</h3><p>Contextual advertising can be profitable. It can either pay for your hosting and maintenance costs for you website or it can pay for a lot more.</p>"
    }
  ],
  "default": [
    {
      "image": {
        "loading": "lazy"
      },
      "text": "<h3>This is a title</h3><p>Contextual advertising can be profitable. It can either pay for your hosting and maintenance costs for you website or it can pay for a lot more.</p>"
    },
    {
      "image": {
        "loading": "lazy"
      },
      "text": "<h3>This is a title</h3><p>Contextual advertising can be profitable. It can either pay for your hosting and maintenance costs for you website or it can pay for a lot more.</p>"
    }
  ]
}
Para verificar se um item em um grupo repetido deve ser mostrado em destaque, você pode consultar a propriedade hs_meta. O código abaixo usa um loop for para verificar os itens do grupo de campos definidos como em destaque e, em seguida, exibe o título de cada um como um cabeçalho h3. {{ repeated_group_item.hs_meta.occurrence.featured }} 
<div>
  <h2>Check out this week's featured items:</h2>
  <div>
    {% for item in module.card %}
        {% if item.hs_meta.occurrence.featured %}
            <h3>{{item.title}}</h3>
        {% endif %}
    {% endfor %}
  </div>
</div>

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

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

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

"occurrence" : {
    "min" : 1,
    "max" : 4,
    "sorting_label_field" : "ingredients.ingredient",
}
ParâmetroTipoDescriçãoPadrão
maxInteiroNú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
minInteiroNú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_fieldStringEste é 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",
    "property_value_paths" : {
      "font": "module.body_font.font",
      "font_set": "module.body_font.font_set"
    }
  }
}
Como a família de fontes é determinada por uma combinação de font e font_set, você deve incluir ambos para herança de campo de fonte. Saiba mais sobre o campo de fonte.
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 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 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"
  }
ParâmetroTipoDescrição
controlling_field_pathStringO 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 ponto. Por exemplo:
    • field_group_name.field_name
    • parent_group.child_group.field_name
controlling_value_regexStringA 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. 
operatorStringO operador que define como o valor controlling_value_regex deve ser atendido. Os operadores podem ser um dos seguintes:
  • NOT_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX
propertyStringDefine 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.
Você também pode incluir um objeto occurrence_options dentro do objeto visibility para atingir a contagem de valores de um campo repetido. Este objeto deve incluir o count para comparar e uma definição operator. Por exemplo, para mostrar um campo de texto somente quando outro campo repetido tiver pelo menos dois itens, você pode definir visibility do seguinte modo: 
[
  {
    "type": "group",
    "name": "ingredients",
    "label": "Recipe ingredients",
    "display": "drilldown",
    "children": [
      {
        "name": "ingredient",
        "label": "Ingredient",
        "occurrence": {
          "min": 1,
          "max": null,
          "default": 1
        },
        "type": "text",
        "default": ["1 cup water"]
      },
      {
        "type": "text",
        "label": "Conditional field",
        "name": "conditional_field",
        "visibility": {
          "controlling_field_path": "ingredients.ingredient",
          "occurrence_options": {
            "count": 2,
            "operator": "GREATER_THAN_OR_EQUAL"
          }
        }
      }
    ]
  }
]
Você pode usar qualquer um dos seguintes valores operater:
  • "NOT_EQUAL"
  • "EQUAL"
  • "EMPTY"
  • "NOT_EMPTY"
  • "GREATER_THAN"
  • "GREATER_THAN_OR_EQUAL"
  • "LESS_THAN"
  • "LESS_THAN_OR_EQUAL"

​
Visibilidade avançada

O atributo visibility 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"
    }]
}
ParâmetroTipoDescrição
visibility_rulesStringPor padrão, esse valor é definido como SIMPLE. Para usar advanced_visibility, defina como ADVANCED.
boolean_operatorStringO operador booleano para os critérios condicionais. Pode ser AND ou OR.
criteriaMatrizUma matriz de objetos de visibilidade que define os critérios condicionais que precisam ser atendidos para que o campo seja exibido.
controlling_field_pathStringO 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 ponto. Por exemplo:
    • field_group_name.field_name
    • parent_group.child_group.field_name
controlling_value_regexStringO valor no campo de controle que precisa ser atendido para exibir o campo. Ao usar o operador MATCHES_REGEX, o regex deve corresponder à string inteira (não a um subconjunto) e é executado com distinção entre maiúsculas e minúsculas. Um campo com controlling_field_path mas não com controlling_value_regex ficará visível se o campo de controle tiver um valor diferente de nulo que não esteja em branco.
operatorStringO operador que define como o valor controlling_value_regex deve ser atendido. Os operadores podem ser um dos seguintes:
  • NOT_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX
A sintaxe Regex é necessá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 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"
          }
        ]
      }
    }
  }
]
ParâmetroTipoDescrição
messageStringA mensagem a ser exibida no editor de conteúdo quando o campo estiver desabilitado.
rulesObjetoAs condições para habilitar o campo para edição.
criteriaMatrizUma matriz de objetos de condição que define os critérios que precisam ser atendidos para que o campo seja exibido. Esta matriz pode conter vários objetos de condição separados pela lógica AND ou OR por meio do parâmetro boolean_operator.
boolean_operatorStringO operador booleano para os critérios condicionais. Pode ser AND ou OR. Quando não especificado, assume o padrão AND.
controlling_field_pathStringO 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 ponto. Por exemplo:
    • field_group_name.field_name
    • parent_group.child_group.field_name
controlling_value_regexStringO valor no campo de controle que precisa ser atendido para exibir o campo. Ao usar o operador MATCHES_REGEX, o regex deve corresponder à string inteira (não a um subconjunto) e é executado com distinção entre maiúsculas e minúsculas. Um campo com controlling_field_path mas não com controlling_value_regex ficará visível se o campo de controle tiver um valor diferente de nulo que não esteja em branco.
operatorStringO operador que define como o valor controlling_value_regex deve ser atendido. Os operadores podem ser um dos seguintes:
  • NOT_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX
A sintaxe Regex é necessá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 Crescimento 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>
DescriçãoParâmetro
theme-directory-pathO 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).