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 folder 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. So it is best to have different icons for the types of modules in your theme. 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.

// 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, "inline_help_text": "This module is for code snippets." }

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 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.

Module editor - label field

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.

// 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

You can add the parameters in the table below to a module's meta.json file.

ParameterTypeDescription 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.

e.g. "css_assets": [{ "path": "../path/to/file.css" }]

 []
css_render_options
Object

Set whether the module CSS renders asynchronously with async: true, false 

 {"async": false}
js_assets
Array

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

e.g. "js_assets": [{ "path": "../path/to/file.js" }]

 []
js_render_options
Object

Modifies the module JavaScript tag added to the rendered page. Options include:

  • position: head , footer
  • async: true, false 
  • defer: true, false 
  • type: string

 

 {"position":"footer"}
inline_help_text
String

Help text that will be shown at the top of the module in a blue info box (limit 300 chars).

Best used to provide information necessary to use the module. If you have field-specific help text information to convey, please refer to our documentation on help text for fields.

 null
master_language
String

The language code of the language the module's fields were originally written in.

e.g. en
placeholder
Object

Sets placeholder content for the module. Includes the following properties:

  • show_module_icon: whether the module icon displays. true, false.
  • title: the title that appears on the module in the editor. String.
  • description: the description that appears on the module in the editor. String.
 False
Was this article helpful?
This form is used for documentation feedback only. Learn how to get help with HubSpot.