Configuring a Module

Last updated:

When creating a module, there are a number of options available that impact where a module is visible, how it is identified, and how it is edited. Modules appear locally as folders with a .module suffix. Inside that folder contain the files that make up the module's settings, and code used to render it. The configuration is kept in the meta.json file. Fields are configured separately in a fields.json file. Most configuration can also be modified using the module editor in the Design Manager

Module structure displayed locally

Adding an Icon

Modules can have an icon that is used in the Design Manager and the page and email editors. For marketplace providers these icons are required. The intent of the icon is that it can provide visual context for the content creator on the purpose of the module.  There are two ways to add an icon, through the design manager or the CMS CLI.

Add an icon using the design manager

  1. open the module in the design manager,
  2. when in the module editor, the icon showing adjacent to the title and type of module is a button. Selecting that button provides an icon upload field.
  3. Upload/select your icon and now you will be able to see it within your page editor and design manager.
Change Icon

Add an icon using the CLI

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.

JSON
// meta.json
{
  "global": false,
  "host_template_types": ["PAGE"],
  "icon": "http://example.com/hubfs/code.svg",
  "label": "Code block",
  "smart_type": "NOT_SMART",
  "is_available_for_new_content": true
}

Creating a module icon

Module icons must be an .svg file and no larger in size than 10kb. For best results your icon should be fairly simple and use only one color. If you're icon uses more than one color, it will be automatically converted for you. The default module icon that displays is a wrench and paint brush icon.

Changing the label

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.

Making a module "global"

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. Setting global to true does this. 

It is also possible to convert modules in a drag-and-drop template to global via the UI.

Controlling where a module is available for use

Modules can be limited to certain content types through how the hostTemplateTypesis configured. Modules also can be hidden so that they can't be added directly to pages through setting is_available_for_new_content to false. Modules built for navigation menus and search are good candidates for hiding via is_available_for_new_content.

Both of these can also be managed through the module editor.

Adding CSS and JavaScript dependencies

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.

JSON
// meta.json
{ 
  "css_assets": [{ "path": "../path/to/file.css" }],
  "js_assets": [{ "path": "../path/to/file.js" }]
}

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.

meta.json

Parameter Type Description Default
icon
String

URL to an image to use as the icon for a module.

null
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
host_template_types
Array

An array of content types that the module can be used within. One or more of [ "PAGE", "BLOG_POST", "BLOG_LISTING", "EMAIL" ].

["PAGE", "BLOG_POST", "BLOG_LISTING"]
css_assets
Array

An array of CSS files that the module depends on. Supports relative paths.

[]
js_assets
Array

An array of JavaScript files that the module depends on. Supports relative paths.

[]