Configuring a module
When creating a module, there are a number of options available that impact where a module is visible, how it's identified, and how it can be edited.
When developing locally, modules are stored as folders with a .module
suffix. These folders contain the files that make up the module's settings and the code used to render it. A module's configuration is kept in the meta.json file, while fields are configured separately in a fields.json file.
Most configuration can also be modified using the module editor in the Design Manager.
At a high level, you configure module options locally within the meta.json
file, which can include the following properties:
Parameter | Type | Description | Default |
---|---|---|---|
icon
| String | URL to an image to use as the icon for a module. | |
label
| String | Label used when modules are shown in the content editors | |
module_id
| Number | Unique id for the module that is independent from the path. | |
is_available_for_new_content
| Boolean | The value for the toggle in the top right corner of the module editor in HubSpot. Determines if the module can be used in content. |
true
|
global
| Boolean | Indicates whether the module is global or not |
false
|
content_types
| Array | An
If a module is not to be used in any area within HubSpot, you would set the value to an empty array Note that this field was previously named | |
css_assets
| Array | An e.g. |
[]
|
css_render_options
| Object | Set whether the module CSS renders asynchronously with |
{"async": false}
|
js_assets
| Array | An e.g. |
[]
|
js_render_options
| Object | Modifies the module JavaScript tag added to the rendered page. Options include:
|
{"position":"footer"}
|
inline_help_text
| String | Help text that will be shown at the top of the module in a blue info box (limit 400 characters). Provides information necessary to use the module. If you have field-specific help text information to convey, refer to the help text field documentation. |
null
|
master_language
| String | With translations enabled, the language code of the language the module's fields were originally written in. e.g. | |
placeholder
| Object | Sets placeholder content for the module. Includes the following properties:
| |
categories
| Array | An array containing up to three module categories. For example: "categories":["FORMS_AND_BUTTONS"] | |
content_tags
| Array | An array of module tag objects containing the tag name and For example: "content_tags": [{ "name" : "BUTTONS", "source" : "USER" }] |
Below, learn more about individual module configuration options.
Modules can include an icon that appears in the Design Manager and the page and email editors to provide visual context for content creators. It's recommended to have different icons for the different types of modules in your theme. Icons are required for marketplace providers.
There are two ways to add an icon, through the design manager or the CMS CLI.
Module icons must be an .svg
file and no larger in size than 10kb. For best results your icon should be simple and use only one color. Icons that use more than one color will be automatically converted for you. The default module icon that displays is a wrench and paint brush icon.
To add an icon using the design manager:
-
In your HubSpot account, navigate to Marketing > Files and Templates > Design Tools.
- Use the left sidebar to locate the module you want to edit, then click the module name.
- In the right sidebar of the module editor, click the icon next to the module title.
- Upload/select your icon. After publishing your changes, the icon will appear within the page editors and design manager.
To add an icon when developing locally, open the module's meta.json
file and add or edit the icon
parameter's value to be an SVG from the file manager.
The label used when modules are displayed in the editor can be adjusted separately from the name for the module. This is useful when developing locally as you can have a name that makes sense to you while having a different one content creators see.
Locally you change the label
parameter to set the label. In the design manager there's a field in the module editor below the module name.
For normal modules, the content of each instance of a module in a page, email or template is independent. For some use cases, it is useful to be able to have all instances of a module share the same content. When developing locally, you can make a module global by setting global
to true
.
You can also convert modules in a drag-and-drop template to global using the design manager.
When developing locally, you can control which types of content a module can be used in through the hostTemplateTypes
property. Learn more about the available template types. Modules also can be hidden so that they can't be added directly to pages through setting is_available_for_new_content
to false
. For example, this can be helpful for modules built for navigation menus and search.
You can update this in the design manager by clicking the Template type option in the right sidebar.
In addition to using module.css
and module.js
to add CSS and JavaScript that will be added to all pages that include a module instance, dependencies that are shared between modules can be attached using css_assets
and js_assets
. Paths can be absolute or relative to the meta.json
file.
Warning: When using relative paths to reference dependencies, running hs fetch --overwrite
to update the module for local development will overwrite the relative paths with absolute paths.
Using the design manager, you can link CSS and JavaScript files to a module using the Linked files section in the right sidebar of the module editor.
You can assign categories and tags to modules to organize them within HubSpot tools:
- Categories: assign categories to a modules to organize them into groups within the content editor UI. This enables content creators to find modules more easily while building content in HubSpot. Note the following about categories:
- A module can have up to three categories, which are pre-defined and cannot be customized.
- Currently, categories are not surfaced in the content editor UI. However, you can assign categories for when categorization is available in editors.
- Uncategorized modules will be available under an All category.
- Tags: assign tags to organize modules within the design manager. This enables you to find modules more easily while building templates.
In the design manager, you can assign categories and tags using the Filter tags section of the right sidebar in the module editor. Learn more about the available categories and tags below.
Locally, you can add categories and tags to a module's meta.json
file as follows:
A module's categories
array can contain up to three of the following categories (case-insensitive):
Category | Description |
---|---|
blog |
Blog-specific modules, such as a recent post listing. |
body_content |
Modules that are formatted to graphically showcase content, such as an image gallery. |
commerce |
Commerce-specific modules, such as pricing cards. |
design |
Modules that affect content structure and layout, such as accordions. |
functionality |
Modules that include dynamic responses or behavior on the page, such as menus. |
forms_and_buttons |
Modules that allow site visitors to input and submit data. |
media |
Modules that contain elements such as images, icons, video, and banners. |
social |
Social media-specific modules, such as social sharing. |
text |
Modules that contain only text. |
A module's content_tags
array can contain any of the following module tag objects (case sensitive):
Content types:
ACCORDION
ANIMATION
BLOG_POST
BUTTONS
CODE
CTA
FEED
FORM
ICON
IMAGE
LISTS
LOGO
MENU
RICH_TEXT
SLIDER
TEXT
VIDEO
Functions:
BANNER
BLOG
BRANDING
CALCULATOR
CONVERSION
EMAIL
GALLERY
HEADERS
INTERACTION
LAYOUT
MAP
MULTIMEDIA
NAVIGATION
PROGRESS_BAR
SEARCH
SETTINGS
SOCIAL
TRANSLATION
Thank you for your feedback, it means a lot to us.