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.
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.
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.
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.
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.
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.
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
.
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"
}
]
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.
xxxxxxxxxx
[
{
"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, proscuitto, 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.
xxxxxxxxxx
[
{
"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, proscuitto, 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
}
}
]
}
]
}
]
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.
- 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.
- Rótulos de grupo: para grupos de detalhamento, você pode substituir o rótulo do grupo para exibi-lo maior com um divisor abaixo.
- Ícone do grupo: se desejar, você pode incluir um ícone Font Awesome que é exibido à esquerda do rótulo.
xxxxxxxxxx
[
{
"type": "group",
"name": "recipe_summary_group",
"label": "Recipe summary",
"display": "drilldown",
"use_large_label": true,
"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, proscuitto, toasted sourdough"
}
]
}
]
Parâmetro | Tipo | Descrição |
---|---|---|
display | String | O estilo de exibição do grupo de campos. Pode ser um dos seguintes:
|
use_large_label | Booleano | Se o rótulo deve ser ampliado para criar uma hierarquia visual mais distinta. O texto de ajuda embutido será exibido abaixo do rótulo como texto pequeno, em vez de uma caixa de alerta. |
icon | Objeto | Adiciona um ícone à esquerda do rótulo. Contém os seguintes parâmetros:
|
expanded | Booleano | Se o grupo de campos é expandido por padrão. |
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.
xxxxxxxxxx
<div>
{# printing a value from a field group `recipe_summary` is the field group,
`title` is the text field. #} {{module.recipe_summary.title}}
</div>
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.
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 comotrue
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
.
xxxxxxxxxx
// 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 }}
xxxxxxxxxx
<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 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.
Os campos de estilo adicionados a um módulo aparecerão na guia Estilos do editor de páginas ao editar o módulo:
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:
xxxxxxxxxx
// 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.
- Alinhamento
- Gradiente
- Espaçamento
- Imagem de fundo
- Borda
- Booleano
- Escolha
- Número
- Cor
- Ícone
- Imagem
- Fonte
- Alinhamento de texto
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.
Os campos de estilo adicionados a um tema aparecerão na barra lateral esquerda do editor de temas:
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:
xxxxxxxxxx
// 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.
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:
xxxxxxxxxx
{% 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 %}
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 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.
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.
xxxxxxxxxx
// 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"]
}
xxxxxxxxxx
<!--Looping through a repeating field-->
<ul>
{% for item in module.ingredient %}
<li>{{ item }}</li>
{% endfor %}
</ul>
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.
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.
xxxxxxxxxx
// 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"
}
]
}
xxxxxxxxxx
<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>
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.
xxxxxxxxxx
"occurrence" : {
"min" : 1,
"max" : 4,
"sorting_label_field" : "ingredients.ingredient",
}
Parâmetro | Tipo | Descrição | Padrão |
---|---|---|---|
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. |
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.
xxxxxxxxxx
// 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:
xxxxxxxxxx
// 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:
xxxxxxxxxx
// 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.
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.
xxxxxxxxxx
"visibility" : {
"controlling_field_path" : "field_name",
"controlling_value_regex" : "regular_expression_in_controlling_field",
"property": "src",
"operator" : "EQUAL"
}
Parâmetro | Tipo | Descrição |
---|---|---|
controlling_field_path | String | O caminho separado por ponto do campo que controla a condição de exibição.
|
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 deve ser atendido. Os operadores podem ser um dos seguintes:
|
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. |
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:
xxxxxxxxxx
[
{
"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"
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
.
xxxxxxxxxx
"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âmetro | Tipo | Descrição |
---|---|---|
visibility_rules | String | Por padrão, esse valor é definido como SIMPLE . Para usar advanced_visibility , defina como ADVANCED . |
boolean_operator | String | O operador booleano para os critérios condicionais. Pode ser AND ou OR . |
criteria | Matriz | 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.
|
controlling_value_regex | String | O 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. |
operator | String | O operador que define como o valor controlling_value_regex deve ser atendido. Os operadores podem ser um dos seguintes:
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.
xxxxxxxxxx
[
{
"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:
- Quando um link de pagamento for selecionado, os três campos a seguir (
checkout_location
,button_text
eicon
) serão exibidos. Isso ocorre porque os campos têm um atributo devisibility
que é controlado pelo campo depayment
e exige um valor de ID no parâmetro deid
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.
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.
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.
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 campotext_field
estiver definido comotesting
. - O campo
fancy_page
inclui lógica para ser desativado setext_field
outext_field_2
estiver definido como qualquer valor diferente detesting
etesting2
respectivamente.
xxxxxxxxxx
// 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âmetro | Tipo | Descrição |
---|---|---|
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 | Matriz | Uma 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_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.
|
controlling_value_regex | String | O 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. |
operator | String | O operador que define como o valor controlling_value_regex deve ser atendido. Os operadores podem ser um dos seguintes:
MATCHES_REGEX . |
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:
xxxxxxxxxx
// 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.
xxxxxxxxxx
// 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"
]
}
}
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.
xxxxxxxxxx
hs theme generate-selectors <theme-directory-path>
Descrição | Parâmetro |
---|---|
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).