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

Last updated:

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.

theme-settings-fields

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

HubSpot CLI

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.

Éditeur de modules du gestionnaire de conception

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. 

side-by-side-modules0

Un champ unique dont le 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 afficher sous forme de groupes. Les modules et les thèmes permettent de regrouper plusieurs champs. 

Groupe de champs sans groupes de champs imbriqués

Les groupes de champs sans groupes de champs imbriqués s'affichent simplement avec des séparateurs au-dessus et en dessous du groupe, et l'étiquette du groupe est affichée en haut du groupe.

Groupe de champs imbriqués

Les groupes de champs peuvent être imbriqués. Un groupe de champs qui contient un autre groupe de champs s'affiche comme un bouton. En cliquant sur le bouton pour visualiser le groupe, le contenu de ce groupe s'affiche.

Les groupes de champs peuvent être imbriqués sur 3 niveaux de profondeur, ce qui signifie que les champs de modules peuvent avoir 4 niveaux de profondeur. Cela facilite la création d'interfaces utilisateur qui transmettent les relations entre les champs et plus de profondeur.

Groupes de champs dans fields.json

Les objets de groupe de champs peuvent être répertoriés comme enfants d'autres groupes de champs. Leur structure est très similaire à celle des champs eux-mêmes, le seul paramètre spécial étant le paramètre « enfants », qui est un tableau de champs et de groupes qu'ils contiennent.

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

Développer le groupe de champs par défaut

Les groupes de champs peuvent être définis pour être développés par défaut en définissant la propriété booléenne expanded sur true dans les propriétés du groupe fields.json, comme indiqué dans l'exemple de code ci-dessus. Les groupes de champs ne sont pas développés par défaut et lorsque des groupes de champs imbriqués sont utilisés, le groupe parent ne peut pas utiliser cette propriété.

Sortie des valeurs des champs dans les groupes de champs

Les groupes de champs créent des dictionnaires qui contiennent les valeurs des champs que vous souhaitez éditer. Si vous imbriquez des groupes de champs, le groupe de champs imbriqué devient un dictionnaire à l'intérieur du dictionnaire du groupe de champs extérieur. Pour accéder à ces données, vous traverserez 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 }}; }

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 : 

style-field-module-editor0

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 modèle 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 :

style-field-theme-editor0

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 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 modèle 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 de 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 HubSpot Ideas.

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 autour des ingrédients. C'est là tout l'intérêt des répéteurs. HubSpot dispose de deux formes de répéteurs : les champs répétés et les groupes répétés.

Champs répétés

Les champs répétés sont des champs normaux, mais les créateurs de contenu peuvent ajouter, supprimer et réorganiser les instances du champ. En utilisant l'exemple de module de recette ci-dessus, chaque ingrédient peut être un champ de texte répétitif. 

champ répéteur

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 parcourir en boucle 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

Les groupes répétés sont des groupes de champs dont l'option de répétition est activée. Les groupes répétés permettent aux créateurs de contenu d'ajouter, de supprimer et de réorganiser des groupes de champs. En utilisant l'exemple de module de recette, supposons que vous souhaitez intégrer votre liste d'ingrédients à une fonctionnalité de liste de courses au sein de votre module de recette.

Groupe répété de champs

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

Pour améliorer l'expérience d'édition et empêcher les éditeurs de contenu de fournir des valeurs que vous n'avez pas prises en compte dans le programme, nous vous permettons de définir des valeurs minimales et maximales pour le nombre d'éléments que les créateurs de contenu peuvent ajouter à un champ répété ou à un groupe répété. 

Pour les groupes répétés, vous pouvez également définir le champ qui sert de libellé pour cet élément lors de l'affichage du répéteur.

Nombre maximal d'occurrences
"occurrence" : { "min" : 1, "max" : 4, "sorting_label_field" : "ingredients.ingredient", }
Options du répéteur
ParameterTypeDescription Default
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 si vous accédiez à 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" } }

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_path 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 the effects of default_value_path and property_value_paths { "name": "body_font", "type": "font", "default": { "font": "Helvetica", "color": "#000000" } }, { "name": "secondary_color", "type": "color", "default": { "color": "#C27BA0", "opacity": 100 } }, { "name": "h1_font", "type": "font", "default": {}, "inherited_value": { "default_value_path": "module.body_font", "property_value_paths": { "color": "module.secondary_color.color" } } }

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" }
Use this table to describe parameters / fields
ParameterTypeDescription
controlling_field_path
String

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
String

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
String

L'opérateur qui définit la manière dont la valeur controlling_value_regex doit être respectée. Opérateurs possibles : 

  • NO_EQUAL
  • EQUAL
  • EMPTY
  • NOT_EMPTY
  • MATCHES_REGEX
property
String

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.

L'attribut de visibilité 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" }] }
Use this table to describe parameters / fields
ParameterTypeDescription
visibility_rules
String

Par défaut, cette valeur est définie sur SIMPLE. Pour utiliser advanced_visibility, définissez sur ADVANCED.

boolean_operator
String

L'opérateur booléen pour les critères conditionnels. Peut être AND ou OR.

criteria
Array

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
String

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
String

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 control_field_path mais sans control_value_regex est visible si le champ de contrôle a une valeur non nulle, non vide.

operator
String

L'opérateur qui définit la manière dont la valeur controlling_value_regex doit être respectée. Opérateurs possibles : 

  • NO_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 :

payment-link-selector

  • 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.
display-conditions-property

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. 

Screenshot 2023-05-23 at 4.10.28 PM

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" }, ] } } } ]
Use this table to describe parameters / fields
ParameterTypeDescription
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 (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

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 control_field_path mais sans control_value_regex est visible si le champ de contrôle a une valeur non nulle, 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 : 

  • NO_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" ] } }

growth-theme-hover

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>
ParameterDescription
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 > Voir le thème). 

Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.