Ignorar e ir ao conteúdo principal

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.

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.

Editor de módulos do gerenciador de design

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.

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

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

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.
  • Rótulos de grupo: para grupos de detalhamento, você pode substituir o rótulo do grupo para exibi-lo maior com um divisor abaixo. large-label-example
  • Ícone do grupo: se desejar, você pode incluir um ícone Font Awesome que é exibido à esquerda do rótulo. ícone-exemplo
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.
use_large_labelBooleanoSe 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.
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.

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.

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.

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

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:

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:

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.

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:

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:

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.

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

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:

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.

campo repetidor

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.

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.

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

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.

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.

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:

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:

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.

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:

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.

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.

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.

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

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:

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.

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.

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 > SiteTemas > Exibir tema).