Using Modules in Templates
Modules can either be added directly to a template or added to individual pages with drag and drop areas and flexible columns. When a module is added to a template, the module will appear in that location by default. Modules in drag and drop areas and flexible columns can be moved and removed, and other modules can be added around them. These are module instances.
After a module has been defined, you can get its field values at the template level through the content.widgets dict.
Module tags are made up of the following components:
- A unique name for that module: gives the module a unique identity in the context of the template
- Path: depending on the tag, defines the location of where the module is in the design manager.
/
means the root of the current drive;./
means the current directory;../
means the parent of the current directory.
- Parameters: additional settings for the instance of the module. Includes template-level default values for module fields.
@hubspot/
followed by the type of module. See the example below and the default modules page for more information.
HubL module tags are delimited by {%
, and require the type of module and a unique name to be specified. The unique name must be in quotes following the type of module. Module names must use underscores instead of spaces or dashes.
The unique name is used to match content inputted with the page/email editor with the corresponding HubL module tag. For example, if you code a HubL module tag with the same name in two different areas of a template, users will only have one module to edit in the editor, but changes to that module will apply in both locations.
In addition to the two required components of a module tag, HubL modules support various parameters that specify a module's behavior as well as how it renders. Parameters are key-value pairs separated by commas. Parameters have different types including string, boolean, integer, enumeration, and JSON list. String parameters should have their value in quotes*, while Boolean parameters do not require quotes around their True or False values. Below is an example of a basic text module with a label and a value parameter specified.
*String parameter values can be written in either single or double-quotes. In this example, the unique module name has double quotes and the parameter values are in single quotes. This syntax is helpful when parameter values include HTML markup with multiple attributes. Boolean parameter values are capitalized for legibility.
For modules with fields that expect dicts, you can pass them like you would other parameters. If it's cleaner to you or you plan to re-use the values, you can set the dict to a variable, and pass the variable to the parameter instead.
When we introduced dnd_area
and all of the HubL tags you use with it. It became possible to have a module field with the same name as an existing dnd parameter. The design manager will prevent you from creating new fields that use one of these reserved parameter names but that doesn't help old modules. To fix this we've added a fields
parameter. Just like you would pass field data for a group you can pass the field name as a key on the fields object. It's value needs to be consistent with the format the field type expects.
You can set template level default values for repeating fields by passing an array to the field's parameter. The array's items must be in the format expected based on the field type. Example a simple text field only expects a string, an image repeater field expects an image field's object. This applies to all of the other field types.
Modules that contain repeating groups of fields - like you might see in a slideshow module or FAQ module - can have a template level default set for those groups. To do this you pass an array of objects to your field group's parameter. The key and value pairs of the object are the field names and their values.
While most modules have parameters that control default content, there may be situations where you need to add large code blocks to the default content of a module. For example, you may want to include a large block of HTML as the default content for a rich text or HTML module. Rather than trying to write that code into a value parameter, you can use HubL block syntax.
Prior to the module_block
syntax, widget_block
was used. It follows the same pattern but the opening tags were widget_block
, and widget_attribute
. Closing tags were end_widget_attribute
, end_widget_block
.
The widget_block
syntax is deprecated but you don't need to update old code.
The parameter that immediately follows module_block
or widget_block
(deprecated) is the type_of_module
parameter.
In nearly all of our documentation you will find we use module
. V2 HubSpot Modules are normal modules, like what you can create. Therefore there's no longer a need to use a different type_of_module
.
While widget_block
is deprecated, and you should use module_block
. If inheriting a website from another developer it may contain old code using widget_block
and type_of_module
.
The type_of_module
supports V1 HubSpot module names for example: rich_text
or raw_html
. Additional parameters can be added to the first line of HubL. The second line defines which parameter the contents of the block will be applied to. For example, for a rich_text
module this should be the html parameter. For a raw_html
module, this would be the value parameter (see both examples below).
In addition to regular and block syntax, there are certain instances where you may want to specify a large block default content for a predefined content variable. The most common example of this proves to be the content.email_body variable. This variable prints a standard email body that can be altered in the content editor. Since this isn't a standard HubL module, we use a content_attribute tag to specify a block of default content. The example below shows the email body variable populated with a default content code block.
Certain modules have certain special parameters, but there are also parameters supported by all modules. Below is a list of parameters supported by all modules.
Parameter | Type | Description | Default |
---|---|---|---|
label
| String | Defines the internal title of the module in the content editor. This parameter can also be used to give users additional instructions. | |
overrideable
| Boolean | Controls whether or not the module can be edited in the content editor. This parameter is the equivalent of using the lock module feature in the Template Builder UI. |
True
|
no_wrapper
| Boolean | Setting no_wrapper=True removes the wrapping markup from around the content of a module. Module output to the page is always wrapped in a <div> with special classes. This wrapping markup makes it so when you click the module in the preview pane, the editor scrolls to that module. There may be instances where you want to remove the wrapper, such as if you want to use a text module to populate the destination of an anchor tag href attribute. |
False
|
extra_classes
| String | Adding an extra classes parameter will add those classes to the wrapping of the module content. You can add multiple classes at once, by separating the classes with spaces (ie extra_classes='full-width panel'). | |
export_to_template_context
| Boolean | If True, instead of rendering the HTML, the parameters from this widget will be available in the template context. How to use this parameter and the widget_data tag. |
False
|
unique_in_loop
| Boolean | This parameter can be used when a module is defined within a loop to append the unique module name with the loop.index. If True, this makes it possible to print a different version of that module with each iteration of the loop. |
False
|
To see a complete list of all module types and their parameters, click here.
You can set the value of custom module fields using parameters.
faq_group_title
in this case is not one of the parameters that is available for all modules. faq_group_title
is specific to this custom module. It is the variable name for a field in the module.
Some fields are simple and the parameter simply expects a string, integer, true/false. Others may expect an object. Providing the values in the correct format is down to you as there is no in-editor value validation based on settings you set in the custom module's field settings. Example: A module has a number field that has a minimum value set to 1, you pass into the parameter a 0. There is no warning to indicate your value is invalid.
When building templates with modules that contain style fields, you can explicitly set default values for style fields using the styles parameter.
This works just like normal groups do, the parameter is the name of the group. You pass an object to that parameter with all of the fields you wish to set.
Field | Type | Example | Keys |
---|---|---|---|
Blog | blog id | 1234567890 | |
Boolean | true/false | false | |
Choice | value string | "option_1" | |
Color | object |
|
|
CTA | String, CTA id |
|
|
Date | timestamp |
|
|
Datetime | timestamp |
|
|
Email address | array of email address strings |
|
|
File | URL string to file |
|
|
Follow Up Email | Follow up email id |
|
|
Font | Object with font keys and values |
|
|
Form | Object with form keys and values |
|
|
HubDB Table | hubDB table id | 123456789 |
|
Icon | object with icon keys and values |
|
|
Image | object with image keys and values |
|
|
Link | object with link keys and values |
|
|
Logo | object with logo keys and values |
|
|
Meeting | String of meeting link url |
"https://app.hubspot.com/meetings/developers-r-kewl"
|
|
Menu | Menu ID |
123456789
|
|
Number | integer |
1
|
|
Page | Page ID |
1234567890
|
|
richtext | string, can contain html |
"<h1>Hello, world!</h1>"
|
|
Salesforce Campaign | string, salesforce campaign id |
"7016A0000005S0tQAE"
|
|
Simple Menu | array of menu item objects |
|
|
Tag | Tag ID/slug (ID is recommended) |
1234567890
|
|
Text | string |
"it's like any other string"
|
|
URL | object with URL keys and values |
|
|
Thank you for your feedback, it means a lot to us.