Présentation des modules et des champs de thème

Dans les modules et les thèmes, les champs sont utilisés pour permettre aux créateurs de contenu de contrôler le style et les fonctionnalités des modules ainsi que des thèmes sur votre site web. Lorsque vous développez un module ou un thème, vous incluez des champs dans un fichier fields.json, qui sera ensuite traduit vers les éditeurs de thème et de contenu.

Découvrez ci-dessous comment créer et gérer des options pour les champs de module et de thème. Pour en savoir plus sur les types de champs spécifiques, consultez le guide de référence sur les types de modules et de champs.

Créer et modifier des champs

Vous pouvez ajouter des champs au fichier fields.json d’un module localement par le biais du ILC HubSpot et dans l’éditeur de module présent dans l’application. Pour ajouter des champs à un thème, vous devez mettre à jour le fichier fields.json du thème en utilisant l’ILC.

ILC HubSpot

Lors du développement local d’un module ou d’un thème, les champs peuvent être modifiés par le biais d’un fichier fields.json situé dans le dossier du module ou du thème. Pour les modules, ce fichier est automatiquement créé lors de l’utilisation de la commande hs create module. Toutes les options de champ disponibles dans l’éditeur de module sont disponibles sous forme de propriétés que vous pouvez ajouter ou modifier dans le fichier fields.json. Cela comprend les champs, les groupes et les conditions des répéteurs. L’un des avantages de l’édition locale est qu’elle facilite l’inclusion de vos modules dans les systèmes de contrôle de version tels que git.

Éditeur de module

Le gestionnaire de conception dispose d’une interface utilisateur intégrée dédiée à l’éditeur de module qui vous permet de créer, de regrouper et de modifier les champs de module. L’éditeur de module contient un aperçu du module qui vous permet de visualiser le module seul, ainsi que de tester ses champs. Vous devez toujours tester les modules sur un modèle que vous prévoyez d’utiliser afin de voir quels styles de modèles peuvent les affecter. Attention : si un module est contenu dans un dossier verrouillé, il ne peut pas être modifié de cette façon.

Remarque : si vous travaillez principalement en local, mais que vous souhaitez utiliser l’éditeur de module pour configurer les champs, veillez à récupérer vos modifications. Ceci est particulièrement important pour les personnes utilisant des systèmes de contrôle de version tels que git.

Champs côte à côte

Par défaut, les champs de module des éditeurs de contenu s’empilent verticalement. Toutefois, vous pouvez placer des champs de module côte à côte en ajoutant la propriété display_width aux champs dans le fichier fields.json avec la valeur half_width.

Un champ unique avec un display_width de half_width apparaîtra en demi-largeur dans l’éditeur de contenu. Lorsque le champ situé au-dessus ou en dessous de ce champ dans le fichier fields.json est défini sur half_width, ils sont placés côte à côte.

// 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"
  }
]

Groupes de champs

Lorsque les champs sont liés les uns aux autres, il est souvent judicieux de les regrouper visuellement. Pour ce faire, vous pouvez créer des groupes de champs, qui sont pris en charge à la fois dans les modules et les thèmes. Pour créer un groupe de champs localement, créez un objet dans fields.json avec l’élément type de "group". Ensuite, incluez un tableau children pour contenir les champs que vous souhaitez regrouper.

[
  {
    "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"
      }
    ]
  }
]

Vous pouvez créer des groupes de champs supplémentaires à l’intérieur d’un groupe en ajoutant un autre type d’objet "group" dans le premier paramètre children. Ensuite, construisez le groupe de champs de la même manière que ci-dessus, en utilisant children pour contenir les champs. Vous pouvez imbriquer des groupes de champs jusqu’à une profondeur de trois.

[
  {
    "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
            }
          }
        ]
      }
    ]
  }
]

Options d’affichage du groupe de champs

Vous pouvez personnaliser le comportement d’affichage des groupes de champs suivant :

Expansion : par défaut, les groupes de champs s’affichent réduits dans l’éditeur. Les groupes qui contiennent des groupes imbriqués s’affichent sous forme de boutons d’exploration qui ouvrent le groupe dans sa propre vue, le groupe situé le plus à l’intérieur affichant des séparateurs.

Type d’affichage : par défaut, les groupes qui ne contiennent pas de groupes imbriqués s’afficheront sous forme de sections réductibles avec des séparateurs visuels autour de leurs enfants. Les groupes qui contiennent des groupes imbriqués s’affichent sous forme de boutons d’exploration qui ouvrent le groupe dans sa propre vue, le groupe situé le plus à l’intérieur affichant des séparateurs.
Icône du groupe : si vous le souhaitez, vous pouvez inclure une icône Font Awesome qui s’affiche à gauche de l’étiquette.

[
  {
    "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"
      }
    ]
  }
]

Paramètre	Type	Description
`display`	String	Le style d’affichage du groupe de champs. Peut être l’un des suivants : `drilldown` : affiche le groupe réduit avec un bouton permettant d’ouvrir les enfants du groupe dans son propre panneau. Il s’agit de l’affichage par défaut pour les groupes qui contiennent des groupes imbriqués. `accordion` : affiche le groupe réduit avec un bouton permettant de développer les enfants du groupe ci-dessous sous forme de section extensible. Il s’agit de l’affichage par défaut pour les groupes sans groupes imbriqués. `inline` : affiche le groupe et ses enfants en ligne sans option permettant de réduire le groupe.
`icon`	Objet	Ajoute une icône à gauche du libellé. Contient les paramètres suivants : `name` : l’identifiant de l’icône Font Awesome. `set` : l’ensemble d’icônes Font Awesome. `type` : style d’icône (par exemple, `SOLID`, `REGULAR`).
`expanded`	Booléen	indique si le groupe de champs est développé par défaut.

Sortir des valeurs des champs dans les groupes de champs

Les groupes de champs créent des dict. qui contiennent les valeurs des champs que vous souhaitez éditer. Si vous imbriquez des groupes de champs, le groupe de champs imbriqué devient un dict. à l’intérieur du dict. du groupe de champs extérieur. Pour accéder à ces données, vous parcourez l’arborescence à partir du thème racine ou de la variable du module, selon le contexte.

<div>
{# printing a value from a field group `recipe_summary` is the field group,
`title` is the text field. #} {{module.recipe_summary.title}}
</div>

/* Printing a Font field's color value, when the font field is within a field group.
`typography` is the field group, `h1_font` is the field */
h1{
color: {{ theme.typography.h1_font.color }};
}

Éléments phares dans le groupe de champs imbriqués

Dans les cas où un groupe de champs est répété, vous pouvez spécifier une ou plusieurs de ces occurrences en tant qu’éléments phares, ce qui vous permet de styliser l’élément séparément pour le faire ressortir. Par exemple, cela peut être particulièrement utile pour une page produit où vous pouvez avoir un produit phare que vous souhaitez mettre en avant. Vous pouvez spécifier un nombre maximum d’éléments phares par groupe de champs. Dans l’éditeur, les créateurs de contenu peuvent ensuite marquer les éléments comme phares selon leurs besoins.

Pour activer les éléments phares dans un groupe de champs, incluez la propriété group_occurrence_meta dans la configuration du groupe de champs. Cette propriété contient les propriétés suivantes :

featured_enabled : défini sur true pour activer les éléments phares.
featured_limit : le nombre maximum d’éléments phares à autoriser.

Le groupe de champs doit également inclure la propriété 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>"
    }
  ]
}

Pour vérifier si un élément d’un groupe répété est présenté, vous pouvez interroger la propriété hs_meta. Le code ci-dessous utilise une boucle for pour vérifier les éléments de groupe de champs qui sont définis comme phares, puis affiche le titre de chacun sous forme d’en-tête 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>

Champs de style

Les champs de style sont un type de groupe de champs spécifique dans le fichier fields.json d’un module ou d’un thème. Celui-ci permet aux créateurs de contenu de contrôler le style d’un module ou d’un thème dans l’éditeur de page et de thème. Découvrez ci-dessous comment ajouter des champs de style à un module ou à un thème. Découvrez les meilleures pratiques pour utiliser et organiser les champs de style.

Champs de style du module

Les champs de style ajoutés à un module apparaissent dans l’onglet Styles de l’éditeur de page lors de l’édition du module :

Lorsque vous ajoutez des champs de style au fichier fields.json d’un module, vous les ajoutez dans un groupe de styles. Ce groupe, cependant, peut contenir plusieurs groupes en son sein, comme indiqué ci-dessous :

// 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"
            }
          }
        }
      }
    ]
  }
]

Les champs suivants peuvent être utilisés comme champs de style dans les modules. Découvrez chacun des types de champs dans le module et le guide des types de champs.

Découvrez-en davantage sur les types de champs de modules et de thèmes. Consultez le boilerplate du CMS pour obtenir un exemple de champs de style dans le fichier fields.json d’un module.

Champs de style de thème

Les champs de style ajoutés à un thème apparaissent dans la barre latérale gauche de l’éditeur de thème :

Tous les champs de style contenus dans le fichier fields.json d’un thème seront ajoutés à la barre latérale gauche de l’éditeur de thème. Il n’est pas nécessaire de les placer dans un groupe de styles, comme illustré ci-dessous :

// 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]"
         }
       }
     }
   ]
  }
]

Les champs suivants peuvent être utilisés comme champs de style dans les thèmes. Découvrez chacun des types de champs dans le module et le guide des types de champs.

Découvrez-en davantage sur les types de champs de modules et de thèmes. Consultez le boilerplate du CMS pour obtenir un exemple de champs de style dans le fichier fields.json d’un thème.

Remarque : Si vous êtes un fournisseur du marketplace, vous ne devez pas remplacer les champs de contenu existants par des champs de style dans les modules existants. La modification de la hiérarchie des champs dans un fichier fields.json peut entraîner la perte des données des instances de module existantes. Ajoutez de nouveaux champs de style ou créez une nouvelle liste dans laquelle les champs sont regroupés de manière appropriée. Cela permet d’éviter que vos mises à jour ne constituent des changements brusques pour les clients qui utilisent vos thèmes. Pour mettre en place la migration à partir des anciens modules, consultez le forum des idées HubSpot.

CSS générée

Certains champs de style permettent d’éditer directement des CSS en fonction de la valeur du champ. Cette fonction est particulièrement utile pour les champs qui peuvent contrôler des styles plus complexes, comme les dégradés. Les champs de style suivants ont une propriété .css générée :

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

Répéteurs

Lorsque vous créez des modules qui mettent en forme des informations, il arrive souvent que certains types d’informations se répètent. Un module de recette, par exemple, peut avoir un champ dédié aux « Ingrédients ». La plupart des recettes se composent de plus d’un ingrédient. En les dotant d’un champ de texte enrichi, il se peut que vous ne puissiez plus imposer de style cohérent ni ajouter de fonctionnalités pour chaque ingrédient. C’est là tout l’intérêt des répéteurs, dont HubSpot dispose de deux formes distinctes : les champs répétés et les groupes répétés.

Champs répétés

Ainsi, le créateur de contenu peut ajouter autant d’ingrédients qu’il le souhaite. Les développeurs obtiennent un tableau qu’ils peuvent faire défiler pour imprimer cette liste d’ingrédients, en appliquant le formatage et les fonctionnalités désirés. Les champs répéteurs sont utilisés de préférence dans des situations très simples. Il est souvent plus judicieux de répéter les groupes.

Remarque : il n’est actuellement pas possible de définir l’ordre par défaut des champs répétés.

Champs répétés dans 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"]
}

Boucle dans les éléments du module HTML+HubL

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

Groupes répétés

La quantité d’un ingrédient serait un élément crucial de la liste de courses. Si l’on fournit cette information dans le champ de texte, le module devrait alors analyser le champ de texte et espérer parvenir à séparer la quantité de l’ingrédient. C’est là toute l’utilité des groupes répétés. Le résultat de ces champs est un objet qui peut être parcouru en boucle.

Groupes répétés dans 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"
    }
  ]
}

Boucle dans les champs répétés des modules

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

Options du répéteur

"occurrence" : {
    "min" : 1,
    "max" : 4,
    "sorting_label_field" : "ingredients.ingredient",
}

Paramètre	Type	Description	Par défaut
`max`	Entier	Nombre maximum d’occurrences de ce groupe. Empêche le créateur de contenu d’ajouter plus que ce nombre d’éléments dans l’interface utilisateur.	`null`
`min`	Entier	Nombre minimum d’occurrences de ce groupe de champs. Empêche le créateur de contenu d’avoir moins de ce nombre d’éléments dans l’interface utilisateur.	`null`
`sorting_label_field`	Chaîne	Il s’agit de l’identifiant du champ dont il faut extraire le texte pour l’afficher dans l’interface utilisateur sur les cartes à glisser. Par défaut, il s’agit du premier champ du groupe.

Champs hérités

La propriété inherited_value peut être configurée pour qu’un champ hérite de sa valeur par défaut d’autres champs. Pour définir la valeur par défaut d’un champ à partir de la valeur d’un autre champ, définissez default_value_path comme chemin d’accès au nom du champ cible. Lorsque default_value_path est défini, il ignorera tout default défini sur le champ. Pour accéder aux valeurs d’autres champs, les chemins doivent inclure module. au début, comme lorsque vous accédez à la valeur dans le code HubL du module.

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

Étant donné que la famille de polices est déterminée par une combinaison de font et font_set, vous devez inclure les deux pour l’héritage des champs de police. Découvrez-en davantage sur le champ de police.

Pour les champs complexes (champs dont les valeurs sont des objets), les utilisateurs peuvent disposer d’une plus grande granularité sur les propriétés héritées grâce à l’option property_value_path. Tous les chemins référencés dans inherited_value peuvent également inclure des clés provenant de la valeur d’un champ pour les champs complexes. Par exemple, les champs de couleur ont des valeurs d’objet qui contiennent la couleur du champ ainsi que son opacité. Ainsi, pour obtenir la valeur réelle d’une couleur sans son opacité, le chemin d’accès doit se terminer par .color. Par exemple, un champ de police ne peut hériter sa couleur que d’un champ de couleur distinct :

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

Vous pouvez également combiner les effets de default_value_path et de property_value_paths pour hériter d’une valeur par défaut d’un champ tout en héritant d’une valeur de propriété spécifique d’un champ différent :

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

Si un champ hérite d’un autre champ, mais qu’il est ensuite directement remplacé au niveau de la page ou dans les paramètres du thème, son lien avec le champ de contrôle est rompu. Les champs liés via default_value_path ou property_value_paths n’affecteront plus la valeur de ce champ.

Visibilité du champ

Lors de la définition de champs de module et de thème personnalisés, vous pouvez configurer l’affichage d’un champ en ajoutant l’objet visibility au champ dans le fichier fields.json. Par exemple, vous pouvez définir un module de formulaire pour afficher une zone de texte enrichi lorsque le message de remerciement est sélectionné, mais un sélecteur de page lorsqu’une redirection est sélectionnée. Vous pouvez définir la visibilité en fonction de la valeur de controlling_field_path ou d’une propriété spécifique dans ce champ à l’aide du paramètre property. Vous pouvez également appliquer la visibilité à un champ individuel ou à un groupe de champs pour contrôler la visibilité de tous les éléments du groupe.

"visibility" : {
 "controlling_field_path" : "field_name",
 "controlling_value_regex" : "regular_expression_in_controlling_field",
 "property": "src",
 "operator" : "EQUAL"
  }

Paramètre	Type	Description
`controlling_field_path`	Chaîne	Le chemin du champ qui contrôle la condition d’affichage. Si le champ n’est pas imbriqué dans un groupe de champs, utilisez le nom du champ (par exemple : `field_name`). Pour les champs imbriqués dans des groupes, le chemin doit correspondre à sa structure de groupe, séparée par un point. Par exemple : `field_group_name.field_name` `parent_group.child_group.field_name`
`controlling_value_regex`	Chaîne	L’expression régulière dans le champ de contrôle qui doit être présente pour que le champ s’affiche. L’expression régulière doit correspondre à la chaîne entière (et non à un sous-ensemble) et est exécutée en fonction de la casse.
`operator`	Chaîne	L’opérateur qui définit la manière dont la valeur `controlling_value_regex` doit être respectée. Opérateurs possibles : `NOT_EQUAL` `EQUAL` `EMPTY` `NOT_EMPTY` `MATCHES_REGEX`
`property`	Chaîne	Définit la visibilité en fonction d’une propriété spécifique du champ cible. Par exemple, vous pouvez activer la visibilité lorsque la propriété `src` d’un champ d’image est égale à une valeur spécifique. Par défaut, si aucune valeur n’est fournie pour ce champ, la visibilité est basée sur la valeur de chaîne de `controlling_value_regex`.

Vous pouvez également inclure un objet occurrence_options à l’intérieur de l’objet visibility pour cibler le nombre de valeurs d’un champ répété. Cet objet doit inclure count pour la comparaison et une définition operator. Par exemple, pour afficher un champ de texte uniquement lorsqu’un autre champ répété comporte au moins deux éléments, vous pouvez définir visibility comme suit :

[
  {
    "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"
          }
        }
      }
    ]
  }
]

Vous pouvez utiliser n’importe laquelle des valeurs suivantes operater :

"NOT_EQUAL"
"EQUAL"
"EMPTY"
"NOT_EMPTY"
"GREATER_THAN"
"GREATER_THAN_OR_EQUAL"
"LESS_THAN"
"LESS_THAN_OR_EQUAL"

Visibilité avancée

L’attribut visibility ne peut prendre en charge qu’un seul critère à la fois. Pour inclure plusieurs critères avec plusieurs opérateurs ainsi que l’ordre des opérations, vous pouvez utiliser 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"
    }]
}

Paramètre	Type	Description
`visibility_rules`	Chaîne	Par défaut, cette valeur est définie sur `SIMPLE`. Pour utiliser `advanced_visibility`, définissez sur `ADVANCED`.
`boolean_operator`	Chaîne	L’opérateur booléen pour les critères conditionnels. Peut être `AND` ou `OR`.
`criteria`	Tableau	Un tableau d’objets de visibilité qui définit les critères conditionnels qui doivent être remplis pour que le champ s’affiche.
`controlling_field_path`	Chaîne	Le chemin du champ qui contrôle la condition d’affichage. Si le champ n’est pas imbriqué dans un groupe de champs, utilisez le nom du champ (ex : `field_name`). Pour les champs imbriqués dans des groupes, le chemin doit correspondre à sa structure de groupe, séparée par un point. Par exemple : `field_group_name.field_name` `parent_group.child_group.field_name`
`controlling_value_regex`	Chaîne	La valeur dans le champ de contrôle qui doit être respectée pour afficher le champ. Lors de l’utilisation de l’opérateur `MATCHES_REGEX`, l’expression régulière doit correspondre à la chaîne entière (et non à un sous-ensemble) et est exécutée en fonction de la casse. Un champ avec `controlling_field_path`, mais sans `controlling_value_regex` est visible si le champ de contrôle a une valeur non-nulle et non vide.
`operator`	Chaîne	L’opérateur qui définit la manière dont la valeur `controlling_value_regex` doit être respectée. Opérateurs possibles : `NOT_EQUAL` `EQUAL` `EMPTY` `NOT_EMPTY` `MATCHES_REGEX` La syntaxe de l’expression régulière est obligatoire lors de l’utilisation de `MATCHES_REGEX`.

Par exemple, vous trouverez ci-dessous la première partie du code du module de paiement par défaut. Pour consulter le code complet, vous pouvez cloner le module dans HubSpot, puis le télécharger dans votre environnement local pour afficher le fichier fields.json du module.

[
  {
    "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
]

Le code ci-dessus entraîne le comportement suivant :

Le premier champ (payment) est un champ obligatoire (menu déroulant) qui permet au créateur de contenu de sélectionner un lien de paiement spécifique. Dans HubSpot, un créateur de contenu verra les éléments suivants lors du premier ajout du module à la page :

Une fois qu’un lien de paiement est sélectionné, les trois champs suivants (checkout_location, button_text, et icon) s’affichent. En effet, les champs ont un attribut visibility contrôlé par le champ de payment et nécessitant une valeur d’ID dans le paramètre id du champ de paiement.

Le champ icon lui-même utilise advanced_visibility pour apparaître uniquement lorsqu’un lien de paiement est présent dans le champ payment ET lorsque la case à cocher add_icon est sélectionnée. En plus de définir la visibilité dans fields.json, vous pouvez définir la visibilité dans le gestionnaire de conception en modifiant les options Conditions d’affichage d’un champ.

Après avoir défini la visibilité dans le gestionnaire de conception, vous pouvez récupérer le module à l’aide de l’ILC pour afficher l’attribut visibility dans le fichier fields.json du module.

Désactivation de champ conditionnel

Vous pouvez ajouter des conditions à un champ pour empêcher la modification lorsque les conditions spécifiées sont remplies. Vous pouvez également définir un message à afficher au-dessus du champ lorsqu’il est désactivé pour fournir un contexte dans l’éditeur de contenu.

Les conditions et le message sont définis dans l’objet disabled_controls du champ. Les conditions pour rendre un champ modifiable sont définies dans l’objet rules, qui suit le même format que advanced_visibility. Le code ci-dessous montre à la fois une mise en œuvre simple et avancée des critères rules :

Le champ simple_page inclut une logique pour désactiver le champ si le champ text_field est défini sur testing.
Le champ fancy_page inclut une logique pour désactiver le champ si text_field ou text_field_2 est défini sur une valeur non égale à testing et testing2 respectivement.

// 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"
          }
        ]
      }
    }
  }
]

Paramètre	Type	Description
`message`	Chaîne	Le message à afficher dans l’éditeur de contenu lorsque le champ est désactivé.
`rules`	Objet	Les conditions d’activation du champ pour modification.
`criteria`	Tableau	Un tableau d’objets de condition qui définit les critères qui doivent être remplis pour que le champ s’affiche. Ce tableau peut contenir plusieurs objets de condition séparés par une logique `AND` ou `OR` via le paramètre `boolean_operator`.
`boolean_operator`	Chaîne	L’opérateur booléen pour les critères conditionnels. Peut être `AND` ou `OR`. Lorsqu’il n’est pas spécifié, la valeur par défaut est `AND`.
`controlling_field_path`	Chaîne	Le chemin du champ qui contrôle la condition d’affichage. Si le champ n’est pas imbriqué dans un groupe de champs, utilisez le nom du champ (ex : `field_name`). Pour les champs imbriqués dans des groupes, le chemin doit correspondre à sa structure de groupe, séparée par un point. Par exemple : `field_group_name.field_name` `parent_group.child_group.field_name`
`controlling_value_regex`	Chaîne	La valeur dans le champ de contrôle qui doit être respectée pour afficher le champ. Lors de l’utilisation de l’opérateur `MATCHES_REGEX`, l’expression régulière doit correspondre à la chaîne entière (et non à un sous-ensemble) et est exécutée en fonction de la casse. Un champ avec `controlling_field_path`, mais sans `controlling_value_regex` est visible si le champ de contrôle a une valeur non-nulle et non vide.
`operator`	Chaîne	L’opérateur qui définit la manière dont la valeur `controlling_value_regex` doit être respectée. Opérateurs possibles : `NOT_EQUAL` `EQUAL` `EMPTY` `NOT_EMPTY` `MATCHES_REGEX` La syntaxe de l’expression régulière est obligatoire lors de l’utilisation de `MATCHES_REGEX`.

Mise en évidence des champs de l’éditeur de thème

Dans l’éditeur de thème, la mise en évidence de l’aperçu peut aider les créateurs de contenu à identifier les champs qui contrôlent les éléments de page. La mise en évidence de l’aperçu fonctionne en associant les champs du thème aux sélecteurs CSS qu’ils affectent, en ajoutant une zone autour de ces éléments lors du survol du champ dans l’éditeur de thème. Pour configurer la mise en évidence d’aperçu pour les champs de thème, vous inclurez un fichier editor-preview.json dans le répertoire racine du thème pour mapper les champs de thème à une liste de sélecteurs CSS. Dans le fichier, vous inclurez un tableau pour chaque champ de style que vous souhaitez mettre en évidence contenant les sélecteurs CSS pertinents, en utilisant le format suivant :

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

Par exemple, le code ci-dessous mettra en évidence les éléments de la page qui sont contrôlés par le champ de police principal. Vous pouvez consulter l’exemple complet dans le fichier editor-preview.json du thème Growth par défaut.

// 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"
    ]
  }
}

Pour commencer à générer ce fichier, exécutez la commande d’ILC suivante pour créer le fichier. Lors de la création du fichier, un script s’exécutera pour configurer les mappages initiaux des sélecteurs de champ.

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

Paramètre	Description
`theme-directory-path`	Le chemin d’accès au répertoire du thème.

Après avoir exécuté la commande, vous devrez examiner et affiner le fichier editor-preview.json pour vous assurer que les champs et les sélecteurs sont mappés correctement. Si la commande generate-selectors fera une supposition rudimentaire sur les champs qui affectent les sélecteurs, vous devrez apporter des corrections en fonction de la façon dont votre thème est construit. Par exemple, cette commande ne peut pas détecter si des modules remplacent le style ou si vous utilisez des macros. Pour tester ces mappages, téléchargez le thème sur un compte, puis consultez l’éditeur de thème de ce compte (**Paramètres ** > Site web > Thèmes > Afficher le thème).

Champs

HubL

React

Modules

Fonctions sans serveur

Présentation des modules et des champs de thème

Créer et modifier des champs

ILC HubSpot

Éditeur de module

Champs côte à côte

Groupes de champs

Options d’affichage du groupe de champs

Sortir des valeurs des champs dans les groupes de champs

Éléments phares dans le groupe de champs imbriqués

Champs de style

Champs de style du module

Champs de style de thème

CSS générée

Répéteurs

Champs répétés

Champs répétés dans fields.json

Boucle dans les éléments du module HTML+HubL

Groupes répétés

Groupes répétés dans fields.json

Boucle dans les champs répétés des modules

Options du répéteur

Champs hérités

Visibilité du champ

Visibilité avancée

Désactivation de champ conditionnel

Mise en évidence des champs de l’éditeur de thème

​Créer et modifier des champs

​ILC HubSpot

​Éditeur de module

​Champs côte à côte

​Groupes de champs

​Options d’affichage du groupe de champs

​Sortir des valeurs des champs dans les groupes de champs

​Éléments phares dans le groupe de champs imbriqués

​Champs de style

​Champs de style du module

​Champs de style de thème

​CSS générée

​Répéteurs

​Champs répétés

​Champs répétés dans fields.json

​Boucle dans les éléments du module HTML+HubL

​Groupes répétés

​Groupes répétés dans fields.json

​Boucle dans les champs répétés des modules

​Options du répéteur

​Champs hérités

​Visibilité du champ

​Visibilité avancée

​Désactivation de champ conditionnel

​Mise en évidence des champs de l’éditeur de thème

Créer et modifier des champs

ILC HubSpot

Éditeur de module

Champs côte à côte

Groupes de champs

Options d’affichage du groupe de champs

Sortir des valeurs des champs dans les groupes de champs

Éléments phares dans le groupe de champs imbriqués

Champs de style

Champs de style du module

Champs de style de thème

CSS générée

Répéteurs

Champs répétés

Champs répétés dans fields.json

Boucle dans les éléments du module HTML+HubL

Groupes répétés

Groupes répétés dans fields.json

Boucle dans les champs répétés des modules

Options du répéteur

Champs hérités

Visibilité du champ

Visibilité avancée

Désactivation de champ conditionnel

Mise en évidence des champs de l’éditeur de thème