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.
{% if get_asset_version("@hubspot/module-name") == "1" %}
hr {
border-bottom-width: 5px;
}
{% endif %}
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.
Please note: this feature is not available for child themes. Instead, child themes will inherit module versions based on the parent theme when provided.
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.
xxxxxxxxxx
"pinned_module_versions": {
"@hubspot/divider": "0-1",
"@hubspot/search_input": "0"
}
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.
In an account's Themes & Modules settings (Settings >** Content** > Themes & Modules) users can opt into new module versions, revert modules updated within the past 30 days, and view the version information for all default modules.
To opt into a new version of a module:
- In your HubSpot account, click the settings icon in the top navigation bar.
- In the left sidebar menu, navigate to Content > Themes & Modules.
- On the Alerts tab, the latest updates for default modules will appear with an Update Available tag. Click View update next to a module to view more details about the update.
- In the panel, review the changes. The panel will include a high-level summary of the update, along with a detailed breakdown of the changes and the assets that will be affected.
- To update the module, click Install update. Then, in the dialog box, click Confirm update. Note that it can take up to 10 minutes for pages and templates to reflect the updated module.
After updating the module, you'll be taken to the Modules tab of the Themes & Modules settings page. On this page, you can see recently updated modules, modules with available updates, and version information for all your account's default modules.
Within 30 days of updating a module, you can revert it to a previous version if needed:
- On the Modules tab, next to the module that you want to revert, click Roll back recent update.
- In the panel, review the module's version history, then click Roll back this update.
- Review the information in the right sidebar to confirm that you'd like to roll back the update, then click Roll back.
- In the dialog box, click Confirm.
After reverting the update, it may take some time for your templates and pages to reflect the reverted module. At any point, you can update the module again by following the update steps above.
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.
xxxxxxxxxx
// v1
[
{
"label": "Styles",
"name": "styles",
"type": "group",
"tab": "STYLE",
"children": [
{
"label": "Line",
"name": "line",
"type": "group",
"children": [
{
"label": "Color",
"name": "color",
"type": "color",
"required": true,
"aliases": ["color"],
"default": {
"color": "#000000",
"opacity": 100
}
},
{
"label": "Style",
"name": "style",
"type": "choice",
"choices": [
["solid", "Solid"],
["dotted", "Dotted"],
["dashed", "Dashed"]
],
"display": "select",
"required": true,
"aliases": ["line_type"],
"default": "solid"
},
{
"label": "Thickness",
"name": "thickness",
"type": "number",
"display": "text",
"max": 10,
"min": 1,
"required": true,
"step": 1,
"default": 1,
"aliases": ["height"],
"suffix": "px"
}
]
},
{
"label": "Size",
"name": "size",
"type": "group",
"children": [
{
"label": "Width",
"name": "width",
"id": "styles.size.width",
"type": "number",
"help_text": "Percentage of the area the divider is placed into.",
"max": 100,
"min": 1,
"required": true,
"step": 1,
"suffix": "%",
"aliases": ["width"],
"default": 50
}
]
},
{
"label": "Alignment",
"name": "alignment",
"type": "group",
"visibility": {
"controlling_field": "styles.size.width",
"controlling_value_regex": "100",
"operator": "NOT_EQUAL"
},
"children": [
{
"label": "Alignment",
"name": "alignment",
"type": "alignment",
"default": {
"horizontal_align": "CENTER"
},
"alignment_direction": "HORIZONTAL"
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "spacing",
"visibility": {
"hidden_subfields": {
"padding": true
}
},
"default": {
"margin": {
"top": {
"value": "10",
"units": "px"
},
"bottom": {
"value": "10",
"units": "px"
}
}
}
}
]
}
]
}
]
xxxxxxxxxx
// v0
[
{
"label": "Height",
"name": "height",
"id": "f25c7200-c134-2cd0-ebac-2f2e7152c0a9",
"type": "number",
"display": "text",
"max": 8,
"min": 1,
"required": true,
"step": 1,
"suffix": "px",
"default": 1
},
{
"label": "Width",
"name": "width",
"id": "69957b03-2442-9cc8-3666-c67e96f37645",
"type": "number",
"help_text": "Percentage of the area the divider is placed into.",
"display": "slider",
"max": 100,
"min": 1,
"required": true,
"step": 1,
"suffix": "%",
"default": 50
},
{
"label": "Color",
"name": "color",
"id": "a3f3e26c-5bca-611e-ea99-c91d4f1c88bb",
"type": "color",
"required": true,
"default": {
"color": "#000000",
"opacity": 100
}
},
{
"label": "Line type",
"name": "line_type",
"id": "5dfe1bf6-99b3-5339-3a05-db1aee413317",
"type": "choice",
"choices": [
["solid", "Solid"],
["dotted", "Dotted"],
["dashed", "Dashed"]
],
"display": "select",
"required": true,
"default": "solid"
},
{
"label": "Alignment",
"name": "alignment",
"id": "2919e8d6-68f4-9cfc-5253-8e36d3f54807",
"type": "choice",
"choices": [
["left", "Left"],
["center", "Center"],
["right", "Right"]
],
"display": "select",
"required": true,
"default": "center"
},
{
"label": "Show padding?",
"name": "show_padding",
"id": "c2849a01-3d7b-a5b7-8d80-969f2a3e65f0",
"type": "boolean",
"default": false
},
{
"label": "Padding",
"name": "padding",
"id": "14154310-667e-8128-0394-96c83342c964",
"type": "number",
"inline_help_text": "Max of 20 pixels",
"visibility": {
"controlling_field": "c2849a01-3d7b-a5b7-8d80-969f2a3e65f0",
"controlling_value_regex": "true",
"operator": "EQUAL"
},
"display": "text",
"max": 20,
"min": 1,
"required": true,
"step": 1,
"suffix": "px",
"default": 5
}
]
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.
xxxxxxxxxx
// meta.json
{
"label": "Language Switcher",
"host_template_types": ["PAGE", "BLOG_POST", "BLOG_LISTING"],
"icon": "../img/icon/edited-language.svg",
"extra_classes": "widget-type-language_switcher",
"smart_type": "NOT_SMART",
"master_language": "en",
"placeholder": {
"show_module_icon": true,
"title": "No language variant setup",
"description": "This page does not have a language variant setup."
},
"categories": ["functionality"],
"content_tags": [
{
"name": "OTHER_INDUSTRY",
"source": "MARKETPLACE"
},
{
"name": "COMPATIBLE_PAGE",
"source": "MARKETPLACE"
}
],
"editable_contexts": ["TEMPLATE"]
}
xxxxxxxxxx
// meta.json
{
"label": "Language Switcher",
"host_template_types": ["PAGE", "BLOG_POST", "BLOG_LISTING"],
"icon": "../img/icon/edited-language.svg",
"extra_classes": "widget-type-language_switcher",
"smart_type": "NOT_SMART",
"master_language": "en",
"categories": ["functionality"],
"content_tags": [
{
"name": "OTHER_INDUSTRY",
"source": "MARKETPLACE"
},
{
"name": "COMPATIBLE_PAGE",
"source": "MARKETPLACE"
}
],
"editable_contexts": ["TEMPLATE"]
}
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.
xxxxxxxxxx
import {
FieldGroup,
ModuleFields,
TextField,
FontField,
SpacingField,
BlogField,
ChoiceField,
NumberField,
} from '@hubspot/cms-components/fields';
export const fields = (
<ModuleFields>
<BlogField
label="Select blog to display"
name="selectBlog"
propertyAliasesPaths={{ selectBlog: ['select_blog'] }}
/>
<ChoiceField
label="Sort posts by"
name="listingType"
display="select"
placeholder="Search"
choices={[
['recent', 'Most recent'],
['popular_all_time', 'Most popular - all time'],
['popular_past_year', 'Most popular - past year'],
['popular_past_six_months', 'Most popular - past six months'],
['popular_past_month', 'Most popular - past month'],
]}
propertyAliasesPaths={{ listingType: ['listing_type'] }}
default="recent"
/>
<ChoiceField
label="Choose what shows in your feed"
name="displayForEachListItem"
display="checkbox"
multiple={true}
reorderingEnabled={false}
choices={[
['image', 'Image'],
['title', 'Title'],
['authorName', 'Author name'],
['publishDate', 'Publish date'],
]}
default={['title', 'authorName', 'publishDate']}
/>
<NumberField
label="Maximum blog posts to list"
name="maxLinks"
min={1}
max={20}
step={1}
propertyAliasesPaths={{ maxLinks: ['max_links'] }}
default={5}
/>
<TextField
label="Posts heading"
name="postsHeading"
default="Featured posts"
propertyAliasesPaths={{ heading: ['list_title'] }}
/>
<ChoiceField
name="headingLevel"
label="Heading level"
display="select"
choices={[
['h1', 'H1'],
['h2', 'H2'],
['h3', 'H3'],
['h4', 'H4'],
['h5', 'H5'],
['h6', 'H6'],
]}
default="h2"
/>
<FieldGroup name="groupStyle" label="Styles" tab="STYLE">
<FieldGroup name="groupLayout" label="Layout">
<ChoiceField
name="style"
label="Style"
display="select"
choices={[
['tiles', 'Tiles'],
['minimal', 'Minimal'],
]}
default="minimal"
/>
</FieldGroup>
<FieldGroup label="Heading" name="groupHeading">
<FontField label="Font" name="font" />
</FieldGroup>
<FieldGroup label="Title" name="groupTitle">
<FontField
label="Font"
name="font"
default={{
font: '',
styles: { 'font-weight': 'bold' },
}}
/>
<SpacingField
label="Spacing"
name="spacing"
visibility={{ hidden_subfields: { padding: 'true' } }}
default={{
margin: {
bottom: {
value: 20,
units: 'px',
},
},
}}
/>
<FontField
label="Hover font"
name="hoverFont"
default={{
font: '',
styles: { 'font-weight': 'bold' },
}}
/>
</FieldGroup>
<FieldGroup label="Author" name="groupAuthor">
<FontField label="Font" name="font" />
</FieldGroup>
<FieldGroup label="Publish date" name="groupPublishDate">
<FontField label="Font" name="font" />
</FieldGroup>
</FieldGroup>
</ModuleFields>
);
xxxxxxxxxx
[
{
"id": "5c3b2c23-6585-a913-cabe-1d5ba025a1b9",
"name": "select_blog",
"label": "Select blog to display",
"help_text": "Default will use the current blog when used in a blog template or the primary blog when used elsewhere.",
"sortable": false,
"required": false,
"locked": false,
"type": "blog",
"default": null
},
{
"id": "f245b59c-d2ea-08ab-a40a-e545bc71d2cf",
"name": "listing_type",
"label": "List blog posts by",
"sortable": false,
"required": true,
"locked": false,
"display": "select",
"placeholder": "Search",
"choices": [
["recent", "Most recent"],
["popular_all_time", "Most popular - all time"],
["popular_past_year", "Most popular - past year"],
["popular_past_six_months", "Most popular - past six months"],
["popular_past_month", "Most popular - past month"]
],
"type": "choice",
"default": "recent"
},
{
"id": "643831b9-0aa6-a0ef-f3db-b5a71143168e",
"name": "list_title",
"label": "List title to display",
"sortable": false,
"required": false,
"locked": false,
"validation_regex": "",
"allow_new_line": false,
"show_emoji_picker": false,
"type": "text",
"default": "Recent Posts"
},
{
"id": "1417ad86-21ca-17b6-09a8-65ca54def75b",
"name": "max_links",
"label": "Maximum blog posts to list",
"sortable": false,
"required": false,
"locked": false,
"display": "text",
"min": 1,
"step": 1,
"type": "number",
"default": 5
}
]
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.
xxxxxxxxxx
[
{
"label": "Search input field",
"name": "input",
"type": "group",
"children": [
{
"label": "Label text",
"name": "field_label",
"type": "text",
"aliases": ["field_label"]
},
{
"label": "Placeholder text",
"name": "placeholder",
"type": "text",
"aliases": ["placeholder"],
"default": "Search"
}
]
},
{
"label": "Button",
"name": "button",
"type": "group",
"children": [
{
"label": "Icon",
"name": "icon",
"type": "icon",
"default": {
"name": "search",
"unicode": "f002",
"type": "SOLID"
}
},
{
"label": "Button text",
"name": "button_label",
"type": "text"
}
]
},
{
"label": "Results",
"name": "results",
"type": "group",
"children": [
{
"label": "Use custom search results page",
"name": "use_custom_search_results_template",
"id": "results.user_custom_search_results_template",
"type": "boolean",
"display": "toggle",
"inline_help_text": "Turn this setting on to use a custom search results page instead of the default global search results page.",
"default": false
},
{
"label": "Search results page",
"name": "path_id",
"type": "page",
"visibility": {
"operator": "EQUAL",
"controlling_field": "results.user_custom_search_results_template",
"controlling_value_regex": "true"
},
"inline_help_text": "This is where people will go when they click to search their search term. Make sure to choose a page that contains the search results module."
},
{
"label": "Search results include",
"name": "content_types",
"type": "group",
"children": [
{
"label": "Website pages",
"name": "website_pages",
"type": "boolean",
"visibility": {
"access": {
"operator": "HAS_ALL",
"scopes": ["sitepages-access"]
},
"operator": "NOT_EMPTY"
},
"display": "checkbox",
"aliases": ["content_types.website_pages"],
"default": true
},
{
"label": "Landing pages",
"name": "landing_pages",
"type": "boolean",
"display": "checkbox",
"aliases": ["content_types.landing_pages"],
"default": false
},
{
"label": "Blog posts",
"name": "blog_posts",
"type": "boolean",
"display": "checkbox",
"aliases": ["content_types.blog_posts"],
"default": true
},
{
"label": "Knowledge articles",
"name": "knowledge_articles",
"type": "boolean",
"visibility": {
"access": {
"operator": "HAS_ALL",
"scopes": ["service-knowledge-access"]
}
},
"display": "checkbox",
"aliases": ["content_types.knowledge_articles"],
"default": false
}
],
"default": {
"use_custom_search_results_template": false
}
}
]
},
{
"label": "Default text",
"name": "default_text",
"type": "group",
"children": [
{
"label": "Autosuggest results message",
"name": "autosuggest_results_message",
"type": "text",
"default": "Results for “[[search_term]]”"
},
{
"label": "Autosuggest no results message",
"name": "autosuggest_no_results_message",
"type": "text",
"default": "There are no autosuggest results for “[[search_term]]”"
},
{
"label": "Screen reader empty search field message",
"name": "sr_empty_search_field_message",
"type": "text",
"default": "There are no suggestions because the search field is empty."
},
{
"label": "Screen reader autosuggest results message",
"name": "sr_autosuggest_results_message",
"type": "text",
"default": "There are currently [[number_of_results]] auto-suggested results for [[search_term]]. Navigate to the results list by pressing the down arrow key, or press return to search for all results."
},
{
"label": "Screen reader search field aria-label",
"name": "sr_search_field_aria_label",
"type": "text",
"default": "This is a search field with an auto-suggest feature attached."
},
{
"label": "Screen reader search button aria-label",
"name": "sr_search_button_aria_label",
"type": "text",
"default": "Search"
},
{
"label": "Auto suggest results for example search term",
"name": "as_example_search_results",
"type": "text",
"default": "Results for “example search term”"
},
{
"label": "Auto suggest line 1 for example search term",
"name": "as_example_line_1",
"type": "text",
"default": "This is where suggested results appear as your visitor types their search term"
},
{
"label": "Auto suggest line 2 for example search term",
"name": "as_example_line_2",
"type": "text",
"default": "Here's another suggested search result"
},
{
"label": "Auto suggest line 3 for example search term",
"name": "as_example_line_3",
"type": "text",
"default": "Configure the type of content that appears in your search results using the “search results include” option"
}
],
"locked": true
},
{
"label": "Styles",
"name": "styles",
"type": "group",
"tab": "STYLE",
"children": [
{
"label": "Container",
"name": "container",
"type": "group",
"children": [
{
"label": "Background color",
"name": "color",
"type": "color"
},
{
"label": "Corner",
"name": "radius",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "spacing"
}
]
}
]
},
{
"label": "Label",
"name": "field_label",
"type": "group",
"children": [
{
"label": "Text",
"name": "text",
"type": "group",
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "spacing"
}
]
}
]
},
{
"label": "Field",
"name": "input",
"type": "group",
"children": [
{
"label": "Text",
"name": "text",
"type": "group",
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "spacing"
}
]
},
{
"label": "Background",
"name": "background",
"type": "group",
"children": [
{
"label": "Color",
"name": "color",
"type": "color"
}
]
},
{
"label": "Border",
"name": "border",
"type": "group",
"children": [
{
"label": "Border",
"name": "border",
"type": "border"
}
]
},
{
"label": "Corner",
"name": "corner",
"type": "group",
"children": [
{
"label": "Radius",
"name": "radius",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
}
]
}
]
},
{
"label": "Button",
"name": "button",
"type": "group",
"children": [
{
"label": "Text",
"name": "text",
"type": "group",
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
},
{
"label": "Transform",
"name": "transform",
"type": "choice",
"choices": [
["none", "None"],
["capitalize", "Capitalize"],
["uppercase", "Uppercase"],
["lowercase", "Lowercase"]
],
"display": "select"
}
]
},
{
"label": "Background",
"name": "background",
"type": "group",
"children": [
{
"label": "Color",
"name": "color",
"type": "color"
}
]
},
{
"label": "Border",
"name": "border",
"type": "group",
"children": [
{
"label": "Border",
"name": "border",
"type": "border"
}
]
},
{
"label": "Corner",
"name": "corner",
"type": "group",
"children": [
{
"label": "Radius",
"name": "radius",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "spacing"
}
]
},
{
"label": "Hover",
"name": "hover",
"type": "group",
"children": [
{
"label": "Text",
"name": "text",
"type": "group",
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"visibility": {
"hidden_subfields": {
"size": true
}
}
}
]
},
{
"label": "Background",
"name": "background",
"type": "group",
"children": [
{
"label": "Color",
"name": "color",
"type": "color"
}
]
},
{
"label": "Border",
"name": "border",
"type": "group",
"children": [
{
"label": "Border",
"name": "border",
"type": "border"
}
]
}
]
},
{
"label": "Position",
"name": "position",
"type": "group",
"children": [
{
"label": "Button position",
"name": "button_position",
"id": "button_position",
"type": "choice",
"choices": [
["inline", "In line with search field"],
["beneath", "Beneath search field"]
],
"display": "radio",
"default": "inline"
},
{
"label": "Button alignment",
"name": "button_alignment",
"type": "choice",
"visibility": {
"operator": "EQUAL",
"controlling_field": "button_position",
"controlling_value_regex": "beneath"
},
"choices": [
["left", "Left"],
["right", "Right"]
],
"display": "radio",
"default": "left"
}
]
}
]
},
{
"label": "Suggested results",
"name": "autosuggest_results",
"type": "group",
"children": [
{
"label": "Background",
"name": "background",
"type": "group",
"children": [
{
"label": "Color",
"name": "color",
"type": "color"
}
]
},
{
"label": "Border",
"name": "border",
"type": "group",
"children": [
{
"label": "Border",
"name": "border",
"type": "border"
}
]
},
{
"label": "Corner",
"name": "corner",
"type": "group",
"children": [
{
"label": "Radius",
"name": "radius",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "spacing"
}
]
},
{
"label": "Text",
"name": "text",
"type": "group",
"children": [
{
"label": "Header font",
"name": "header_font",
"type": "font",
"default": {
"size_unit": "px"
}
},
{
"label": "Suggestion font",
"name": "suggestion_font",
"type": "font",
"default": {
"size_unit": "px"
}
}
]
},
{
"label": "Hover",
"name": "hover",
"type": "group",
"children": [
{
"label": "Text",
"name": "text",
"type": "group",
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"visibility": {
"hidden_subfields": {
"size": true
}
}
}
]
},
{
"label": "Background",
"name": "background",
"type": "group",
"children": [
{
"label": "Color",
"name": "color",
"type": "color"
}
]
}
]
}
]
}
]
}
]
xxxxxxxxxx
[
{
"id": "d7644a33-944a-3b21-7faa-133195962602",
"name": "field_label",
"label": "Label text",
"required": false,
"locked": false,
"validation_regex": "",
"allow_new_line": false,
"show_emoji_picker": false,
"type": "text",
"default": null
},
{
"id": "e75bef76-6568-6550-8840-1d97bfc93c0b",
"name": "placeholder",
"label": "Placeholder text",
"required": false,
"locked": false,
"validation_regex": "",
"allow_new_line": false,
"show_emoji_picker": false,
"type": "text",
"default": "Search"
},
{
"id": "132b5655-eccf-c251-9ed4-d04901e91987",
"name": "include_search_button",
"label": "Include search button",
"required": false,
"locked": false,
"type": "boolean",
"default": false
},
{
"id": "346180f5-0d36-e8df-aca9-a74bfa2d79a4",
"name": "content_types",
"label": "Search results include",
"required": false,
"locked": false,
"children": [
{
"id": "71d525ff-37c4-6c64-1f96-d99dbb529816",
"name": "website_pages",
"label": "Website pages",
"required": false,
"locked": false,
"visibility": {
"controlling_field": null,
"controlling_value_regex": null,
"operator": "NOT_EMPTY",
"access": {
"operator": "HAS_ALL",
"scopes": ["sitepages-access"]
},
"hidden_subfields": null
},
"type": "boolean",
"default": true
},
{
"id": "d6212113-19b5-c9b9-2f92-12dfc122d00c",
"name": "landing_pages",
"label": "Landing pages",
"required": false,
"locked": false,
"type": "boolean",
"default": false
},
{
"id": "7535615c-ed26-2e34-87ef-21c5c87ccbcb",
"name": "blog_posts",
"label": "Blog posts",
"required": false,
"locked": false,
"type": "boolean",
"default": true
},
{
"id": "307d0eed-0cf9-7465-5715-a75c378ec61f",
"name": "knowledge_articles",
"label": "Knowledge articles",
"required": false,
"locked": false,
"visibility": {
"controlling_field": null,
"controlling_value_regex": null,
"operator": null,
"access": {
"operator": "HAS_ALL",
"scopes": ["service-knowledge-access"]
},
"hidden_subfields": null
},
"type": "boolean",
"default": false
}
],
"type": "group",
"default": {
"website_pages": true,
"landing_pages": false,
"blog_posts": true,
"knowledge_articles": false
}
}
]
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.
xxxxxxxxxx
[
{
"label": "Title",
"name": "title",
"type": "group",
"children": [
{
"label": "Show title",
"name": "show_title",
"type": "boolean",
"display": "toggle",
"default": false
},
{
"label": "Heading tag",
"name": "heading_tag",
"type": "choice",
"help_text": "Choose a heading level. H1 is the largest, followed by H2, and so on.",
"visibility": {
"controlling_field": "title.show_title",
"controlling_value_regex": "true",
"operator": "MATCHES_REGEX"
},
"choices": [
["h1", "H1"],
["h2", "H2"],
["h3", "H3"],
["h4", "H4"],
["h5", "H5"],
["h6", "H6"]
],
"display": "select",
"placeholder": "Select a heading type",
"default": "h1"
}
]
},
{
"label": "Results",
"name": "results",
"type": "group",
"children": [
{
"label": "",
"name": "display_for_each_result",
"id": "results.display_for_each_result",
"type": "choice",
"choices": [["image", "Display an image preview for each result"]],
"display": "checkbox",
"multiple": true,
"reordering_enabled": false
}
]
},
{
"label": "Pagination",
"name": "pagination",
"type": "group",
"children": [
{
"label": "Numbers",
"name": "numbers",
"id": "pagination.numbers",
"type": "choice",
"choices": [["show_numbers", "Show numbers"]],
"display": "checkbox",
"multiple": true,
"reordering_enabled": false,
"default": ["show_numbers"]
},
{
"label": "First and last",
"name": "first_and_last",
"id": "first_and_last",
"type": "choice",
"choices": [
["show_arrows", "Show arrows"],
["show_labels", "Show labels"]
],
"display": "checkbox",
"multiple": true,
"reordering_enabled": false,
"default": ["show_arrows", "show_labels"]
},
{
"label": "First label",
"name": "first_label",
"type": "text",
"visibility": {
"controlling_field": "first_and_last",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
},
"default": "First"
},
{
"label": "Last label",
"name": "last_label",
"type": "text",
"visibility": {
"controlling_field": "first_and_last",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
},
"default": "Last"
},
{
"label": "Previous and next",
"name": "previous_and_next",
"id": "previous_and_next",
"type": "choice",
"choices": [
["show_arrows", "Show arrows"],
["show_labels", "Show labels"]
],
"display": "checkbox",
"multiple": true,
"reordering_enabled": false,
"default": ["show_arrows", "show_labels"]
},
{
"label": "Previous label",
"name": "previous_label",
"type": "text",
"visibility": {
"controlling_field": "previous_and_next",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
},
"default": "Previous"
},
{
"label": "Next label",
"name": "next_label",
"type": "text",
"visibility": {
"controlling_field": "previous_and_next",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
},
"default": "Next"
}
],
"inline_help_text": "Pagination helps users browse long lists of results by organizing them into pages."
},
{
"label": "Default text",
"name": "default_text",
"type": "group",
"children": [
{
"label": "Results title",
"name": "results_title",
"type": "text",
"help_text": "Enter the title you would like to display above the search results.",
"placeholder": "Search results for “{{ searched_term|escape }}”",
"default": "Search results for “{{ searched_term|escape }}”"
},
{
"label": "Search results count",
"name": "results_count_message",
"type": "text",
"placeholder": "Displaying [[offset]] – [[limit]] of [[total]] results",
"default": "Displaying [[offset]] – [[limit]] of [[total]] results"
},
{
"label": "Featured Image",
"name": "featured_image",
"type": "text",
"default": "Featured Image"
},
{
"label": "Search Results Article Title",
"name": "search_results_article_title",
"type": "text",
"default": "Search Results Article Title"
},
{
"label": "Search result article description.",
"name": "search_results_article_description",
"type": "text",
"default": "Some preview text from each page will be displayed here to help your visitors browse through the search results quickly and find the page they need."
},
{
"label": "Navigation aria label",
"name": "navigation_aria_label",
"type": "text",
"default": "Paging navigation"
},
{
"label": "No results message",
"name": "no_results_message",
"type": "richtext",
"default": "<p>Sorry. There were no results for [[search_term]].</p><p>Try rewording your query, or browse through our site.</p>"
},
{
"label": "First page link text",
"name": "first_page_link_text",
"type": "text",
"default": "First Page"
},
{
"label": "Current page aria label",
"name": "current_page_aria_label",
"type": "text",
"default": "Current Page"
},
{
"label": "Page number aria label",
"name": "page_number_aria_label",
"type": "text",
"default": "Page"
},
{
"label": "Last page link text",
"name": "last_page_link_text",
"type": "text",
"default": "Last Page"
},
{
"label": "Previous page link text",
"name": "previous_page_link_text",
"type": "text",
"default": "Previous"
},
{
"label": "Next page link text",
"name": "next_page_link_text",
"type": "text",
"default": "Next"
}
],
"locked": true
},
{
"label": "Styles",
"name": "styles",
"type": "group",
"tab": "STYLE",
"children": [
{
"label": "Container",
"name": "container",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "spacing"
}
]
}
]
},
{
"label": "Title",
"name": "title",
"type": "group",
"visibility": {
"operator": "EQUAL",
"controlling_field": "title.show_title",
"controlling_value_regex": "true"
},
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
},
{
"label": "Transform",
"name": "transform",
"type": "choice",
"choices": [
["none", "None"],
["capitalize", "Capitalize"],
["uppercase", "Uppercase"],
["lowercase", "Lowercase"]
],
"display": "select"
}
]
},
{
"label": "Results count message",
"name": "results_count_message",
"type": "group",
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
},
{
"label": "Transform",
"name": "transform",
"type": "choice",
"choices": [
["none", "None"],
["capitalize", "Capitalize"],
["uppercase", "Uppercase"],
["lowercase", "Lowercase"]
],
"display": "select"
}
]
},
{
"label": "Results",
"name": "results",
"type": "group",
"children": [
{
"label": "Image",
"name": "featured_image",
"type": "group",
"visibility": {
"controlling_field": "results.display_for_each_result",
"controlling_value_regex": "image",
"operator": "MATCHES_REGEX"
},
"children": [
{
"label": "Size",
"name": "size",
"type": "group",
"children": [
{
"label": "Aspect ratio",
"name": "aspect_ratio",
"type": "choice",
"choices": [
["1/1", "1:1"],
["3/2", "3:2"],
["2/3", "2:3"],
["4/3", "4:3"],
["3/4", "3:4"],
["16/9", "16:9"]
],
"display": "select"
},
{
"label": "Width",
"name": "width",
"type": "number",
"display": "text",
"max": 75,
"min": 25,
"step": 5,
"suffix": "%"
}
]
},
{
"label": "Corner",
"name": "corner",
"type": "group",
"children": [
{
"label": "Radius",
"name": "radius",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "spacing",
"visibility": {
"hidden_subfields": {
"padding": true
}
}
},
{
"label": "Between image and content",
"name": "between_image_and_content",
"type": "number",
"display": "text",
"max": 50,
"min": 0,
"step": 1,
"suffix": "px"
}
]
}
]
},
{
"label": "Title",
"name": "title",
"type": "group",
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
}
]
},
{
"label": "Preview text",
"name": "description",
"type": "group",
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Space between results",
"name": "space_between_results",
"type": "number",
"display": "text",
"max": 48,
"min": 12,
"step": 2,
"suffix": "px"
}
]
}
]
},
{
"label": "Pagination",
"name": "pagination",
"type": "group",
"children": [
{
"label": "Numbers",
"name": "numbers",
"type": "group",
"visibility": {
"controlling_field": "pagination.numbers",
"controlling_value_regex": "show_numbers",
"operator": "MATCHES_REGEX"
},
"children": [
{
"label": "Text",
"name": "text",
"type": "group",
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
}
]
},
{
"label": "Background",
"name": "background",
"type": "group",
"children": [
{
"label": "Color",
"name": "color",
"type": "color"
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Spacing",
"name": "spacing",
"type": "spacing",
"visibility": {
"hidden_subfields": {
"margin": true
}
}
}
]
},
{
"label": "Border",
"name": "border",
"type": "group",
"children": [
{
"label": "Border",
"name": "border",
"type": "border"
}
]
},
{
"label": "Corner",
"name": "corner",
"type": "group",
"children": [
{
"label": "Radius",
"name": "radius",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
}
]
},
{
"label": "Hover",
"name": "hover",
"type": "group",
"children": [
{
"label": "Text color",
"name": "text_color",
"type": "color",
"visibility": {
"hidden_subfields": {
"opacity": true
}
}
},
{
"label": "Background color",
"name": "background_color",
"type": "color"
},
{
"label": "Border color",
"name": "border_color",
"type": "color",
"visibility": {
"hidden_subfields": {
"opacity": true
}
}
}
]
},
{
"label": "Active",
"name": "active",
"type": "group",
"help_text": "Styles the numbered link matching the page that you're currently on.",
"children": [
{
"label": "Text color",
"name": "text_color",
"type": "color",
"visibility": {
"hidden_subfields": {
"opacity": true
}
}
},
{
"label": "Background color",
"name": "background_color",
"type": "color"
},
{
"label": "Border color",
"name": "border_color",
"type": "color",
"visibility": {
"hidden_subfields": {
"opacity": true
}
}
}
]
}
]
},
{
"label": "Previous and next",
"name": "previous_and_next",
"type": "group",
"advanced_visibility": {
"boolean_operator": "OR",
"criteria": [
{
"controlling_field": "previous_and_next",
"controlling_value_regex": "show_arrows",
"operator": "MATCHES_REGEX"
},
{
"controlling_field": "previous_and_next",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
}
]
},
"children": [
{
"label": "Text",
"name": "text",
"type": "group",
"visibility": {
"controlling_field": "previous_and_next",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
},
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
}
]
},
{
"label": "Icon",
"name": "icon",
"type": "group",
"visibility": {
"controlling_field": "previous_and_next",
"controlling_value_regex": "show_arrows",
"operator": "MATCHES_REGEX"
},
"children": [
{
"label": "Size",
"name": "size",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
}
]
},
{
"label": "Background",
"name": "background",
"type": "group",
"children": [
{
"label": "Color",
"name": "color",
"type": "color"
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Space between text and icon",
"name": "space_between_text_and_icon",
"type": "number",
"advanced_visibility": {
"boolean_operator": "AND",
"criteria": [
{
"controlling_field": "previous_and_next",
"controlling_value_regex": "show_arrows",
"operator": "MATCHES_REGEX"
},
{
"controlling_field": "previous_and_next",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
}
]
},
"display": "slider",
"max": 25,
"step": 1,
"suffix": "px",
"visibility_rules": "ADVANCED"
},
{
"label": "Spacing",
"name": "spacing",
"type": "spacing",
"visibility": {
"hidden_subfields": {
"margin": true
}
}
}
]
},
{
"label": "Border",
"name": "border",
"type": "group",
"children": [
{
"label": "Border",
"name": "border",
"type": "border"
}
]
},
{
"label": "Corner",
"name": "corner",
"type": "group",
"children": [
{
"label": "Radius",
"name": "radius",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
}
]
},
{
"label": "Hover",
"name": "hover",
"type": "group",
"children": [
{
"label": "Text color",
"name": "text_color",
"type": "color",
"visibility": {
"hidden_subfields": {
"opacity": true
},
"controlling_field": "previous_and_next",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
}
},
{
"label": "Background color",
"name": "background_color",
"type": "color"
},
{
"label": "Border color",
"name": "border_color",
"type": "color",
"visibility": {
"hidden_subfields": {
"opacity": true
}
}
}
]
}
],
"visibility_rules": "ADVANCED"
},
{
"label": "First and last",
"name": "first_and_last",
"type": "group",
"advanced_visibility": {
"boolean_operator": "OR",
"criteria": [
{
"controlling_field": "first_and_last",
"controlling_value_regex": "show_arrows",
"operator": "MATCHES_REGEX"
},
{
"controlling_field": "first_and_last",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
}
]
},
"children": [
{
"label": "Text",
"name": "text",
"type": "group",
"visibility": {
"controlling_field": "first_and_last",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
},
"children": [
{
"label": "Font",
"name": "font",
"type": "font",
"default": {
"size_unit": "px"
}
}
]
},
{
"label": "Icon",
"name": "icon",
"type": "group",
"visibility": {
"controlling_field": "first_and_last",
"controlling_value_regex": "show_arrows",
"operator": "MATCHES_REGEX"
},
"children": [
{
"label": "Size",
"name": "size",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
}
]
},
{
"label": "Background",
"name": "background",
"type": "group",
"children": [
{
"label": "Color",
"name": "color",
"type": "color"
}
]
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Space between text and icon",
"name": "space_between_text_and_icon",
"type": "number",
"advanced_visibility": {
"boolean_operator": "AND",
"criteria": [
{
"controlling_field": "first_and_last",
"controlling_value_regex": "show_arrows",
"operator": "MATCHES_REGEX"
},
{
"controlling_field": "first_and_last",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
}
]
},
"display": "slider",
"max": 25,
"step": 1,
"suffix": "px",
"visibility_rules": "ADVANCED"
},
{
"label": "Spacing",
"name": "spacing",
"type": "spacing",
"visibility": {
"hidden_subfields": {
"margin": true
}
}
}
]
},
{
"label": "Border",
"name": "border",
"type": "group",
"children": [
{
"label": "Border",
"name": "border",
"type": "border"
}
]
},
{
"label": "Corner",
"name": "corner",
"type": "group",
"children": [
{
"label": "Radius",
"name": "radius",
"type": "number",
"display": "text",
"max": 100,
"step": 1,
"suffix": "px"
}
]
},
{
"label": "Hover",
"name": "hover",
"type": "group",
"children": [
{
"label": "Text color",
"name": "text_color",
"type": "color",
"visibility": {
"hidden_subfields": {
"opacity": true
},
"controlling_field": "first_and_last",
"controlling_value_regex": "show_labels",
"operator": "MATCHES_REGEX"
}
},
{
"label": "Background color",
"name": "background_color",
"type": "color"
},
{
"label": "Border color",
"name": "border_color",
"type": "color",
"visibility": {
"hidden_subfields": {
"opacity": true
}
}
}
]
}
],
"visibility_rules": "ADVANCED"
},
{
"label": "Spacing",
"name": "spacing",
"type": "group",
"children": [
{
"label": "Space between links",
"name": "space_between_links",
"type": "number",
"display": "slider",
"max": 50,
"min": 0,
"step": 5,
"suffix": "px"
},
{
"label": "Spacing",
"name": "spacing",
"type": "spacing",
"visibility": {
"hidden_subfields": {
"padding": true
}
}
}
]
}
]
}
]
}
]
xxxxxxxxxx
[
{
"id": "cbd47343-8232-3ff0-5757-c0c104454ca2",
"name": "display_featured_images",
"label": "Display featured images",
"sortable": false,
"required": false,
"locked": false,
"type": "boolean",
"default": false
}
]