HubL variables & macros syntax
HubL uses variables to store and output values to the template. Variables can be used in template logic or iterated through with for loops. In addition to variables, macros are another useful tool for printing repetitive yet dynamic sections of code throughout your templates.
Variables are expressions delimited by
}}. The basic syntax of variables is as follows:
Variables are either a single word in an expression or an attribute of a dictionary. HubL uses Python-based data structures called dictionaries or dicts to store various sets of variables. For example, HubSpot uses a dictionary "content" to house many attributes that pertain to the content created with that template. For example the
content.absolute_url prints the URL of the specific piece of content.
HubSpot has many predefined variables that can be used throughout your page, blog, and email templates. We have a reference list of variables, you can also view the developer info when browsing any page from your account to see the variables available within that page..
In addition to printing the values of variables and dictionary attributes in a template, you can also define your own variables. You can store strings, booleans, integers, sequences, or create dictionaries within a single variable. Variables are defined within statement delimiters using the word "set". Once stored, variables can then be printed by stating the variable name as an expression. Below you can see various types of information stored in variables and then printed.
Variables should either be single words or use underscores for spaces (ie my_variable). HubL does not support hyphenated variable names.
Each example above stores a different type of variable, with the final example storing two different variables in a sequence.
One common usage is to use variables to define common CSS values in your stylesheet. For example, if you have a color that you use over and over again throughout your CSS file. That way, if you need to change that color, you can change the variable value, and all references to that variable will be updated, the next time that you publish the file.
HubL macros allow you to print multiple statements with a dynamic value. For example, if there is a block of code that you find yourself writing over and over again, a macro may be a good solution, because it will print the code block while swapping out certain arguments that you pass it.
The macro is defined, named, and given arguments within a HubL statement. The macro is then called in a statement that passes its dynamic values, which prints the final code block with the dynamic arguments. The basic syntax of a macro is as follows:
If your macro is returning whitespace in the form of new lines, you can strip whitespace in templates by hand. If you add a minus sign (
-) to the start or end of a block, a comment, or a variable expression, the whitespaces before or after that block will be removed.
Below shows a practical application of a macro to print a CSS3 properties with the various vendor prefixes, with a dynamic value. This allows you to print 5 lines of code with a single macro tag.
Macros introduce the ability to have recursive code. To prevent reliability and performance issues you can only nest macros 20 levels deep. If you go over this limit you will get the error:
max recursion limit of 20 reached for macro <your macro name>
In some instances, you may want to pass additional dynamic information back into the macro block. For example, you may have a large piece of code that you want to feed back into the macro, in addition to the arguments. You can do this using call block and caller(). A call block works essentially like a macro but does not get its own name. The expression caller() specifies where the contents of the call block will render.
In the example below, a
<p> is added into a macro in addition to the two arguments.
Another useful feature of macros is that they can be used across templates by importing one template file into another. To do this you will need to use the import tag. The import tag will let you specify a Design Manager file path to the template that contains your macros and give the macros a name in the template that you are including them in. You can then pass values into these macros without needing to redefine them.
For example, let's say that you have a .html template file that contains the following 2 macros. One macro is defined to set up a header tag and one is defined to generate a footer tag. This file is saved in Design Manager with the name
In the template that will use these macros, an import tag is used that specifies the file path to the
my_macros.html file. It also names the group of macros (in this example
header_footer). Macros can then be executed by appending the macro name to the name given to the imported template. See the example below.
If you want to only import specific macros, instead of all macros contained in a separate .html file, you can use the from tag. With the from tag, specify only the macros that you want to import. Generally, using import will provide more flexibility, but this alternative is also supported.
The example below accesses the same
my_macros.html file from the previous section of this article. But this time instead of importing all macros, it accesses only the footer macro.
Any variables defined within loops are limited to the scope of that loop and cannot be called from outside of the loop.
You can call variables that are defined outside of a loop, from within a loop, but not the other way around.
You can also use functions in order to mutate objects for settings values on dict's or performing list operations. The following example is using the
.update list operation:
Thank you for your feedback, it means a lot to us.