In this post, we walk through a handful of helpful HubL techniques that can be used when building templates on the Hubspot CMS.
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.
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 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 %}
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 %}
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')}}
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 %}
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 %}
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 %}
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.
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!