HubL Reference

Table of contents

HubL module syntax & parameters

Modules are editable areas of HubSpot pages or emails. While you can add modules to a template layout using the drag and drop Template Builder, you can also create modules using HubL. HubL modules can be defined in a coded template file, a HubL template module, or a blog content module. Below is a comprehensive list of modules and their parameters.

Basic module syntax

Module tags are made up of the following components:

  • Type of module - specifies which module to render. Please refer to the HubL Supported Tags page for a listing of the different types of modules available.
  • 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. The path for HubSpot default modules should always start with @hubspot/ followed by the type of module. See the example below and the HubL Supported Tags page for more. 
  • Parameters (optional) - specify additional module information

{% 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 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 documentation, the unique module name will always be in double quotes and the parameter values will be 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' %}

<span id="hs_cos_wrapper_simple_section_title" class="highlight hs_cos_wrapper hs_cos_wrapper_widget hs_cos_wrapper_type_text"

style="" data-hs-cos-general-type="widget" data-hs-cos-type="text">

This is a section title


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.

{% widget_block type_of_module "unique_module_name" parameterString='String parameter value', parmeterBoolean=True %}
    {% widget_attribute "parameter_of_default_content" %}
        Block of default content
    {% end_widget_attribute %}
{% end_widget_block %}

The type_of_module should be replaced with the type of module such as 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 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 %}
{% widget_block raw_html "my_custom_html_module" overrideable=True, label='My custom HTML module'  %}
        {% widget_attribute "value" %}
            <div>My HTML block</div>
        {% end_widget_attribute %}
{% end_widget_block %}


<span id="hs_cos_wrapper_my_rich_text_module" class="hs_cos_wrapper hs_cos_wrapper_widget hs_cos_wrapper_type_rich_text" style="" data-hs-cos-general-type="widget" data-hs-cos-type="rich_text">
    <h2>New Module</h2>
    <p>Add content here.</p>

<span id="hs_cos_wrapper_my_custom_html_module" class="hs_cos_wrapper hs_cos_wrapper_widget hs_cos_wrapper_type_raw_html" style="" data-hs-cos-general-type="widget" data-hs-cos-type="raw_html">
    <div>My HTML block</div>


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 being populated with a default content code block.

{% 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>
            <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>
        <p><a href="">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>Your name</p>
{% end_content_attribute %}  

Using content_attribute with block syntax

For larger modules, you can use both the content_attribute and block syntax formats for more readable default content. You can use content_attribute inside a widget_block. Then, set content_attribute to "is_json=True" to set your parameters in a json format.

{% widget_block social_sharing "module_12345" %}
    {% content_attribute "email" is_json=True %}
       "default": true,
       "enabled": false,
       "img_src": "https://..."
   {% end_content_attribute %}
{% end_widget_block %}

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.

Parameters name Type Description Default value
 label  string  Defines the internal title of the module in the content editor. This parameter can also be used to give users additional instructions.  None 
 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 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').   None
 export_to_template_context  boolean If True, instead of rendering the HTML, the parameters from this widget will be available in the template context. To retrieve a parameter with HubL, you will widget_data tag. To learn more about how to use this parameter and the widget_data tag, check out this article.  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. You can see an application of this parameter, here.  False

To see a complete list of all module types and their parameters, click here.