Premiers pas avec les modules

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 comprenant un champ d'image, un champ de texte et un champ de texte enrichi. 

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 notre module personnalisé.
3. images : le dossier contenant les photos de profil que vous utiliserez dans le module de témoignage. 

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.

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 npm install -g @hubspot/cli pour installer l'ILC globalement. Pour installer l'ILC uniquement dans votre répertoire actuel, exécutez npm install @hubspot/cli.
• Dans le répertoire où vous allez stocker les fichiers de votre thème, exécutez 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éé.

• Dans le terminal, exécutez hs create website-theme my-theme. Un dossier de thème sera alors créé dans votre répertoire de travail, contenant les éléments du boilerplate.
• Téléchargez les fichiers vers votre compte en exécutant hs upload<src> <destination>. 
  • <src> est le chemin d'accès au fichier local, relatif à votre répertoire de travail actuel.
  • <destination> est le chemin de destination dans votre compte HubSpot. La destination peut être 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.

• À tout moment, vous pouvez télécharger manuellement les modifications enregistrées vers HubSpot en exécutant hs upload. Toutefois, vous pouvez également exécuter hs watch <src> <destination> pour télécharger automatiquement les modifications locales lors de la sauvegarde. Pour arrêter de regarder, vous pouvez appuyer sur Ctrl+C.

• 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.
  
• Sélectionnez la case à cocher Pages pour que le module soit disponible pour les sites web et les pages de destination.
• Saisissez un nom de fichier pour votre module, puis cliquez sur Créer.

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.

Pour ajouter ces champs :

• Dans la barre latérale droite, cliquez sur le menu déroulant Ajouter un champ, puis sélectionnez Texte.
  
• À côté de l'icône du crayon en haut à droite, dans le champ de texte, 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.

• Dans la barre latérale droite, cliquez sur l'icône du fil d'Ariane pour revenir au menu principal du module.
• 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 du client.

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

Jusqu'à présent, vous avez ajouté des données dans plusieurs champs de module. Même si ces champs contiennent des données, le module lui-même ne les affichera pas encore, car vous n'avez pas ajouté les champs au code HTML du module. Par conséquent, le champ module.html est vide à ce stade. 

Pour ajouter du HubL au module, copiez et collez le code suivant dans le fichier module.html :

Dans le code ci-dessus, la notation par points est utilisée pour accéder aux données de divers champs :

• La variable module représente le module lui-même, tandis que le champ customer_name représente le nom de variable que vous avez attribué au champ de texte à l'étape précédente. Ensemble, module.customer_name recherche le texte du nom du client dans le module.
• La valeur module.profile_pic.src accède au champ profile_pic du module et recherche la valeur src, qui est l'URL de l'image. Cependant, même si la variable HubL contient l'URL de l'image, vous devez la placer dans une balise HTML d'image pour la rendre sur la page.

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.

Dans l'angle supérieur droit du gestionnaire de conception, cliquez sur Publier les modifications.

Une fois votre module créé, vous allez le transférer dans votre environnement local pour le copier dans le dossier de votre thème. Il est important de noter que vous pouvez également créer des modules à partir de zéro localement, mais pour les besoins de ce tutoriel, il est utile de voir le processus HubSpot ainsi que le processus local. 

Pour transférer votre module dans votre environnement 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. 
    
  • <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.

Pour les besoins de ce tutoriel, vous devez faire transférer le module dans le dossier src/modules du répertoire my-theme que vous avez créé à l'étape 1. Découvrez-en davantage sur la commande fetch.

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 :

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.

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 :

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.  

Pour illustrer la relation entre ces champs et leurs données :

• Dans votre environnement local, modifiez la valeur par défaut du champ de texte enrichi Testimonial comme suit : « Je le recommanderais à 100 % à mes collègues et amis. »
• Enregistrez le fichier. Nous y reviendrons à l'étape 10.

Le fichier module.html doit contenir le HubL et le HTML que vous avez saisis dans l'éditeur de module HubL + HTML à l'étape 4.

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

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

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

Après avoir apporté vos modifications au module localement, vous les transférerez dans 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>. 
  • <src> est le chemin d'accès au fichier local, relatif à votre répertoire de travail actuel.
  • <destination> est le chemin de destination dans votre compte HubSpot. La destination peut être 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.

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

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 ;
• téléchargé vos modifications sur votre compte HubSpot à l'aide de la commande d'ILC watch (étape 10).

Mais ce n'est qu'une des nombreuses méthodes disponibles pour créer un module. Par exemple, vous pouvez également :

1. créer un module dans le gestionnaire de conception ;
2. transférer ce module à partir de notre compte HubSpot.
3. Avant d'effectuer toute modification, exécutez la commande watch. Avec la commande watch en cours d'exécution, vous pouvez modifier votre module localement et voir les modifications apparaître immédiatement dans votre compte HubSpot.

Lorsque vous développez sur HubSpot, expérimentez votre workflow afin d'identifier ce qui fonctionne le mieux pour vous.

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

Partie 2 : Utilisation du module dans un modèle

Dans votre éditeur de code, accédez au répertoire my-theme que vous avez créé à l'étape 1 lors du téléchargement initial du thème de boilerplate CMS Hub.

Pour cette partie du tutoriel, vous travaillerez principalement avec les dossiers modules et templates. 

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, nous allons utiliser HubL pour ajouter des modules à un modèle dans notre 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 devrait commencer vers la ligne 28. C'est dans cette section que vous ajouterez votre nouveau module.
  
• Dans dnd_section, au-dessus des autres éléments dnd_modules, copiez et collez la balise de module HubL suivante :

Cette balise référence votre nouveau module par son chemin de fichier relatif. Dans l'étape suivante, vous ajouterez d'autres paramètres facultatifs à la balise.

• Si vous n'avez pas gardé la commande watch en marche pour suivre votre travail automatiquement, exécutez à nouveau hs watch <src> <dest>dans votre terminal pour télécharger vos modifications. Assurez-vous que cette commande continue d'être exécutée pendant que vous effectuez les étapes suivantes. 
• Dans votre compte HubSpot, accédez au 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 homepage.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.

• Dans le nouvel onglet, ouvrez votre aperçu, qui doit contenir votre module de témoignage nouvellement ajouté.

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

• Retournez dans votre éditeur de code, puis ouvrez le fichier homepage.html.
• Ajoutez les paramètres suivants à la balise du module de témoignage :

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 attribué à chaque champ à l'étape 3 :

• customer_name : ce paramètre transmet le nom Mary au champ du nom du client.
• 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 de Mary. Notez que le chemin du fichier de l'image est relatif à votre répertoire de travail. 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 :

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.

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 d'images. Puis, donnez à l'image d'Ollie l'attribut alternatif « Image de profil d'Ollie ».
• 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 d'images. Puis, donnez à l'image d'Ollie l'attribut alt « Image de profil d'Erin ».
• 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.

Dans la partie suivante de ce tutoriel, vous allez créer une page HubSpot en utilisant ce modèle.

Partie 3 : Utilisation du modèle personnalisé dans une page HubSpot

Avant de pouvoir créer une page avec le modèle de page d'accueil que vous venez de modifier, vous devez effectuer un dernier changement dans votre environnement local en modifiant le fichier theme.json. Dans ce fichier, vous désignerez ce répertoire comme un thème accessible à travers différents produits HubSpot.  

Dans votre éditeur de code, ouvrez le fichier theme.json, puis collez l'objet JSON suivant dans le fichier (sans le commentaire //theme.json) :

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

Pour créer une page :

• Dans HubSpot, accédez à Marketing > Site web > Pages de site web.
• Cliquez sur Créer dans l'angle supérieur droit, puis sélectionnez Page de site web. Donnez un nom à la page, puis cliquez sur Créer la page.
• Sur l'écran Choisir un modèle, sélectionnez votre thème personnalisé à l'aide du menu déroulant du sélecteur de thème. 
  
  • Si vous ne voyez pas votre thème, sélectionnez Changer de thème dans le menu déroulant du sélecteur de thème.

• Dans votre thème, cliquez sur le modèle Accueil. Dans l'angle supérieur droit, cliquez sur Sélectionner un modèle.

Dans l'éditeur de page, vous devriez voir toutes les modifications que vous avez apportées tout au long de ce tutoriel.

Pour personnaliser la page :

• Dans la barre latérale gauche, utilisez l'onglet Ajouter pour choisir parmi les modules par défaut et personnalisés. Pour ajouter un module à la page, cliquez et faites-le glisser dans le corps de la page dans le volet central de l'éditeur.
• Dans la barre latérale gauche, utilisez l'onglet Contenu pour passer en revue les modules actuels de la page.
• Dans la barre latérale de gauche, utilisez l'onglet Conception pour passer en revue les styles de thèmes disponibles pour la page. 
• Dans le volet central où s'affiche le contenu de votre page, vous pouvez cliquer sur les modules pour modifier leur contenu.
• Vous pouvez visualiser vos modifications à tout moment en cliquant sur Aperçu dans l'angle supérieur droit. Découvrez-en davantage sur la création et la modification de pages.

La dernière étape avant la publication consiste à modifier les paramètres de la page :

• Cliquez sur l'onglet Paramètres en haut de l'éditeur.
• Cliquez sur le champ Titre de la page pour ajouter un titre à la page. Ce titre s'affichera dans l'onglet du navigateur lorsqu'un visiteur accédera à la page.
• Sous URL de la page, cliquez sur le champ Slug de contenu pour définir l'URL de la page. Vous pouvez également cliquer sur le menu déroulant Domaines pour sélectionner l'un de vos domaines connectés.

• Pour publier votre page, dans l'angle supérieur droit, cliquez sur Publier. Une fois publiée, la page sera en ligne à l'URL spécifiée.

• Premiers pas avec les thèmes
• Premiers pas avec les fonctions sans serveur
• Créer un workflow de développement efficace
• Premiers pas avec l'accessibilité
• Utiliser les infrastructures JavaScript sur CMS Hub