Fichiers de modules

Last updated:

Lorsque vous créez un module pour des pages, des blogs et des devis, le module contient trois fichiers d'interface connexes qui contrôlent le contenu, le style et la fonctionnalité du module :

  • module.html
  • module.css
  • module.js

Les modules de messagerie ne prennent pas en charge module.css et module.js. En effet, les clients de messagerie ne prennent pas en charge JavaScript et la prise en charge des fichiers CSS associés est limitée.

Ces fichiers seront toujours rendus sur la page lorsqu'une instance du module se trouve sur la page.

Lorsqu'une page comprend plusieurs instances du même module, HubSpot ne chargera qu'une seule fois module.css et module.js de ce module. Par défaut, module.css et module.js ne se chargent pas de manière asynchrone, mais vous pouvez changer cela en incluant css_render_options et js_render_options dans le meta.json du module.

Les modules peuvent être construits dans le gestionnaire de conception ou localement en utilisant HubSpot CLI. Dans le gestionnaire de conception, les fichiers de modules sont affichés dans un éditeur à plusieurs volets.

cms-dev-custom-module1Lors de l'affichage d'un module en local, les fichiers sont contenus dans les dossiers module-name.module.

cms-dev-custom-module0La décision d'utiliser le gestionnaire de conception ou le CLI pour créer et gérer les modules dépend des préférences de votre équipe. Voir la création d'un workflow efficace pour les développeurs pour des recommandations.

HTML et HubL (module.html)

Le fichier module.html est destiné au HTML et au HubL. En général, l'endroit où un module est placé dans l'éditeur de page ou le fichier de modèle détermine l'endroit où le contenu du fichier module.html est rendu. 

Ce fichier agit comme un HubL dans la page où le module est placé. Le fichier module.html peut accéder aux valeurs des champs du module via HubL.

CSS (module.css)

Utilisez le fichier module.css pour ajouter de la CSS à un module.

En général, module.css prend en charge un sous-ensemble très limité de HubL. Cependant, vous pouvez utiliser module_asset_url("my-image.png") pour les images ajoutées en tant que ressources associées à un module. Cela permet d'associer des ressources telles que des images, compilées avec le module lui-même. Par exemple :

.testimonial-module__wrapper{ background: url("{{ module_asset_url("bg-pattern.png") }}"); background-repeat:repeat; min-height:200px; width:100%; display:block; }

Découvrez ci-dessous comment configurer la CSS d'un module pour qu'elle change dynamiquement en fonction des champs du module.

Stylisation basée sur les valeurs des champs du module

Il existe plusieurs façons d'influencer le style de votre module en fonction des champs du module. Choisissez la méthode qui convient le mieux à votre cas d'utilisation spécifique.

Classe CSS

Pour créer un style prédéfini pour le module avec la possibilité pour les éditeurs de choisir parmi ces options, vous pouvez ajouter un champ de module pour définir des classes dans votre fichier module.html qui correspondent aux classes CSS dans votre fichier module.css.

Par exemple, vous pouvez avoir un module image et un module texte. Vous souhaitez que les créateurs de contenu puissent positionner l'image à droite ou à gauche du texte en fonction d'un champ de sélection. Pour ce faire, vous pouvez définir vos fichiers module.html et module.css comme suit :

<!-- module.html --> <section class="img-text__wrapper img-text--{{ module.positioning }}" aria-label="{{ module.heading }}"> {# module.position is a choice field with two values "img-left" or "img-right". This dictates the order they appear on desktop. Controlled by CSS #} <div class="img-text__img"> <img src="{{ module.image.src }}" alt="{{ module.image.alt }}"> </div> <div class="img-text__text"> <h2> {% inline_text field="heading" value="{{ module.heading }}" %} </h2> {% inline_rich_text field="text" value="{{ module.text }}" %} </div> </section>
/* module.css */ /* CSS that makes the image show adjacent to the text, and positioned based on the positioning field.*/ /* The media query ensures that on mobile the image will always appear above the text for visual consistency. */ @media(min-width:768px){ .img-text__wrapper{ display:flex; align-items:row; } .img-text__img,.img-text__text{ flex:1; padding:10px; } .img-text--img-right{ flex-direction:row-reverse; } }

bloc require_css

Lorsque vous devez donner aux créateurs de contenu un contrôle direct sur des propriétés spécifiques et que les classes ne sont pas idéales, les balises de style avec blocs require_css sont la meilleure option. 

Pour donner aux créateurs de contenu un contrôle direct sur des propriétés spécifiques sans utiliser de classes, vous pouvez ajouter du style au fichier module.html dans les balises require_css. Par exemple :

<div class="img__wrapper"> {% if module.image.src %} {% set sizeAttrs = 'width="{{ module.image.width }}" height="{{ module.image.height }}"' %} {% if module.image.size_type == 'auto' %} {% set sizeAttrs = 'style="max-width: 100%; height: auto;"' %} {% elif module.image.size_type == 'auto_custom_max' %} {% set sizeAttrs = 'width="100%" height="auto" style="max-width: {{ module.image.max_width }}px; max-height: {{ module.image.max_height }}px"' %} {% endif %} <img src="{{ module.image.src }}" alt="{{ module.image.alt }}" {{ sizeAttrs }}> {% endif %} </div> {% require_css %} <style> img { border-width:{{ module.border_width }}px; border-color:rgba({{ module.border_color.color|convert_rgb}},{{ module.border_color.opacity/100 }}); border-style: solid; } </style> {% end_require_css %}

Comme module.html peut rendre HubL, vous pouvez utiliser les valeurs des champs du module comme variables CSS. Lorsqu'un créateur de contenu met à jour le champ dans l'éditeur de page, la CSS est mise à jour en conséquence. Ces blocs déplacent les balises <style> dans le <head> de votre page, dans l'annonce standard_header_includes.

Vous pouvez également configurer la CSS pour qu'elle ne s'applique qu'à l'instance du module en l'encadrant de balises scope_css. Par exemple, vous pouvez mettre à jour le code du module ci-dessus comme suit :

<div class="img__wrapper"> {% if module.image.src %} {% set sizeAttrs = 'width="{{ module.image.width }}" height="{{ module.image.height }}"' %} {% if module.image.size_type == 'auto' %} {% set sizeAttrs = 'style="max-width: 100%; height: auto;"' %} {% elif module.image.size_type == 'auto_custom_max' %} {% set sizeAttrs = 'width="100%" height="auto" style="max-width: {{ module.image.max_width }}px; max-height: {{ module.image.max_height }}px"' %} {% endif %} <img src="{{ module.image.src }}" alt="{{ module.image.alt }}" {{ sizeAttrs }}> {% endif %} </div> {% require_css %} <style> {% scope_css %} img { border-width:{{ module.border_width }}px; border-color:rgba({{ module.border_color.color|convert_rgb}},{{ module.border_color.opacity/100 }}); border-style: solid; } {% end_scope_css %} </style> {% end_require_css %}

Ajouter un style intraligne

Lorsque vous devez donner aux créateurs de contenu un contrôle poussé sur quelques propriétés seulement et que les classes ne sont pas idéales, vous pouvez ajouter directement les valeurs à un attribut de style dans le HTML.

{# Module.html #} <div style="background: rgba({{ module.bg_color.color|convert_rgb }},{{ module.bg_color.opacity/100 }});"> {% inline_rich_text field="richtext" value="{{ module.richtext }}" %} </div>

Si vous avez de nombreuses propriétés et que le code devient difficile à lire, envisagez de passer à la méthode du bloc require_css.

Importer des fichiers CSS spécifiques

require_css est une fonction HubL que vous pouvez ajouter à module.html et qui indique à HubSpot qu'un module ou un modèle particulier nécessite un fichier CSS particulier pour s'afficher. Une balise de lien pointant vers le fichier css est ajoutée à <head> de la page, à l'intérieur de standard_header_includes. 

La fonction require_css ne chargera ce fichier CSS qu'une seule fois, quel que soit le nombre de fois où ce même fichier est requis par les modules et les modèles sur une page particulière. Il est donc idéal pour les situations où les styles peuvent être partagés entre plusieurs modules, mais où l'ajout de CSS directement dans les feuilles de style principales utilisées sur chaque page de votre site n'a pas de sens.

require_css et les fichiers CSS associés remplissent le même objectif, mais require_css peut être utilisé de manière conditionnelle en fonction des valeurs des champs. Cela évite de charger du code inutile.

<!-- module.html --> {{ require_css(get_asset_url("/modules/shared_layout_styles.css")) }}

JavaScript (module.js)

Utilisez le fichier module.js pour ajouter du JavaScript à un module.

Comme le fichier module.css, le fichier module.js ne prend pas en charge HubL.

Script basé sur les valeurs des champs

Il existe plusieurs façons de concevoir des modules, où JavaScript agit différemment en fonction des valeurs des champs. Comprendre quelle méthode utiliser et à quel moment peut se traduire par des gains de performance sur chaque page où le module est utilisé. 

Par exemple, vous avez un module d'image personnalisé et vous voulez donner aux créateurs de contenu la possibilité d'ouvrir l'image dans une galerie. Les créateurs de contenu veulent l'utiliser que pour des images spécifiques, et non pour toutes les instances du module.

Attributs des données

Les attributs de données sont des attributs personnalisés de la norme HTML 5 que les développeurs ajoutent aux éléments. De même que tous les éléments prennent en charge class="yourClassName", tous les éléments prennent en charge data-your-attribute="yourValue".

<!-- module.html--> <div class="img-module img-module__wrapper" data-lightbox="{{ module.is_lightbox_enabled }}" data-caption="above"> <!-- module.is_lightbox_enabled is a boolean field, module.caption_position is a choice field. --> {% if module.image.src %} {% set sizeAttrs = 'width="{{ module.image.width }}" height="{{ module.image.height }}"' %} {% if module.image.size_type == 'auto' %} {% set sizeAttrs = 'style="max-width: 100%; height: auto;"' %} {% elif module.image.size_type == 'auto_custom_max' %} {% set sizeAttrs = 'width="100%" height="auto" style="max-width: {{ module.image.max_width }}px; max-height: {{ module.image.max_height }}px"' %} {% endif %} <img src="{{ module.image.src }}" alt="{{ module.image.alt }}" {{ sizeAttrs }}> {% endif %} </div>

Vous pouvez utiliser les attributs de données pour transmettre les valeurs des champs de vos instances de module qui seront traitées par votre fichier module.js.

Pour utiliser les valeurs de votre fichier module.js, vous devrez parcourir en boucle toutes les instances de votre module. L'ajout d'un nom de classe spécifique au module à l'élément encadreur le plus externe de votre module vous donnera une cible à utiliser, afin que vous puissiez parcourir en boucle chacune de vos instances de module.

// module.js let imgModules = document.getElementsByClassName('img-module'); Array.from(imgModules).forEach(function(element) { // loop through each of the instances of the module // set data attributes to variables to make it easy to work with let isLightboxEnabled = element.dataset.lightbox; let captionStyle = element.dataset.caption; if(isLightboxEnabled){ element.addEventListener('click', function(){ showLightbox(captionStyle); // Execute your code for the action you want to take, you can pass your data attributes into functions from libraries. }); } });

Les attributs de données vous permettront de récupérer les valeurs des champs pour chaque instance de module dans votre module.js. 

bloc require_js

Dans des situations avancées, par exemple lors de l'utilisation d'une bibliothèque de modèles JavaScript ou d'un cadre réactif comme Vue.js ou React.js, vous préférerez peut-être n'afficher que les données, et voir le cadre se charger du rendu.

Dans ce cas, utilisez une balise script entourée d'un bloc require_js pour fournir des variables auxquelles vous pouvez accéder à partir de votre script de modélisation.

{% require_js %} <script> let myArray = [ {%- for item in module.repeating_text_field -%}"{{ item }}",{%- endfor -%} ]; </script> {% end_require_js %}

Cette technique peut être utile pour fournir aux applications avancées un ensemble initial de données à partir desquelles effectuer le rendu. Cela élimine un appel JavaScript initial pour récupérer les données.

require_js

require_js est une fonction HubL qui indique à HubSpot qu'un module ou un modèle particulier nécessite un fichier JavaScript particulier pour être chargé correctement. La fonction prend deux paramètres : le chemin d'accès au fichier et l'emplacement où le fichier doit être ajouté ("head" ou "footer"). 

Dans un module, require_js ne peut être ajouté que dans le module.html. Le fichier JavaScript mentionné dans l'annonce require_js ne sera chargé qu'une fois par page, quel que soit le nombre de fois où il est requis par les modules et les modèles de la page. Cela réduit le nombre de requêtes HTTP et évite la duplication du code. 

Certaines situations où cela devient pratique :

  • Si vous avez plusieurs modules ou modèles qui nécessitent le même JavaScript, vous pouvez utiliser require_js pour partager ce script entre les modules.
  • Si vous travaillez avec un pack JavaScript comme webpack, il peut être plus facile d'envoyer vos fichiers js à un emplacement spécifique. En utilisant require_js, vous pouvez associer JavaScript à votre module.

require_js et les fichiers JavaScript associés servent le même objectif, mais require_js peut être fait de manière conditionnelle en fonction des valeurs des champs. Cela évite de charger du code inutile. Vous avez également la possibilité de charger JavaScript dans l'en-tête, si vous en avez besoin.

Puisque JavaScript bloque le rendu, l'emplacement par défaut require_js pour JavaScript est le "footer". En savoir plus sur l'optimisation des performances.

Informations associées

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