HubL Reference

Table of contents


export_to_template_context is a parameter that makes a module's parameters available to the template environment without actually rendering the module. This parameter can be used all HubL module tags. The widget_data tag is used to retrieve these parameters, store them in variables, and/or incorporate them into your template's logic.

By making modules parameter's available in the template context, without actually rendering the module, you can allow users to make decisions in the content editor that effect how the template renders. For example, let's say that you want to only render a certain code block, when the user gives a value to a field. This becomes is possible with this parameter.

First you must add export_to_template_context=True to the module tag. Then you must use a widget_data.module.parameter_you_want_to_retreive.

{% text "module_name" label="Enter some text here", value="Default text to print", export_to_template_context=True %} 
{# Makes the parameters available to be stored and used in template logic #}

{{ widget_data.module_name.parameter }} 
{# Prints the value of the module but can also be used in template logic #}

Below are a few applications of this concept.

Usage within custom modules

If you are defining HubL modules within a custom module and trying to access one of that module's parameters, you need to account for the fact that each HubL module's name automatically gets appended with the name of the custom module in the context of the template. This ensures that the module stays unique within the context of the template layout.

For example, on template layouts, each custom module will have a unique name like module_12287093845098 (you find the name by using Developer Info). If you defined a color module named "my_color" within the custom module, the module's actual name would be "module_12287093845098_my_color"; therefore, when retreiving the color parameter from this module, you would need to use the syntax widget_data.module_12287093845098_my_color.color. At this time, it is impossible to do this dynamically within a custom module, so you may instead choose to use no_wrapper=True, when printing HubL module values within custom modules.

User selectable background images

In this example, an image module is created, but then exported to the context of the template rather than rendered. The src parameter is retreived with the widget_data tag, and render as the source of a background image in a style tag. This technique is applied on the homepage of
HubSpot Help article screenshot

{% image "background_image" label='Select a background image', 
export_to_template_context=True %}
<!--Sample markup -->
<div class="bg-image-section" style="background:url('{{ widget_data.background_image.src }}'); background-size:cover; min-height: 500px;">
    <h1>Supercharge your app with HubSpot</h1>
    <h3>Build powerful integrations for a global community of users</h3>

Choice field to render pre-defined markup

The following example uses the export_to_template_context parameter in conjunction with a choice module to change a banner message on a careers page. The user selects a departmet via the UI and the heading changes without the user having to actually edit content.

{% choice "department" label='Choose department', value='Marketing', choices='Marketing, Sales, Dev, Services' export_to_template_context=True %}
{% if widget_data.department.value == 'Marketing' %}

<h3>Want to join our amazing Marketing team?!</h3>
<h4>We have exciting career opportunities on the {{ widget_data.department.value }} team.</h4>

{% elif widget_data.department.value == 'Sales' %}

<h3>Are you a Sales superstar?</h3>
<h4>We have exciting career opportunities on the {{ widget_data.department.value }} team.</h4>        
{% elif widget_data.department.value == 'Dev' %}
<h3>Do you love to ship code?</h3>
<h4>We have exciting career opportunities on the {{ widget_data.department.value }} team.</h4>
{% else %}
<h3>Want to work with our awesome customers?</h3>
<h4>We have exciting career opportunities on the {{ widget_data.department.value }} team.</h4>
{% endif %}      

Retrieving params from modules that already render on template

If you want to retrieve a parameter from a module that is already rendering on a page, the module can be accessed within a dict named widgets. The export_to_template_context parameter is not required. The syntax is as follows:

{{ content.widgets.name_of_module.body.parameter }}

{{ content.widgets.my_text.body.value }}

Printing HubL module info on blog listing

While blog templates are generally used for blogs, they can also be repurposed to create various other types of listings. You can use the techniques described above to achieve this.

For example, you may want to create a listing layout of press that you company has received, but rather than linking to posts, you want the listing to link to another page.

You can see this concept in action at The projects listing page is a blog listing template, but each post links to a regular HubSpot page. The content creator specifies the destination link in the editor.

Within the individual blog post's code, you would define a text field. If you don't want  the text to render on the post, you would use export_to_template_context.

{% text "custom_blog_link" label="Link to external press item", export_to_template_context=True %}

This text field is editable in each blog post. Next, we would need to define a link in our listing. But because the widget_data only exists in the context of the post, we need to use different syntax to fetch the widget data to populate the link. In this case, we would use content.widgets.custom_blog_link.body.value. While the widget_data is not available to the blog listing, the value of that field is still stored within the context of the individual content's widgets.

A basic blog listing loop that renders this custom link with each post is shown below. If using this technique, you would want to ensure that you add the subdirectory automically created for each blog post to your robots.txt file to prevent those empty posts from being crawled by Google and other crawlers.

{% for content in contents %}
<a href="{{ content.widgets.custom_blog_link.body.value }}">
    Click here to see this press feature!
{% endfor %}