Moduldateien
Bei der Erstellung eines Moduls für Seiten, Blogs und Angebote enthält das Modul drei Front-End-bezogene Dateien, die den Inhalt, das Styling und die Funktionalität des Moduls steuern:
- module.html
- module.css
- module.js
E-Mail-Module unterstützen nicht module.css und module.js. Das liegt daran, dass E-Mail-Clients kein JavaScript unterstützen und die Unterstützung für verknüpfte CSS-Dateien begrenzt ist.
Diese Dateien werden immer auf der Seite gerendert, wenn sich eine Instanz des Moduls auf der Seite befindet.
Wenn eine Seite mehrere Instanzen desselben Moduls enthält, lädt HubSpot module.css und module.js von diesem Modul nur einmal. Standardmäßig werden module.css und module.js nicht asynchron geladen. Sie können dies jedoch ändern, indem Sie css_render_options und js_render_options in der meta.json des Moduls aufnehmen.
Module können im Design-Manager oder lokal über das HubSpot-CLI erstellt werden. Im Design-Manager werden die Moduldateien in einem Editor mit mehreren Fenstern angezeigt.
Wenn ein Modul lokal angezeigt wird, befinden sich die Dateien in module-name.module-Ordnern.
Ob Sie zum Erstellen und Verwalten von Modulen den Design-Manager oder das CLI verwenden, hängt von den Präferenzen Ihres Teams ab. Empfehlungen finden Sie unter Erstellen eines effizienten Entwicklungsworkflows.
Die module.html-Datei ist für HTML und HubL gedacht. Im Allgemeinen bestimmt der Ort, an dem ein Modul im Seiten-Editor oder in der Vorlagendatei platziert ist, wo der Inhalt der Datei module.html gerendert wird.
Diese Datei agiert wie ein HubL-Include an der Stelle auf der Seite, an der das Modul platziert ist. Die module.html-Datei kann über HubL auf die Feldwerte des Moduls zugreifen.
Verwenden Sie die module.css-Datei, um CSS zu einem Modul hinzuzufügen.
Im Allgemeinen unterstützt module.css eine sehr begrenzte Teilmenge von HubL. Sie können jedoch module_asset_url("mein_bild.png") für Bilder verwenden, die als modulverknüpfte Inhaltselemente hinzugefügt wurden. Dies ermöglicht die Verknüpfung von Elementen wie Bildern, die mit dem Modul selbst verpackt sind. Zum Beispiel:
Im Folgenden erfahren Sie, wie Sie das CSS eines Moduls so einrichten, dass es sich dynamisch auf der Grundlage der Felder des Moduls ändert.
Es gibt einige Möglichkeiten, wie Sie das Styling Ihres Moduls auf der Grundlage der Modulfelder beeinflussen können. Wählen Sie die Methode, die für Ihren speziellen Anwendungsfall am besten geeignet ist.
Um ein vordefiniertes Styling für das Modul einzurichten, bei dem die Editoren aus diesen Optionen auswählen können, können Sie ein Modulfeld hinzufügen, um in Ihrer module.html-Datei Klassen festzulegen, die den CSS-Klassen in Ihrer module.css-Datei entsprechen.
Sie können zum Beispiel ein Bild- und ein Textmodul haben. Sie möchten, dass Content-Autoren das Bild auf der Grundlage eines Auswahlfeldes rechts oder links vom Text positionieren können. Dazu könnten Sie Ihre module.html- und module.css-Dateien wie folgt festlegen:
Wenn Sie Content-Autoren direkte Kontrolle über bestimmte Eigenschaften geben müssen und wenn Klassen nicht ideal sind, sollten Sie Stil-Tags mit require_css-Blöcken verwenden.
Um Content-Autoren die direkte Kontrolle über bestimmte Eigenschaften zu geben, ohne Klassen zu verwenden, können Sie stattdessen Styling zur module.html-Datei innerhalb von require_css-Tags hinzufügen. Zum Beispiel:
Da module.html HubL rendern kann, können Sie die Werte der Modulfelder als CSS-Variablen verwenden. Wenn ein Content-Autor das Feld im Seiten-Editor aktualisiert, wird das CSS entsprechend angepasst. Diese Blöcke verschieben die <style>-Tags in die <head> Ihrer Seite innerhalb der standard_header_includes-Anweisung.
Sie können das CSS auch so festlegen, dass dessen Bereich nur für die Modulinstanz gilt, indem Sie das CSS mit scope_css-Tags umschließen. Sie könnten zum Beispiel den obigen Modulcode wie folgt aktualisieren:
<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 %}
Wenn Sie Content-Autoren detaillierte Steuerungsmöglichkeiten über bestimmte Eigenschaften geben müssen und Klassen nicht ideal sind, können Sie die Werte direkt in ein Stilattribut im HTML-Code einfügen.
{# 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>
Wenn Sie viele Eigenschaften haben und der Code schwer zu lesen ist, sollten Sie auf die require_css-Blockmethode umsteigen.
require_css ist eine HubL-Funktion, die Sie zu module.html hinzufügen können und die HubSpot mitteilt, dass ein bestimmtes Modul oder eine Vorlage eine bestimmte CSS-Datei zum Anzeigen benötigt. Ein Link-Tag, das auf die CSS-Datei verweist, wird der <head> der Seite innerhalb des standard_header_includes hinzugefügt.
Die require_css-Funktion lädt diese CSS-Datei nur einmal, unabhängig davon, wie oft dieselbe Datei von Modulen und Vorlagen auf einer bestimmten Seite benötigt wird. Dies eignet sich hervorragend für Situationen, in denen Stile von mehreren Modulen gemeinsam genutzt werden. Das Hinzufügen von CSS direkt zu den Haupt-Stylesheets, die auf jeder Seite Ihrer Website verwendet werden, ist möglicherweise jedoch nicht sinnvoll.
require_css und verlinkte CSS-Dateien erfüllen denselben Zweck, aber require_css kann auf der Grundlage von Feldwerten bedingt verwendet werden. Dies verhindert das Laden von unnötigem Code.
<!-- module.html -->
{{ require_css(get_asset_url("/modules/shared_layout_styles.css")) }}
Verwenden Sie die module.js-Datei, um JavaScript zu einem Modul hinzuzufügen.
Wie die module.css-Datei unterstützt auch die module.js-Datei kein HubL.
Es gibt einige Möglichkeiten, Module zu erstellen, bei denen das JavaScript je nach Feldwert unterschiedlich reagiert. Wenn Sie wissen, welche Methode wann zu verwenden ist, können Sie auf jeder Seite, auf der das Modul verwendet wird, Performance-Vorteile erzielen.
Wenn Sie zum Beispiel ein benutzerdefiniertes Bildmodul haben, möchten Sie Content-Autoren die Möglichkeit geben, das Bild in einer Lightbox zu öffnen. Content-Autoren möchten dies nur für bestimmte Bilder und nicht für alle Instanzen des Moduls.
Datenattribute sind benutzerdefinierte HTML 5-Standardattribute, die Entwickler zu Elementen hinzufügen. So wie alle Elemente class="IhrKlassename" unterstützen, unterstützen auch alle Elemente data-your-attribute="IhrWert".
<!-- 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>
Sie können Datenattribute verwenden, um die Feldwerte Ihrer Modulinstanzen zu übergeben, die von Ihrer module.js-Datei verarbeitet werden sollen.
Um die Werte in Ihrer module.js-Datei zu verwenden, müssen Sie alle Instanzen Ihres Moduls durchlaufen. Durch Hinzufügen eines modulspezifischen Klassennamens zum äußersten Wrapper-Element Ihres Moduls erhalten Sie ein Ziel, das Sie verwenden können, damit Sie alle Instanzen Ihres Moduls durchlaufen können.
// 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.
});
}
});
Die Datenattribute ermöglichen es Ihnen, die Feldwerte für jede Modulinstanz in Ihrer module.js abzurufen.
In anspruchsvollen Situationen, z. B. bei Verwendung einer JavaScript-Templating-Bibliothek oder eines reaktiven Frameworks wie Vue.js oder React.js, möchten Sie möglicherweise nur die Daten ausgeben, während das Framework das Rendering übernimmt.
In diesem Fall verwenden Sie ein Skript-Tag, das von einem require_js-Block umschlossen ist, um Variablen bereitzustellen, auf die Sie von Ihrem Templating-Skript aus zugreifen können.
{% require_js %}
<script>
let myArray = [
{%- for item in module.repeating_text_field -%}"{{ item }}",{%- endfor -%}
];
</script>
{% end_require_js %}
Diese Technik kann nützlich sein, um fortgeschrittene Anwendungen mit einem ersten Datensatz zu versorgen, von dem aus dann gerendert werden kann. Dadurch entfällt ein anfänglicher JavaScript-Aufruf zum Abrufen von Daten.
require_js ist eine HubL-Funktion, die HubSpot mitteilt, dass ein bestimmtes Modul oder eine Vorlage eine bestimmte JavaScript-Datei benötigt, um korrekt geladen zu werden. Die Funktion benötigt zwei Parameter: den Pfad zur Datei und den Ort, an dem die Datei hinzugefügt werden soll ("head" oder "footer").
In einem Modul kann require_js nur zur module.html hinzugefügt werden. Die JavaScript-Datei, auf die in der require_js-Anweisung verwiesen wird, wird nur einmal pro Seite geladen, unabhängig davon, wie oft sie von Modulen und Vorlagen auf der Seite benötigt wird. Dadurch wird die Anzahl der HTTP-Anfragen reduziert und doppelter Code vermieden.
Es gibt einige Situationen, in denen dies praktisch ist:
- Wenn Sie mehrere Module oder Vorlagen haben, die dasselbe JavaScript benötigen, können Sie
require_js verwenden, um dieses Skript modulübergreifend zu nutzen.
- Wenn Sie mit einem JavaScript-Bundler wie Webpack arbeiten, ist es möglicherweise einfacher, Ihre js-Dateien an einem bestimmten Ort auszugeben. Mit
require_js können Sie das JavaScript mit Ihrem Modul verknüpfen.
require_js und verknüpfte JavaScript-Dateien erfüllen denselben Zweck, aber require_js kann auf der Grundlage von Feldwerten bedingt ausgeführt werden. Dadurch wird verhindert, dass unnötiger Code geladen wird. Außerdem haben Sie die Möglichkeit, JavaScript in die Kopfzeile zu laden, falls Sie dies benötigen.
Da JavaScript das Rendern blockiert, ist "footer" der Standardort, an den require_js JavaScript platziert. Erfahren Sie mehr über die Optimierung der Leistung.
Vielen Dank, dass Sie Ihr Feedback mit uns geteilt haben.
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.