Using Modules in Templates

Last updated:

Modules are editable areas of HubSpot pages or emails. Module instances can be added to templates using HubL. When defined in a template a module will appear in that location in the template by default. If the module is in an editable region such as a drag and drop area or flexible column, it can be removed, moved, and other modules can be added. These are module instances.

The module definitions - the module tags you can add to templates define the default state for module instances.

After a module has been defined if needed you can get it's field values at the template level through content.widgets.

Basic module syntax

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 (depends on 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.
The path for HubSpot default modules should always start with @hubspot/ followed by the type of module. See the example below and the default modules page for more information. 
HubL 
{% module "unique_module_name" path="@hubspot/module_type",
  parameterString='String parameter value',
  parameterBoolean=True
%}

{# Sample of a default HubSpot text module #}
{% module "job_title" path="@hubspot/text",
  label="Job Title",
  value="Chief Morale Officer"
%}

{# Sample of a custom module #}
{% module "faqs" path="/Marketplace/HubSpotSiteSetup/Vast_Site_Setup/Custom_Modules/Vast FAQ Module",
  label="Vast FAQ Module"
%}

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.

{% module "simple_section_title" path="@hubspot/text",
  label='Enter text for this section title',
  value='This is a section title'
%}

Passing dicts to module parameters

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.

HubL 
{% module "social_buttons",
  path="@hubspot/social_sharing", 
  email={
    "default": true,
    "enabled": false,
    "img_src": "https://..."
  }
%}

Passing fields that have dnd associated parameters

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.

HubL 
{% dnd_area "main_content"%}
     {% dnd_section %}
        {% dnd_column %}
          {% dnd_row %}
            {% dnd_module path="@hubspot/divider",
               fields={width: "90"}
            %}
            {% end_dnd_module %}
        {% end_dnd_row %}
      {%end_dnd_column%}
    {% end_dnd_section %}
  {% end_dnd_area %}

Setting template level default values for repeating fields

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, a color field would expect a color object.

HubL 
{% module path='../modules/recipe_card.module',
  ingredients=["Eggs","Ham","Cheese"]
%}

Setting template level default values for repeating groups of fields.

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.

HubL 
{% module path='../modules/slideshow.module',
  slides=[
    {
      "caption":"Cute dog looking up",
      "image_url":"http://example.com/image.jpg",
    },
    {
      "caption":"Cuter cat not looking amused",
      "image_url":"http://example.com/image2.jpg",
    }
  ]
%}

Block Syntax

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.

HubL 
{% module_block module "my_rich_text_module" path="/My Rich Text Field Module",
  label="My Rich Text Field Module" 
%}
    {% module_attribute "rich_text_field_variable" %}
       <div>My HTML block</div>
    {% end_module_attribute %}
{% end_module_block %}

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

{# widget_block is deprecated, use module_block instead. This example is only to
explain what type_of_module was used for, for those with legacy code. #}
{% widget_block rich_text "my_rich_text_module" overrideable=True, label='My rich-text module'  %}
        {% widget_attribute "html" %}
            <h2>New Module</h2>
            <p>Add content here.</p>
        {% end_widget_attribute %}
{% end_widget_block %}

content_attribute

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.

HubL 
{% content_attribute "email_body" %}
        <p>Hi {{ contact.firstname }},</p>
        <p>Describe what you have to offer the customer. Why should they read? What did you promise them in the subject line? Tell them something cool. Make them laugh. Make them cry. Well, maybe don't do that...</p>
        <p>Use a list to:</p>
        <ul>
            <li>Explain the value of your offer</li>
            <li>Remind the reader what they’ll get out of taking action</li>
            <li>Show off your skill with bullet points</li>
            <li>Make your content easy to scan</li>
        </ul>
        <p><a href="http://hubspot.com">LINK TO A LANDING PAGE ON YOUR SITE</a> (This is the really important part.)</p>
        <p>Now wrap it all up with a pithy little reminder of how much you love them.</p>
        <p>Aw. You silver-tongued devil, you.</p>
        <p>Sincerely,</p>
        <p>Your name</p>
{% end_content_attribute %}

Parameters available for all modules

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.

How module field types translate to parameters
ParameterTypeDescription 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.

Field based parameters

You can set the value of custom module fields using parameters.

HubL 
{% module "faq" path="faq", 
  label="Accessible FAQ Module",
  faq_group_title="Commonly Asked Questions"
%}

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.

How module field type's translate to parameters
Field Type Example Keys
Blog blog id 1234567890  
Boolean true/false false  
Choice value string "option_1"  
Color object 
{
  "color" : "#ffffff",
  "opacity" : 100
}
color
6 character hexidecimal format
opacity
integer 0 - 100
CTA String, CTA id 
"fb9c0055-6beb-489d-8dda-3e1222458750"
  
Date timestamp 
1566360000000
  
Datetime timestamp 
1566360000000
  
Email address array of email address strings 
["develop@hubspot.com", "design@hubspot.com"]
  
File URL string to file 
"https://cdn2.hubspot.net/hubfs/file.pdf"
  
Follow Up Email Follow up email id 
1234567890
  
Font Object with font keys and values 
{
  "size" : 12,
  "size_unit" : "px",
  "color" : "#000",
  "styles" :{
    "text-decoration" : "underline"
  },
  "font" : "Alegreya",
  "fallback" : "serif",
  "variant" : "regular",
  "font_set" : "GOOGLE"
}
size
font size without unit type
size_unit
font size unit string
  • "px"
  • "pt"
  • "em"
  • "rem"
  • "%"
  • "ex"
  • "ch"
color
hex color code string
styles
supported properties
"font-weight"
"normal" / "bold"
"font-style"
"normal" / "italic"
"font-style"
"none" / "underline"
Form Object with form keys and values 
{
  "form_id" : "9aa2e5f3-a46d-4774-897e-0bc37478521c",
  "response_type" : "redirect",
  "redirect_url" : "http://www.hubspot.com",
  "redirect_id" : null,
  "form_type" : "HUBSPOT"
}
form_id
The form's ID. How to get a form's id.
response_type
"redirect" / "inline"
message
Message displayed if using response_type "inline". String supporting html.
redirect_url
String, absolute URL to a webpage
redirect_id
Page/Post id to redirect to
form_type
"HUBSPOT" / "TICKET_FORM"
HubDB Table hubDB table id 123456789  
Icon object with icon keys and values 
{ 
  "name" : "align-center",
  "unicode" : "f037",
  "type" : "SOLID"
}
name
The icon's name
unicode
The unicode symbol for the font the icon is from
type
Symbol style. "SOLID" / "REGULAR"
It is recommended you set an icon field and view the values that way, to set the parameters properly.
Image object with image keys and values 
{
  "src" : "https://cdn2.hubspot.net/hubfs/image.jpeg",
  "alt" : "an_image",
  "width" : 100,
  "height" : 100
}
src
Image URL
alt
Image alt text, used by screen readers and search engines
width
The width at which the image is to be displayed
height
The height at which the image is to be displayed
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 
[ 
  { 
    "isPublished" : true,
    "pageLinkId" : 123456789,
    "pageLinkName" : "My page",
    "isDeleted" : false,
    "categoryId" : 1,
    "subCategory" : "site_page",
    "contentType" : "site_page",
    "state" : "PUBLISHED_OR_SCHEDULED",
    "linkLabel" : "This is a page",
    "linkUrl" : null,
    "linkParams" : null,
    "linkTarget" : null,
    "type" : "PAGE_LINK",
    "children" : [ ]
  } 
]
isPublished
true/false is the menu item's page published?
pageLinkId
Page id in the CMS
pageLinkName
The page's actual name in the CMS
isDeleted
true/false
categoryId
  • 1 - Site Page
  • 3 - Blog post
subCategory
  • site_page
  • landing_page
  • blog
  • normal_blog_post
contentType
  • site_page
  • landing_page
  • blog
state
  • DRAFT
  • DRAFT_AB
  • PUBLISHED
  • PUBLISHED_OR_SCHEDULED
  • PUBLISHED_AB
  • SCHEDULED
linkLabel
text the user reads and clicks
linkUrl
actual URL the user is sent to upon clicking
linkParams
# links or ? query parameters
linkTarget
if open in new tab is enabled "_blank" otherwise "null"
type
  • "PAGE_LINK"
  • "PAGE_LINK_WITH_PARAMS"
  • "NO_LINK"
children
array of menu item objects, identical to individual menu items.
Tag Tag ID/slug (ID is recommended) 1234567890  
Text string "it's like any other string"  
URL object with URL keys and values 
{ 
  "type" : "CONTENT",
  "href" : null,
  "content_id" : 123456789
}
type
  • "EXTERNAL" for non HubSpot non-email URLs
  • "CONTENT" for pages, blog posts, and landing pages
  • "FILE" for files uploaded to the file manager
  • "EMAIL_ADDRESS" for email addresses
  • "BLOG" for blog listing pages
href
String, the URL you are linking to.