HubL Pro Tips - Advanced Templating Functions For Hubspot CMS

In this post, we walk through a handful of helpful HubL techniques that can be used when building templates on the Hubspot CMS.

What is HubL?

HubL is the templating language of the Hubspot CMS. HubL, an acronym for "HubSpot Markup Language" and pronounced "hubble", is HubSpot’s extension of Jinjava, a templating engine based on Jinja.

If you’re building on the Hubspot CMS, you’ll use HubL to do things like run conditional logic or loop through an array (called “sequences” in HubL).

There are actually quite a few things that can be done in HubL – although it’s not a full-fledged server language (like PHP), there are ways to accomplish just about anything you need to do.

Here are some of the HubL techniques we find ourselves using often:

View The HubL Developer Info

Something to know when developing templates for Hubspot is that you can view all available variables (there are more than mentioned in the HubL variable documentation) by viewing the developer info of a blog or landing page.

The “Export to Template Context” Attribute

The export_to_template_context attribute can be added to HubL supported tags, and their values will be stored on a dictionary variable called widget_data, and globally available in your template. This is a common way to use boolean field values in template logic.

{% boolean 'show_form' label='Show Signup Form?', value='true', no_wrapper='true', export_to_template_context='true' %}
{% if widget_data.show_form.value %}
	{# Your conditional code here... #}
{% endif %}

Numbered Iterations With The HubL Range Function

When building templates on any platform, a common need is to perform a given number of loop iterations. Your instinct may be to search for the HubL equivalent of a while loop, but for loops are the only iterator available.

You might consider creating a sequence variable to loop over, but this is tedious and won’t work for user-entered number values.

{% set tedious_array = [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15] %}
{% for count in tedious_array %}
	{{count}}
{% endfor %}

We could really use some help from the range function. It returns a sequence containing a progression of integers, so it’s perfect for this particular use case. We can even do a user-defined amount of iterations.

{% set user_count = widget_data.user_count.value %}
{% for count in range(user_count) %}
  {{count}}
{% endfor %}

Re-Usable HubL Template Partials with Macros.

Macros in HubL are essentially functions, and they can be passed arguments that can be used in the function logic. They are perfect for minimizing duplicated markup in your templates.

{% macro do_post_list(title, desc, blog_id='default', classes='') %}
  {% set posts = blog_recent_posts(blog_id) %}
  {{title}}
  {{desc}}
  {% for p in posts %}
  	{{p.name}}
  {% endfor %}
{% endmacro %}

Additionally, macros can be defined in a partial and imported in a template. This makes it easy to use your defined macros across multiple templates. A macro like the one defined above can be imported and used like so:

{% import 'path/to/your/macros.html' as my_macros %}
{{my_macros.do_post_list('Recent Posts', 'The latest news and happenings')}}

If String (or Array) Contains Substring

In the HubL documentation, be sure to fully browse the operators & expressions tests page – there are many useful expression tests that you may not find in code examples and tutorials.

{% set needle = 'ipsum' %}
{% set haystack = 'Lorem ipsum dolor sit amet, consectetur adipisicing elit.' %}
{% if haystack is string_containing %}
  {{haystack}}
{% endif %}

Another common need is to check an array of strings to see if a single item matches a given string. This can be done by utilizing the HubL join filter to turn the array into a single string – then performing the same expression test as in the previous example.

{% set needle = 'ipsum' %}
{% set haystack = ['lorem', 'ipsum', 'dolor', 'sit', 'amet'] %}
{% set seq_to_string = haystack | join('|') %}
{% if seq_to_string is string_containing %}
  {{haystack}}
{% endif %}

Prevent HubL Loops & Conditionals From Creating Whitespace

You may notice large amounts of whitespace in the source of your templates depending on how you’ve used hubL. To prevent this, you are able to add a hyphen to the opening statement delimiter. Here’s an example:

{%- if post.use_featured_image %}
  {{post.featured_image}}
{%- endif %}

Get HTTP Request Details

If you need to work with http request info (like url GET or POST parameters) in your template logic, hubL has you covered. There is a global variable named request that is accessible from any template.

{% set params = request.query_dict %}
{% set cookies = request.cookies %}

Get Lat/Long from Postal or Country Code

When you’re working with the Hubspot CMS, it can be helpful to fully review the available functions and filters from time to time. The platform goes through constant changes and improvements, so its common to find these features updated or added to. Recently, a function that takes a postal and/or country code and returns a latitude and longitude was added:

{% set location = postal_location("02139", "US") %}
{{ location.latitude }} {{ location.longitude }}

This new function could be useful if building something like a location finder or after geolocating a user with javascript, because latitude and longitude coordinates are needed when working with javascript map libraries.

Does your HubSpot portal need a tune-up? We’re proud to announce that we now offer a full service HubSpot Portal Audit.

Wrapping Up with HubL Templating and Functions

Even though HubL (Hubspot’s template syntax) is not a full-blown server language, it makes just about anything possible with template logic. You can create and work with arrays (sequences), functions (macros), or objects (dictionaries), and there are a ton of useful filters and functions available. Stay tuned, we’ll be posting more helpful info about developing on Hubspot’s CMS in the very near future!