Default module versioning
Releasing a new version of a module, rather than update the existing version, enables HubSpot to make significant updates without impacting existing content. For example, HubSpot may release a new version of a particular module to better organize fields and provide more styling options, or to improve functionality by adding JavaScript.
New versions of modules are first released to new HubSpot accounts created after a certain date. This means that different accounts may be using different versions of the same default module. If multiple accounts are using a theme that you built, you'll need to take module versioning into consideration so that the theme works as expected across all accounts. Below, learn more about how to develop your theme with versioning in mind, and which modules have multiple versions.
HubSpot's existing default modules are treated as v0
modules, while new versions are released started at v1
. For compatibility, HubSpot automatically maps v0
fields to v1
fields, which means that references to module fields are forward compatible. However, field references are not backwards compatible, meaning that v1
field references won't map to v0
fields.
To account for changes in an module's HTML, CSS, and JavaScript, you can use conditional statements to configure it depending on the account's available versions.
To add add a conditional statement, use get_asset_version("@hubspot/module-name")
within an HTML, CSS, or JavaScript file. The module's version will be returned as a string, enabling you to configure module options based on the returned version.
When developing a theme, you can specify which module versions that you want to support within the theme.json
file. When a version is specified, content editors will only allow access to that version in the editor, and the template will render that version accordingly. On upload via the CLI, or when making changes in the design manager, specified module versions will be validated to ensure validity of the modules and their version definitions.
You can specify supported module versions in theme.json
by including a pinned_module_versions
object. For each module, you can specify a version or a range of versions.
For example, the code below would result in the theme allowing access to either v0
or v1
of the divider module, but only v1
of the search input module.
Any default modules not included in the pinned_module_versions
object will not be restricted to a particular version. In addition, you shouldn't specify versions of default modules that don't currently support versioning, and you can only specify versions that are available (e.g. you can't specify 2
for a module that doesn't have a v2
).
Learn more about submitting to HubSpot's Template Marketplace.
Below, learn more about the modules that currently support versioning.
A new version of the default divider module has been released to accounts created after August 25th, 2022 (changelog announcement). This version update impacts the following module files:
fields.json
module.html
Below, learn more about the new v1
version updates in each file, along with the original v0
version for comparison.
- All fields that were previously in the Content tab have been moved to the Styles tab.
- The following fields have moved, but HubSpot automatically links the previous references to the new field names, so you don't need to make any manual updates:
- The
height
field has been moved tostyles.line.thickness
. - The
width
field has been moved tostyles.size.width
. - The
color
field has been moved tostyles.line.color
. - The
line
type field has been moved tostyles.line.style
.
- The
- The
alignment
field, which was previously a choice field, has been replaced by a new field type of Alignment, and can be accessed understyles.alignment.alignment
. - The
padding
field, which was previously a number field, has been replaced by a new field type of Spacing, and can be accessed understyles.spacing.spacing
. - The
show_padding
field has been removed.
In v1
, styles applied to a horizontal rule are set via <style>
tags in the head of the page. In v0
, these are set via inline styles.
A new version of the language switcher module has been released.
This version update impacts the following module files:
meta.json
fields.json
module.html
module.css
module.js
Below, learn more about the new v1
version updates in each file, along with the original v0
version for comparison.
A placeholder
field has been added with the following options:
show_module_icon
(boolean): when set tofalse
, no icon will appear.title
(string): the placeholder title.description
(string): the placeholder descriptive text.
- Added a checkbox field for displaying an arrow in the language switcher to indicate a dropdown menu.
- Added options for content creators to select from several icon options:
icon
: select from a set of standard icons (default).none
: no icon.custom_icon
: select from previously uploaded images or upload a new image.
- Added an array of style fields for customization in the Styles tab.
The module no longer uses the language switcher HubL tag.
A new version of the default post_listing module was released at the end of March 2024. The new version of this module is built with JavaScript and React as opposed to HubL, and module code is now rendered server-side to improve performance.
It preserves all of the previous module fields while bringing in some modern styling options for the user with new fields for text and layout.
Below, learn more about the new v1
version updates in each file, along with the original v0
version for comparison.
The fields.json
is file replaced by fields.tsx
.
Existing fields
The new version of the module includes all existing module fields.
selectBlog
: a field for selecting the blog to display posts from (aliased to the existingselect_blog
field).listingType
: a field for selecting the attribute to list posts by (aliased to the existinglisting_type
field).postsHeading
: a field for setting the heading text at the top of the listing (aliased to the existinglist_title
field).maxLinks
: a field for setting the maximum number of blog posts to display (aliased to the existingmax_links
field).
New fields
- A
displayForEachListItem
choice field has been added to enable selecting the elements that will display for each blog post, including:- Featured image (
image
) - Post title (
title
) - Author name (
authorName
) - Publish date (
publishDate
)
- Featured image (
- A
headingLevel
choice field has been added to enable selecting thepostsHeading
level (h1
-h6
).
Style fields
The following styling fields have been added:
- Layout styling: a
groupLayout
field group contains astyle
choice field for selecting whether the posts will display as rows or 2-column tiles. - Heading styling: a
groupHeading
field group contains afont
field for stylingpostsHeading
. - Post title styling: a
groupTitle
field group containsfont
,spacing
, andhoverFont
fields for styling post titles. - Author styling: a
groupAuthor
field group contains afont
field for styling the post author name text. - Publish date styling: a
groupPublishDate
field group contains afont
field for styling the publish date text. - Background styling: a background field group contains
backgroundColor
andspacing
fields to style the module background.
The module.html
file is replaced by the index.tsx
file. This file imports the module's various components, then renders the module in a return
statement.
In the new version of this module, styling is handled multiple ways:
- A
styles.module.css
file contains layout and spacing styling for displayed blog posts and their featured images, author text, and publish date text. - The module also uses styled-components to set styling rules at the component level. These rules include hardcoded values and values set through style fields in the page editor.
A new version of the default search input module has been released. This version update impacts the following module files:
fields.json
module.html
module.css
module.js
Below, learn more about the new v1
version updates in each file, along with the original v0
version for comparison.
Existing fields
- The
field_label
andplaceholder
text fields have been moved into thesearch
group. - The
include_search_button
toggle has been removed. - The
content_types
group has been moved into theresults
group.
New fields
- A
button
group has been added, which enables controls for:icon
: the search button's icon.button_label
: the search button's text label.
- A
results
group has been added, which enables controls for:use_custom_search_results_template
: toggle to choose which template is used for the search results page.path_id
: the ID of the page that will be used for search results. The referenced page must contain the search results module.
- A
default_text
group has been added, which allows for the translation of default content.
Style fields
The following style field groups have been added:
container
: fields for styling the module container's background color, border radius, and spacing.field_label
: fields for styling the module's label font and spacing.input
: fields for styling the search input's font, spacing, background color, border, and corner radius.button
: fields for styling the button's font, background color, border, corner radius, and spacing. Also includes options for hover styling and button positioning.autosuggest_results
: fields for styling the auto-suggested results box's background color, border, border radius, spacing, header font, suggestion link font, hover font, and hover background color.
v1
, the module's HTML contains:- More configuration options for the submit button, search input form action URL, and accessibility elements.
- In-editor markup to accurately depict what the module will look like in the content editor.
v1
, the module's CSS includes styling adjustments to better handle display options, responsive elements and accessibility.
v1
, the module's JavaScript contains:- Configurable search results template.
- Translation and accessibility support.
A new version of the default search results module module has been released. This version update impacts the following module files:
fields.json
module.html
module.css
module.js
Below, learn more about the new v1
version updates in each file, along with the original v0
version for comparison.
Existing fields
- The
display_featured_images
field has been moved to theresults
group and renamed todisplay_for_each_result
.
New fields
- A
title
group has been added, which enables controls for:show_title
: a toggle for whether the title displays.heading_tag
: the search results heading level (h1
by default).
- A
pagination
group has been added, which enables controls for pagination, such as showing the number of pages and the previous/next arrows and labels. - A
default_text
group has been added, which allows for the translation of default content.
Style fields
The following style field groups have been added:
container
: a field for styling the module container's spacing.title
: fields for styling the page's title font and capitalization options.results_count_message
: fields for styling the page's result count font and capitalization.featured_image
: fields for styling the featured image's size, aspect ratio, border, radius, and spacing.results
: fields for styling the returned result title and description fonts, as well as spacing between results.pagination
: fields for styling the pagination fonts, icon size, background colors, spacing, border, and corner radius. Includes options for hover styling.
In v1
, the module's HTML contains:
<style>
tags which enable styling adjustments.- No HTML template tag for markup.
- In-editor markup placeholders to show search results and reflect style adjustments in the content editor.
v1
, the module's CSS contains all new CSS to better handle responsive display and accessibility.v1
, the module's JavaScript contains:- Rebuilt code that uses the latest search API.
- Translation and accessibility support.
- Code for rendering search results and pagination.
Thank you for your feedback, it means a lot to us.