{% if module.image.src %}
{% endif %}
{% if module.heading %}
{{ module.heading }}
{% endif %} {% if module.body_text %}{{ module.body_text }}
{% endif %}
{% if module.cta_button %}
{% cta guid="{{ module.cta_button }}" %}
{% endif %}
{# Access a link field #}
{{ module.cta_link.name }}
```
### Conditionals
```html
{# Show an element only if the field has a value #}
{% if module.heading %}
{{ module.heading }}
{% endif %} {# Conditional with else #} {% if module.image.src %}
{% else %}
{% endif %}
```
### Loops (for repeatable fields)
```html
{# Iterate over a repeatable field #}
{% for item in module.items %}
{{ item.title }}
{{ item.description }}
{% for card in module.cards %}
{% endfor %}
```
---
## Modules with Custom JavaScript and CSS
### Module CSS
The `module.css` file contains the module's styles. HubSpot loads them automatically when the module is present on the page:
```css
.my-module {
padding: 4rem 0;
}
.my-module__container {
max-width: 1200px;
margin: 0 auto;
padding: 0 1.5rem;
display: grid;
grid-template-columns: 1fr 1fr;
gap: 3rem;
align-items: center;
}
.my-module__heading {
font-size: 2rem;
font-weight: 700;
margin-bottom: 1rem;
}
```
### Module JavaScript
The `module.js` file contains the module's JavaScript. HubSpot loads it automatically at the end of the body:
```javascript
// Access module fields from JavaScript
var moduleData = {{ module | tojson }};
// Initialise module functionality
document.addEventListener('DOMContentLoaded', function() {
var moduleEl = document.querySelector('.my-module');
if (!moduleEl) return;
// Module logic
initSlider(moduleEl);
});
function initSlider(container) {
// Slider implementation
}
```
---
## Global Modules vs Section Modules
### Global modules
Global modules are modules that are shared across multiple pages. When a global module is edited on a page, the changes are applied to all pages that use that module. They are ideal for elements such as the header, footer, announcement banners or pop-ups.
To create a global module, set `"global": true` in the `meta.json` file.
### Section modules
Section modules are modules that can be edited independently on each page. They are the most common modules and are used for most content blocks.
---
## Testing and Debugging Modules
### HubSpot Design Manager Preview
The HubSpot Design Manager includes a preview mode that allows you to see how the module renders with different field values.
### HubSpot CLI Watch Mode
HubSpot CLI's `watch` mode automatically synchronises local changes with HubSpot, enabling a very fast development cycle:
```bash
hs watch --src ./my-module.module --dest @hubspot/my-module.module
```
### HubL Debugging
To debug HubL templates, use the `pprint` filter to print the value of a variable:
```html
{# Print the full module value for debugging #}
{{ card.card_title }}
{{ card.card_description }}
{{ module | pprint }}
```
---
## Module Development Best Practices
**1. Use descriptive names for fields.** Field names should be clear and descriptive so that marketing editors understand what content to enter.
**2. Provide default values.** Define default values for all fields so that the module looks good when first added to a page.
**3. Use conditional fields.** Use the `visibility` property to show or hide fields based on the value of other fields, simplifying the editor interface.
**4. Organise fields into groups.** Group related fields into groups to make the editor interface more intuitive.
**5. Use CSS variables for colour customisation.** Instead of individual colour fields, use CSS variables so that the module respects the theme's design system.
**6. Document modules.** Use the `help_text` field in `meta.json` to document the module's purpose and how to use it.
**7. Version modules.** Use version control (Git) to manage changes to modules and facilitate collaboration.
---
## Frequently Asked Questions
**Can I use JavaScript frameworks (React, Vue) in HubSpot CMS modules?**
Yes, it is possible to use React or Vue in HubSpot CMS modules. However, for most use cases, vanilla JavaScript or jQuery are sufficient and have better performance. If you need to use React, consider using HubSpot CMS with a headless approach.
**How many custom modules can I create in HubSpot CMS?**
There is no official limit on the number of custom modules you can create in HubSpot CMS.
**Can I share modules between different HubSpot accounts?**
Yes, you can export modules from one HubSpot account and import them into another. You can also publish modules to the HubSpot Marketplace to share them with the community.
**Do custom modules affect page performance?**
Custom modules can affect performance if they include heavy JavaScript or CSS. Follow performance best practices: minimise CSS and JavaScript, use lazy loading for images and avoid blocking rendering.
**Can I use custom modules in HubSpot emails?**
Yes, you can use custom modules in HubSpot email templates. However, email templates have additional restrictions (JavaScript cannot be used, CSS must be inline).
---
## Conclusion
Custom modules are the most powerful tool in the HubSpot CMS development ecosystem. By mastering their development, you can create content editing experiences that combine the flexibility of custom development with the ease of use that marketing teams need.
At Emovere we specialise in the development of custom modules and themes for HubSpot CMS. If you need to develop custom modules for your HubSpot website, contact our team.
---
## References
[1] HubSpot — Custom Module Documentation. https://developers.hubspot.com/docs/cms/building-blocks/modules
[2] HubSpot — HubL Reference. https://developers.hubspot.com/docs/cms/hubl
[3] HubSpot — CMS CLI Documentation. https://developers.hubspot.com/docs/cms/developer-reference/local-development-cms-cli
[4] HubSpot — Module Fields Reference. https://developers.hubspot.com/docs/cms/building-blocks/module-theme-fields
[5] HubSpot — Design Manager Overview. https://knowledge.hubspot.com/website-pages/get-started-with-the-design-manager
