Premiers pas avec les modules

Last updated:

Dans ce tutoriel, vous utiliserez le thème boilerplate de CMS Hub afin de découvrir comment créer un module et l'utiliser dans des modèles et des pages dans le cadre d'un thème. À la fin du tutoriel, vous aurez créé un module de témoignage client comprenant un champ d'image, un champ de texte et un champ de texte enrichi. 

S'il s'agit de votre première expérience avec le développement CMS Hub, nous vous recommandons ce qui suit :

Quick start to CMS Hub development

Remarque : Si vous souhaitez développer un module à utiliser dans un thème que vous souhaitez répertorier sur le marketplace des ressources HubSpot, consultez les exigences du marketplace des ressources concernant les modules.

Avant de commencer

Avant de commencer ce tutoriel :

  • Créez un compte sandbox de développeur CMS Hub. Vous pouvez utiliser votre compte existant, mais le compte sandbox vous permettra de développer sans impacter les éléments de votre compte principal.
  • Installez Node.js, qui active les outils de développement local de HubSpot. Les versions 10 ou ultérieures sont prises en charge.

Si vous voulez aller de l'avant, vous pouvez prévisualiser les fichiers de projet terminés. Comme le code du thème de boilerplate CMS peut changer au fil du temps, seuls les fichiers les plus importants que les développeurs devront créer ou modifier au cours du tutoriel sont inclus. Ces fichiers incluent :

  1. Testimonial.module : le dossier contenant les fichiers qui composent le module personnalisé que vous allez créer dans le cadre du tutoriel.
  2. homepage.html : le modèle que vous allez modifier pour inclure le module personnalisé.
  3. images : le dossier contenant les photos de profil que vous utiliserez dans le module. 

Configurer votre environnement de développement local

Au cours de ce tutoriel, vous développerez le module localement. Pour interagir avec HubSpot dans votre interface de ligne de commande, vous devrez installer l'ILC HubSpot et la configurer pour accéder à votre compte.

  • Dans le terminal, exécutez la commande suivante pour installer l'ILC globalement. Pour installer l'ILC uniquement dans votre répertoire actuel, exécutez npm install @hubspot/cli.
npm install -g @hubspot/cli
  • Dans le répertoire où vous stockerez vos fichiers de thème, authentifiez votre compte HubSpot afin de pouvoir interagir avec lui via l'ILC.
hs init
  • Appuyez sur Entrée pour ouvrir la page de la clé d'accès personnelle dans votre navigateur.
  • Sélectionnez le compte sur lequel vous souhaitez effectuer le déploiement, puis cliquez sur Continuer avec ce compte. Vous serez alors redirigé vers la page de la clé d'accès personnelle du compte.
  • À côté de Clé d'accès personnelle, cliquez sur Afficher pour révéler votre clé. Cliquez ensuite sur Copier pour la copier dans votre presse-papiers.
  • Collez la clé dans le terminal, puis appuyez sur Entrée.
  • Saisissez un nom unique pour le compte. Ce nom sera vu et utilisé uniquement par vous lors de l'exécution des commandes. Pour connecter les outils de développement locaux à votre compte, appuyez sur la touche Entrée :

Vous verrez alors un message de succès confirmant que le fichier hubspot.config.yml a été créé.

Ajouter le boilerplate CMS à votre compte

  • Exécutez la commande ci-dessous pour créer un nouveau thème nommé my-theme. Un dossier de thème intitulé my-theme sera alors créé dans votre répertoire de travail, contenant les éléments du boilerplate.
hs create website-theme my-theme
  • Téléchargez les fichiers dans votre compte. 
hs upload <src> <destination>
Use this table to describe parameters / fields
ParameterDescription
<src>

Le chemin d'accès au fichier local, relatif à votre répertoire de travail actuel.

<destination>

Le chemin de destination dans votre compte HubSpot. Il peut s'agir d'un nouveau dossier.

Par exemple, hs upload my-theme my-new-theme téléchargerait le dossier my-theme de votre ordinateur vers un dossier my-new-theme dans HubSpot.

Par défaut, HubSpot va télécharger sur le compte par défaut dans votre fichier hubspot.config,yml. Cependant, vous pouvez également spécifier un compte en incluant l'indicateur --account=<accountNameOrId> dans la commande. Par exemple, hs upload --portal=mainProd.

Découvrez-en davantage dans la référence des commandes d'ILC.

Créer un module dans HubSpot

Avec le boilerplate de CMS dans votre environnement local, vous allez maintenant créer un nouveau module pour le thème.

Aux fins de ce tutoriel, vous créerez le module dans HubSpot, puis le transférerez dans le thème à l'aide de l'ILC. Cependant, vous pouvez également créer des modules à partir de zéro localement à l'aide de la commande hs create module.
  • Connectez-vous à votre compte HubSpot, puis accédez au gestionnaire de conception en accédant à Marketing > Fichiers et modèles > Outils de conception.
  • Dans la barre latérale gauche du gestionnaire de conception, ouvrez le dossier du thème que vous venez de télécharger. 
  • Dans le dossier du thème, ouvrez le dossier des modules.
  • En haut à gauche, cliquez sur Fichier > Nouveau fichier pour créer un nouveau module dans ce dossier.
  • Dans la boîte de dialogue, cliquez sur le menu déroulant, puis sélectionnez Module et Suivant.
    new-module-dropdown-menu0
  • Sélectionnez la case à cocher Pages pour que le module soit disponible pour les sites web et les pages de destination.
  • Nommez le module Témoignage, puis cliquez sur Créer.

Ajouter des champs au module

Ensuite, vous allez ajouter trois champs au module :

  • Un champ de texte pour stocker le nom du client qui donne son témoignage.
  • Un champ d'image qui stockera la photo de profil du client.
  • Un champ de texte enrichi qui stockera le témoignage du client.

Ajouter le champ de texte pour le nom du client

  • Dans la barre latérale droite, cliquez sur le menu déroulant Ajouter un champ, puis sélectionnez Texte.
    testimonial-module-add-field
  • Dans la barre latérale de droite, cliquez sur l'icône Crayon dans l'angle supérieur droit pour nommer le champ. Pour ce tutoriel, saisissez le nom du client. Vous verrez alors le nom de la variable HubL changer pour nom_client.
  • Définissez le texte par défaut sur Sally.
Exemple de champ de texte
  • Dans la barre latérale droite, cliquez sur l'icône du fil d'Ariane pour revenir au menu principal du module. module-breadcrumb-icon0

Ajouter le champ d'image pour la photo de profil du client

  • Ajoutez un autre champ en utilisant la même méthode, en sélectionnant cette fois le type de champ Image.
  • Intitulez le champ Image de profil, puis définissez le nom de la variable HubL sur profile_pic.
  • Sous Image par défaut, sélectionnez la photo de profil fournie pour Sally dans le dossier d'images des fichiers de projet terminés.
  • Définissez le texte alternatif sur Image de profil de Sally.
get-started-with-modules-profile-pic

Ajouter le champ de texte enrichi pour le témoignage de Sally

  • Ajoutez un autre champ en utilisant la même méthode, en sélectionnant cette fois le type de champ Texte enrichi.
  • Intitulez le champ de texte enrichi Témoignage.
  • Cliquez sur la zone Texte enrichi par défaut, puis saisissez « Je n'ai eu que de merveilleuses expériences avec cette entreprise. »
Exemple de champ de texte enrichi

Jusqu'à présent, vous avez ajouté des données dans plusieurs champs de module. À ce stade, le module ne contient pas de code HTML pour restituer ces données. Dans l'éditeur de module, cela se traduit par l'état vide de la section module.html
module-html-empty0

Ensuite, vous ajouterez HubL à module.html pour afficher les données des champs.

Ajouter HubL pour afficher les données des champs

Pour afficher les données des champs précédemment créés, ajoutez le HubL suivant au volet module.html :

<!-- module.html --> {{module.customer_name}} <img src={{module.profile_pic.src}} alt="{{module.profile_pic.alt}}"> {{module.testimonial}}

Les jetons HubL ci-dessus utilisent la notation par points pour accéder aux données de chaque champ. Dans ce cas, étant donné que nous voulons extraire des données des champs de module, chaque jeton commence par module, suivi du nom de la variable HubL du champ. Vous pouvez utiliser la notation par points pour accéder davantage aux propriétés spécifiques d'un champ, que vous pouvez voir dans les jetons profile_pic à la ligne 3 ci-dessus.

  • Une fois le HubL ajouté à votre module, vous pouvez cliquer sur Aperçu en haut à droite pour voir à quoi ressemble le module jusqu'à présent.
design-manager-previewer
  • Puis, dans l'angle supérieur droit, cliquez sur Publier les modifications.

Après avoir créé et publié le module dans HubSpot, vous allez maintenant utiliser l'ILC pour transférer le module dans votre environnement local afin de pouvoir en consulter le contenu et y apporter d'autres modifications.

Consulter et modifier le module localement

Pour afficher le module localement, vous devez tout d'abord le transférer dans votre thème local :

  • Dans le terminal, exécutez la commande hs fetch<hs_src> <destination> :
    • <hs_src> représente le chemin du fichier du module dans HubSpot. Pour obtenir le chemin du fichier, vous pouvez effectuer un clic droit sur le module dans la barre latérale gauche du gestionnaire de conception, puis sélectionner Copier le chemin
      design-manager-copy-path0
    • <destination> représente le chemin d'accès au répertoire local où se trouve votre thème. S'il est omis, il s'agira par défaut de votre répertoire de travail actuel.

Par exemple, si vous êtes déjà dans le répertoire de travail, votre commande fetch peut ressembler à ce qui suit :

hs fetch my-theme/modules/testimonial.module

Ouvrir le dossier du module dans votre environnement local

Dans votre éditeur de code préféré, accédez au dossier du module que vous venez de télécharger depuis votre compte HubSpot. Dans le dossier de votre module, vous verrez cinq fichiers différents :

Use this table to describe parameters / fields
ParameterDescription
fields.json

Un objet JSON qui contient les champs de votre module.

meta.json

Un objet JSON qui contient des méta-informations sur votre module.

module.css

Le fichier CSS qui donne un style à votre module.

module.html

Le HTML et le HubL de votre module.

module.js

Le JavaScript de votre module.

Vous trouverez des informations plus détaillées dans notre documentation sur la structure des fichiers du module, notamment en ce qui concerne les fichiers fields.json et meta.json. Dans ce tutoriel, nous nous concentrerons sur les fichiers fields.json, module.css et module.html ainsi que sur la manière dont ils sont générés, téléchargés et chargés dans l'éditeur de modules du gestionnaire de conception.

Consulter le fichier fields.json du module

Ouvrez le fichier fields.json du module. À l'exception de certains numéros id, de l'attribut src du champ d'image et, éventuellement, de l'ordre des champs, le fichier doit contenir un objet JSON similaire à ce qui suit :

//fields.json [ { "label": "Customer Name", "name": "customer_name", "id": "2a025cd5-7357-007f-ae2f-25ace762588e", "type": "text", "required": true, "locked": false, "validation_regex": "", "allow_new_line": false, "show_emoji_picker": false, "default": "Sally" }, { "label": "Profile Picture", "name": "profile_pic", "id": "7877fb84-eb8a-d2c7-d939-77e6e9557d8f", "type": "image", "required": false, "locked": false, "responsive": true, "resizable": true, "default": { "src": "https://cdn2.hubspotqa.net/hubfs/101140939/profile-pic-sally.svg", "alt": "Sally Profile Picture", "width": 100, "height": 100, "max_width": 100, "max_height": 100 } }, { "label": "Testimonial", "name": "testimonial", "id": "c5524ece-1ab5-f92d-a5de-e2bf53199dfa", "type": "richtext", "required": false, "locked": false, "default": "<p>I’ve had nothing but wonderful experiences with this company.</p>" } ]

Les valeurs des champs suivants correspondront aux valeurs que vous avez ajoutées à l'étape 3 :

  • name : nom du champ.
  • label : libellé du champ.
  • default : valeur par défaut du champ.  

Consulter le fichier module.html du module

Le fichier module.html doit contenir le HubL et le HTML que vous avez saisis précédemment dans l'éditeur de module HubL + HTML.

Pour rendre ce code plus intéressant et adapté pour le style CSS, copiez et collez le code suivant dans le fichier :

<div class="testimonial"> <h1 class="testimonial__header"> {{ module.customer_name }} </h1> <img class="testimonial__picture" src={{ module.profile_pic.src }} alt={{ module.profile_pic.alt }}> {{ module.testimonial }} </div>

En saisissant votre HTML comme ci-dessus, vous utilisez la structure de classe BEM conformément au guide de style du thème de boilerplate CMS Hub.

Consulter le fichier module.css du module

Le fichier module.css doit être vide à ce stade. Pour ajouter du style, copiez et collez le code suivant dans le fichier :

.testimonial { text-align: center; } .testimonial__header { font-weight: bold; } .testimonial__picture { display: block; margin: auto; }

Après avoir ajouté le code, enregistrez le fichier.

Transférer vos modifications locales vers votre compte HubSpot

Après avoir enregistré vos modifications locales, transférez-les vers votre compte HubSpot.

  • Accédez à votre terminal et assurez-vous que vous êtes dans le bon répertoire.
  • Exécutez la commande watch pour transférer les modifications vers HubSpot lors de la sauvegarde : hs watch <src> <destination>
hs watch my-theme my-theme

Prévisualiser vos modifications locales dans HubSpot

  • Dans votre compte HubSpot, accédez à Marketing > Fichiers et modèles > Outils de conception.
  • Dans la barre latérale gauche, accédez au thème que vous avez créé, puis ouvrez le dossier des modules et sélectionnez le module Témoignage.
  • Le module étant ouvert, vous devriez maintenant voir vos modifications dans les volets module.html et module.css.
  • Dans l'angle supérieur droit, cliquez sur Aperçu. Un nouvel onglet s'ouvrira pour afficher l'aperçu du module. 
Exemple d'aperçu de module

Pour récapituler ce tutoriel jusqu'ici, vous avez :

  • créé un module dans HubSpot ;
  • transféré ce module dans votre environnement local ;
  • apporté des modifications au HTML + HubL et aux CSS en utilisant vos outils de développement locaux.

Dans la prochaine partie de ce tutoriel, vous découvrirez comment utiliser le module dans un modèle.

Ajouter le module à un modèle

Pour cette partie du tutoriel, vous travaillerez principalement avec les dossiers modules et templates dans vos fichiers de thème locaux. 
theme-folder-structure-getting-started-with-modules0

Dans leur définition la plus élémentaire, les modules sont des zones modifiables des modèles et des pages HubSpot. Vous pouvez insérer des modules dans des modèles dans HubSpot en utilisant le gestionnaire de conception. Ici, vous allez utiliser HubL pour ajouter le module à un modèle dans votre environnement local.   

  • Dans votre éditeur de code, ouvrez le dossier templates, puis le fichier home.html
  • Dans le fichier home.html, accédez au dernier élément dnd_section, qui débute vers la ligne 28. C'est dans cette section que vous ajouterez votre nouveau module.
    home-html-add-testimonial-module-to-section0
  • Dans dnd_section, au-dessus des autres éléments dnd_modules, copiez et collez la balise de module HubL suivante :
{% dnd_module path= “../modules/Testimonial.module”, offset=0, width=4 %} {% end_dnd_module %}

Cette balise HubL référence votre nouveau module par son chemin de fichier relatif. Pour que le module s'adapte uniformément aux deux autres modules de dnd_section, il attribue également des valeurs width et offset :

  • Le CMS de HubSpot utilise un système de grille à 12 colonnes. Par conséquent, pour espacer ce module uniformément avec les deux autres, vous devrez mettre à jour chaque module dans dnd_section pour avoir une largeur de 4.
  • Ensuite, le premier dnd_module dans le groupe (testimonial) aura un décalage de 0 pour le positionner en premier.
  • Le second dnd_module (linked_image) aura un décalage de 4 pour le positionner en second.
  • Le troisième dnd_module (rich_text) aura un décalage de 8 pour le positionner en troisième position.

Après avoir défini offset et width pour chaque dnd_module, votre code se présentera comme suit :

{% dnd_section background_color="#f8fafc", vertical_alignment="MIDDLE" %} {% dnd_module path= “../modules/Testimonial.module”, offset=0, width=4 %} {% end_dnd_module %} {% dnd_module path="@hubspot/linked_image", img={ "alt": "Stock placeholder image with grayscale geometrical mountain landscape", "loading": "lazy", "max_height": 451, "max_width": 605, "size_type": "auto_custom_max", "src": get_asset_url("../images/grayscale-mountain.png") }, offset=4, width=4 %} {% end_dnd_module %} {% dnd_module path="@hubspot/rich_text", html="<h2>Provide more details here.</h2><p>Use text and images to tell your company’s story. Explain what makes your product or service extraordinary.</p>" offset=8, width=4 %} {% end_dnd_module %} {% end_dnd_section %}

Lorsque vous ajoutez un module à une zone de glisser-déposer, la balise du module ne nécessite pas de nom unique. Toutefois, lorsque vous ajoutez un module à un fichier HTML en dehors des zones de glisser-déposer, vous devez attribuer un nom unique au module. Vous utiliserez également une syntaxe légèrement différente, comme suit :

{% module "testimonial_one" path="../modules/Testimonial.module" %}

Découvrez-en davantage sur l'utilisation des modules dans les modèles.

Prévisualiser vos modifications dans HubSpot

  • Si vous n'avez pas exécuté la commande watch pour suivre votre travail automatiquement, exécutez à nouveau hs watch <src> <dest>. Assurez-vous que cette commande continue d'être exécutée pendant que vous effectuez les étapes suivantes. 
  • Dans votre compte HubSpot, ouvrez le gestionnaire de conception (Marketing > Fichiers et modèles > Outils de conception).
  • Dans la barre latérale gauche du gestionnaire de conception, sélectionnez le fichier home.html.
  • En haut à droite, cliquez sur Aperçu, puis sélectionnez Aperçu en ligne avec options d'affichage pour ouvrir l'aperçu du modèle dans une nouvelle fenêtre.
Exemple d'aperçu en ligne
  • Dans le nouvel onglet, affichez l'aperçu du modèle, qui doit contenir votre module de témoignage nouvellement ajouté.
testimonial-module-added-to-theme

Personnaliser le module dans le modèle localement

Pour rendre le modèle de la page d'accueil plus intéressant :

  • Retournez dans votre éditeur de code, puis ouvrez le fichier home.html.
  • Ajoutez les paramètres suivants à la balise du module de témoignage :
{% dnd_module path='../modules/Testimonial.module', customer_name = "Mary", profile_pic = { src: "{{ get_asset_url('../images/profile-pic-mary.svg') }}", alt: "Mary Profile Picture" }, testimonial = "Wow, what a product! I can't wait to recommend this to all my family and friends!", offset=0, width=4 %} {% end_dnd_module %}

Les paramètres ci-dessus remplacent les valeurs par défaut que vous avez initialement attribuées à ces trois champs. Chaque paramètre utilise le nom de variable HubL que vous avez précédemment attribué à chaque champ :

  • customer_name : ce paramètre transmet le nom Mary au champ du nom du client, remplaçant la valeur initiale Sally.
  • profile_pic : ce paramètre est un objet qui contient deux propriétés.
    • La propriété src utilise la fonction HubL get_asset_url pour récupérer l'URL de la photo de profil. Notez que le chemin du fichier de l'image est relatif à votre répertoire de travail. Vous devez d'abord ajouter cette image au dossier images dans vos fichiers de thème locaux. Vous pouvez trouver l'image dans le dossier images des fichiers de projet terminés.
    • La propriété alt permet d'attribuer le texte alternatif de l'image.
  • testimonial : ce paramètre permet de transmettre un nouveau texte dans le champ de témoignage.

Pour le champ de texte enrichi, vous pouvez également utiliser la syntaxe de bloc HubL pour écrire un grand bloc de HTML ou de texte :

{% dnd_module path='../modules/Testimonial.module', customer_name = "Mary", profile_pic = { src: "{{ get_asset_url('../images/profile-pic-mary.svg') }}", alt: "Mary Profile Picture" }, offset=0, width=4 %} {% module_attribute "testimonial" %} Wow, what a product! I can't wait to recommend this to all my family and friends! {% end_module_attribute %} {% end_dnd_module %}

Découvrez-en davantage sur la syntaxe des blocs de module.

Si vous avez conservé la commande watch en cours d'exécution dans votre terminal, enregistrez vos modifications pour les envoyer à HubSpot. Vous pouvez ensuite retourner dans le gestionnaire de conception pour prévisualiser le modèle.

Module de Mary dans le modèle

Ajouter deux autres modules de témoignage au modèle

Dans cette étape, vous allez ajouter deux autres modules de témoignage au modèle en suivant les mêmes étapes que précédemment :

  • Accédez à votre éditeur de code, puis ouvrez le fichier home.html.
  • Sous le module de témoignage que vous avez ajouté précédemment, ajoutez une autre instance du module en copiant et collant le code de ce module. Dans le nouveau module de témoignage, spécifiez les détails suivants en suivant les mêmes étapes que ci-dessus :
    • Le nom du client est Ollie.
    • Le témoignage d'Ollie est le suivant : « Je n'arrive pas à croire que j'ai pu mener des activités sans utiliser ce produit ! »
    • Pour la photo d'Ollie, ajoutez le chemin d'accès relatif du fichier dans le dossier images. Vous pouvez obtenir l'image elle-même à partir des fichiers de projet terminés. Puis, donnez à l'image d'Ollie l'attribut alt Image de profil d'Ollie.
    • Pour maintenir l'espacement, définissez offset sur 4 et width sur 4.
  • Sous le deuxième module de témoignage, ajoutez-en un troisième avec les détails suivants :
    • Le nom du client est Erin.
    • Le témoignage d'Erin est le suivant : « Mon activité a presque triplé depuis que j'ai commencé à utiliser ce produit ! Essayez-le sans plus attendre ! »
    • Pour la photo d'Erin, ajoutez le chemin d'accès relatif du fichier dans le dossier images. Puis, donnez à l'image d'Erin l'attribut alt Image de profil d'Erin.
    • Pour maintenir l'espacement, définissez offset sur 8 et width sur 4.
  • Enregistrez vos modifications.

Si vous avez conservé la commande watch en cours d'exécution dans votre terminal, vous pouvez revenir au gestionnaire de conception pour prévisualiser les modifications apportées au modèle. L'aperçu du modèle doit maintenant contenir les trois modules de témoignage.

testimonial-modules-added-to-theme

Pour terminer, vous préparerez le thème à utiliser dans une page en direct en modifiant le fichier theme.json.

Modifier le nom du thème

Si vous souhaitez modifier le nom par défaut du thème, vous pouvez le faire en configurant les champs name et label du fichier theme.json.

// example theme.json { "name": "my_first_theme", "label": "My first theme" }

Après avoir ajouté ce code, enregistrez vos modifications afin que la commande watch envoie vos modifications à HubSpot.

Étapes suivantes

Maintenant que vous avez créé un module personnalisé, que vous l'avez ajouté au modèle home.html et que vous avez éventuellement personnalisé le nom du thème, vous êtes prêt à créer une page en direct à partir du thème. 

Si vous souhaitez suivre un tutoriel similaire qui se concentre sur les thèmes, consultez le tutoriel Premiers pas avec les thèmes. Autrement, découvrez-en davantage sur la création et la personnalisation de pages dans la base de connaissances de HubSpot.

Si vous souhaitez en savoir plus sur les modules, consultez les guides de module suivants :

Autres tutoriels


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