HubL filters
Filters affect the ultimate output of your HubL. They can be applied to various HubL statements and expressions to alter the template markup outputted by the server.
The basic syntax of a filter is |filtername
. The filter is added directly following the statement or the expression, within its delimiters. Some filters have additional parameters that can be added in parentheses. The basic syntax of a filter with a string, a number, and a boolean parameters is: |filtername("stringParameter", 10, true)
. Notice that string parameters should be written in quotes. Also note that HubL filters have an alias that can be used to serve the same purpose as the primary filter.
The following article contains all of the supported HubL filters.
Please note: you can apply HubL filters to personalization tokens, such as contact and company tokens, on HubSpot CMS and blog pages, but not in emails.
Adds a numeric value to another numeric value. This filter functions the same as the + operator. The parameter in parentheses is the addend that you are combining with your initial numeric value.
Renders the attribute of a dictionary. This filter is the equivalent of printing a variable that exists within a dictionary, such as content.absolute_url.
Parameter | Description |
---|---|
attribute_name
Required
| Specifies which attribute to print |
A batch filter groups up items within a sequence.
Parameter | Description |
---|---|
linecount
Required
| The number of items to include in the batch |
fill_with
Optional
| Specifies what to include in order to fill up any missing items |
In the example below, there is variable containing a sequence of types of fruits. The batch filter is applied to a loop that iterates through the sequence. The nested loop runs three times to print 3 types of fruit per row, before the outer loop runs again. Notice in the final output that since there are only 5 types of fruit, the final item is replaced by a   (the second parameter).
Calculates the time between two datetime objects in a specified time unit.
Parameter | Description |
---|---|
end
Required
| The ending datetime object |
timeunit
Required
| Valid time units are nanos , micros , millis , seconds , minutes , hours , half_days , days , weeks , months , years , decades , centuries , millennia , and eras . |
Capitalize the first letter of a variable value. The first character will be uppercase, all others letters will be lowercased. Subsequent words separated by spaces or hyphens will not have their first letter uppercased.
The center filter uses whitespace to center text within a given field length. This filter is not recommended or particularly useful since HubSpot's HTML compiler will automatically strip out the white space; however, it is included here for the sake of comprehensiveness.
Parameter | Description |
---|---|
width
Required
| Specifies the length of whitespace to center the text in. |
The example below shows a center filter being applied to a variable in a pre tag, so the whitespace isn't stripped out.
Converts a HEX value to an RGB string. This is useful if you need to convert color variables to RGB to be used with a RGBA CSS declaration. In the example below, the value set by a color module is converted to an RGB value and used in an RGBA CSS declaration.
Removes a string from a value. This filter can be used to match and cut out a specific part of a string. The parameter specifies the part of the string that should be removed. The example below removes the space and the word world from the original variable value.
Parameter | Description |
---|---|
characters_to_cut
Required
| The part of the string that should be removed. |
Please note:
- This filter has been deprecated. Instead, use the format_datetime filter, which has a more standardized syntax.
- It is strongly recommended to use this filter only with variables that return a date. If a date is not passed, the filter will be used on the current date, which may result in inaccurate date information being displayed on your page.
Formats a datetime object. The datetimeformat filter is used to convert that timestamp into a legible date and/or time. The filter's parameters, listed in the table below, dictate how the time variable ultimately renders.
This filter expects a datetime timestamp. If your date and time information is in a different format, use the strtotime
filter to format the data first.
Parameter | Description |
---|---|
format
Required
| Directive format for the datetime object. See the directive table under the example for values. |
timezone
Optional
| Specifies a timezone. Must be in a supported Java 8 format. |
locale
Optional
| Specifies a locale. Must be in a supported Java 8 format. |
Directive | Example | Description |
---|---|---|
%a
| Sun, Mon, ..., Sat (en-US);So, Mo, ..., Sa (de-DE) | Weekday as locale’s abbreviated name. |
%A
| Sunday, Monday, ..., Saturday (en-US);Sonntag, Montag, ..., Samstag (de-DE) | Weekday as locale’s full name. |
%w
| 1, 2, ..., 7 | Weekday as a decimal number, where 1 is Sunday and 7 is Saturday. |
%d
| 01, 02, ..., 31 | Day of the month as a zero-padded decimal number. |
%e
| 1, 2, ..., 31 | Day of the month as a decimal number, without padding. |
%b
| Jan, Feb, ..., Dec (en-US);Jan, Feb, ..., Dez (de-DE) | Month as locale’s abbreviated name. |
%B
| January, February, ..., December (en-US);Januar, Februar, ..., Dezember (de-DE) | Month as locale’s full name. |
%OB
| 1月, 2月, ..., 12月 (ja) | Get the nominative version of the months name. |
%m
| 01, 02, ..., 12 | Month as a zero-padded decimal number. |
%y
| 00, 01, ..., 99 | Year without century as a zero-padded decimal number. |
%Y
| 1970, 1988, 2001, 2013 | Year with century as a decimal number. |
%H
| 00, 01, ..., 23 | Hour (24-hour clock) as a zero-padded decimal number. |
%I
| 01, 02, ..., 12 | Hour (12-hour clock) as a zero-padded decimal number. |
%k
| 0, 1, ..., 24 | The hour (24-hour clock) as a decimal number (range 0 to 23); single digits are preceded by a blank. |
%l
| 1, 2, ..., 12 | (note this is a lower case L) The hour (12-hour clock) as a decimal number (range 1 to 12); single digits are preceded by a blank. |
%p
| AM, PM (en-US);am, pm (de-DE) | Locale’s equivalent of either AM or PM. |
%M
| 00, 01, ..., 59 | Minute as a zero-padded decimal number. |
%S
| 00, 01, ..., 59 | Second as a zero-padded decimal number. |
%f
| 000000, 000001, ..., 999999 | Microsecond as a decimal number, zero-padded on the left. |
%z
| (empty), +0000, -0400, +1030 | UTC offset in the form +HHMM or -HHMM (empty string if the the object is naive). |
%Z
| (empty), UTC, EST, CST | Time zone name (empty string if the object is naive). |
%j
| 001, 002, ..., 366 | Day of the year as a zero-padded decimal number. |
%U
| 00, 01, ..., 53 | Week number of the year (Sunday as the first day of the week) as a zero padded decimal number. All days in a new year preceding the first Sunday are considered to be in week 0. |
%W
| 00, 01, ..., 53 | Week number of the year (Monday as the first day of the week) as a decimal number. All days in a new year preceding the first Monday are considered to be in week 0. |
%c
| Tue Aug 16 21:30:00 1988 (en-US);Di 16 Aug 21:30:00 1988 (de-DE) | Locale’s appropriate date and time representation. |
%x
| 08/16/88 (None);08/16/1988 (en-US);16.08.1988 (de-DE) | Locale’s appropriate date representation. |
%X
| 21:30:00 (en-US);21:30:00 (de-DE) | Locale’s appropriate time representation. |
%%
| % | A literal |
If the value is undefined it will return the first parameter, otherwise the value of the variable will be printed. If you want to use default with variables that evaluate to false, you have to set the second parameter to true. The first example below would print the message if the variable is not defined. The second example applied the filter to an empty string, which is not undefined, but it prints a message due to the second parameter.
Parameter | Description |
---|---|
default_variable
Required
| Value to return if the variable is undefined. If the variable is defined, the value of the variable will be returned instead. |
boolean
Optional
| Returns the default_value if the variable is an empty string |
Sort a dict and yield (key, value) pairs. Dictionaries are unsorted by default, but you can print a dictionary, sorted by key or value. The first parameter is a boolean to determine, whether or not the sorting is case sensitive. The second parameter determines whether to sort the dict by key or value. The example below prints a sorted contact dictionary, with all the known details about the contact.
Parameter | Description |
---|---|
case_sensitive
Required
| Determines if sorting is case sensitive |
sort_by
Required
| Determines whether to sort by key or value |
This filter returns the difference of two sets or lists. The list returned from the filter contains all unique elements that are in the first list but not the second.
Parameter | Description |
---|---|
list
Required
| The second list to compare to for use in finding differences from the original list. |
An alternative to the divisibleby expression test, the filter divisible will evaluate to true if the value is divisible by the given number.
Parameter | Description |
---|---|
divisor
Required
| The number to use when evaluating if the value is divisible. |
Convert the characters &, <, >, ‘, and ” in string to HTML-safe sequences. Use this if you need to display text that might contain such characters in HTML. Marks return value as markup string.
Converts the characters {
and }
in strings to Jinjava-safe sequences. Use this filter if you need to display text that might contain such characters in Jinjava. Marks return value as markup string.
Format the value like a ‘human-readable’ file size (i.e. 13 kB, 4.1 MB, 102 Bytes, etc). Per default decimal prefixes are used (Mega, Giga, etc.), if the parameter is set to True the binary prefixes are used (Mebi, Gibi).
Parameter | Description |
---|---|
boolean
Optional
| If set to true, binary prefixes are used such as Mebi & Gibi. |
Convert the value into a floating point number. If the conversion doesn’t work it will return 0.0. You can override this default using the first parameter.
Parameter | Description |
---|---|
default
Optional
| Integer to return if the conversion doesn't work. |
Strictly enforce HTML escaping. In HubSpot's environment there isn't really a use case for double escaping, so this is generally behaves the same as the escape filter.
Formats a given number as a currency based on portal's default currency and locale passed in as a parameter.
Parameter | Description |
---|---|
locale
Optional
| The Java local Language tag. The default is the page's locale.Format : ISO639LanguageCodeInLowercase-ISO3166CountryCodeInUppercase |
currency_code
Optional
| the ISO 4217 code of the currency, default is the portals default currency. |
use_default_decimal_digits
Optional
| a boolean that determines if the formatter needs to use default decimal digits of the currency code. Default value is false. |
Parameter | Description |
---|---|
format
Optional
| The format to use. Can be one of:
|
timeZone
Optional
| The time zone of the output date in IANA TZDB format. |
locale
Optional
| The locale to use for locale-aware formats. |
Parameter | Description |
---|---|
format
Optional
| The format to use. Can be one of:
When using |
timeZone
Optional
| The time zone of the output date in IANA TZDB format. By default, returns UTC time. |
locale
Optional
| The locale to use for locale-aware formats. |
Parameter | Description |
---|---|
format
Optional
| The format to use. Can be one of:
|
timeZone
Optional
| The time zone of the output date in IANA TZDB format. |
locale
Optional
| The locale to use for locale-aware formats. |
The groupby filter groups a sequence of objects by a common attribute. The parameter sets the common attribute to group by.
Parameter | Description |
---|---|
attribute
Required
| The attribute to group by. |
The indent filter uses whitespace to indent text within a given field length. This filter is not recommended or particularly useful since HubSpot's HTML compiler will automatically strip out the white space; however, it is included here for the sake of comprehensiveness. The example below shows a center filter being applied to a variable in a pre tag, so the whitespace isn't stripped out. The first parameter controls the amount of whitespace and the second boolean toggles whether to indent the first line.
Parameter | Description |
---|---|
width
Required
| The amount of whitespace to be applied. |
boolean
Required
| A boolean value on whether to indent the first line. |
Convert the value into an integer. If the conversion doesn’t work it will return 0. You can override this default using the first parameter.
Parameter | Description |
---|---|
default
Required
| Integer to return if the conversion doesn't work. |
This filter returns the intersection of two sets or lists. The list returned from the filter contains all unique elements that are contained in both lists.
Parameter | Description |
---|---|
list
Required
| The second list to compare to for use in finding where the list intersects with the original list. |
Return a string which is the concatenation of the strings in the sequence. The separator between elements is an empty string per default, you can define it with the optional parameter. The second parameter can be used to specify an attribute to join.
Parameter | Type | Description |
---|---|---|
delimiter
Optional
| String | The delimiter to use when concatenating strings. |
attribute
Optional
| HubL Variable | Attribute of value to join in an object. |
Convert the number values into a list. If it was a string the returned list will be a list of characters. To add strings to a sequence, simply add them to the string variables to the sequence delimiters [ ].
Applies a filter on a sequence of objects or looks up an attribute. This is useful when dealing with lists of objects but you are really only interested in a certain value of it.
The basic usage is mapping on an attribute. For example, if you want to use conditional logic to check if a value is present in a particular attribute of a dict. Alternatively, you can let it invoke a filter by passing the name of the filter and the arguments afterwards.
Parameter | Description |
---|---|
attribute
| Attribute to return in the sequence of objects. |
filter
| Filter to apply to the sequence of objects. |
Calculates the md5 hash of the given object
Subtracts an amount of time to a datetime object.
Parameter | Description |
---|---|
diff
Required
| Amount to subtract. |
timeunit
Required
| Valid time units are nanos , micros , millis , seconds , minutes , hours , half_days , days , weeks , months , years , decades , centuries , millennia , and eras . |
Multiplies a value with a number. Functions the same as the * operator.
Adds an amount of time to a datetime object.
Parameter | Description |
---|---|
diff
Required
| Amount to add. |
timeunit
Required
| Valid time units are nanos , micros , millis , seconds , minutes , hours , half_days , days , weeks , months , years , decades , centuries , millennia , and eras . |
Return a random item from the sequence.
Please note: when using this filter, the page will be prerendered periodically rather than every time the page content is updated. This means that the filtered content will not be updated on every page reload.
This may not be an issue for certain types of content, such as displaying a random list of blog posts. However, if you need content to change randomly on every page load, you should instead use JavaScript to randomize the content client-side.
Searches for a regex pattern and replaces with a sequence of characters. The first argument is a RE2-style regex pattern, the second is the replacement string.
Information on the RE2 regex syntax can be found here.
Filters a sequence of objects by applying an expression test to the object and rejecting the ones with the test succeeding.
Parameter | Description |
---|---|
exp_text
| The expression test to apply to the object. |
Filters a sequence of objects by applying a test to an attribute of an object and rejecting the ones with the test succeeding.
Parameter | Description |
---|---|
attribute_name
Required
| Specifies the attribute to select. You can access nested attributes using dot notation. |
exp_test
Optional
| The expression to test |
val
Optional
| Value to test against. |
Replace all instances of a substring with a new one.
Parameter | Description |
---|---|
old
Required
| The substring that should be replaced. |
new
Required
| Replacement string. |
count
Optional
| If provided, only the firstcount occurrences are replaced. |
Reverse the object or return an iterator the iterates over it the other way round. To reverse a list use .reverse()
Round the number to a given precision.
Parameter | Description |
---|---|
precision
Optional
| Specifies the precision of the rounding. |
rounding_method
Optional
| Options include common round either up or down (default); ceil always rounds up; floor always rounds down. If you don’t specify a method common is used. |
Filters a sequence of objects by applying a test to an attribute of an object and only selecting the ones with the test succeeding.
Parameter | Description |
---|---|
attribute_name
Required
| Specifies the attribute to select. You can access nested attributes using dot notation. |
exp_test
Optional
| The expression to test |
val
Optional
| Value to test against. |
Randomizes the order of iteration through a sequence. The example below shuffles a standard blog loop.
Please note: when using this filter, the page will be prerendered periodically rather than every time the page content is updated. This means that the filtered content will not be updated on every page reload.
This may not be an issue for certain types of content, such as displaying a random list of blog posts. However, if you need content to change randomly on every page load, you should instead use JavaScript to randomize the content client-side.
Slice an iterator and return a list of lists containing those items. The first parameter specifies how many items will be sliced, and the second parameter specifies characters to fill in empty slices.
Parameter | Description |
---|---|
slices
Required
| How many items will be sliced. |
filler
Required
| Specifies characters to fill in empty slices. |
Sorts an iterable. This filter requires all parameters to sort by an attribute in HubSpot. The first parameter is a boolean to reverse the sort order. The second parameter determines whether or not the sorting is case sensitive. And the final parameter specifies an attribute to sort by. In the example below, posts from a blog are rendered and alphabetized by name.
Parameter | Description |
---|---|
reverse
Required
| Boolean value to reverse the sort order. |
case_sensitive
Required
| Boolean value that determines if the sorting is case sensitive. |
attribute
Required
| Attribute to sort by. Omit when sorting a list. |
Splits the input string into a list on the given separator. The first parameter specifies the separator to split the variable by. The second parameter determines how many times the variable should be split. Any remaining items would remained group. In the example below, a string of names is split at the ";" for the first 4 names.
Parameter | Description |
---|---|
character_to_split_by
Required
| Specifies the separator to split the variable by. |
number_of_splits
Optional
| Determines how many times the variable should be split. Any remaining items would remain grouped. |
Converts a datetime string and a datetime format into a datetime object.
Parameter | Description |
---|---|
datetimeFormat
Required
|
Adds numeric values in a sequence. The first parameter can specify an optional attribute and the second parameter sets a value to return if there is nothing in the variable to sum.
Parameter | Description |
---|---|
attribute
Optional
| Attribute to sum. |
return_if_nothing
Optional
| Value to return if there is nothing in the variable to sum. |
This filter returns the symmetric difference of two sets or lists. The list returned from the filter contains all unique elements that are in the first list but not the second, or are in the second list but not the first
Parameter | Description |
---|---|
list
Required
| The second list to compare to for use in finding the symmetric difference with the original list. |
Return a titlecased version of the value. I.e. words will start with uppercase letters, all remaining characters are lowercase.
Writes an object as a JSON string.
Cuts off text after a certain number of characters. The default is 255. Please note that HTML characters are included in this count. The length is specified with the first parameter which defaults to 255. If the second parameter is true the filter will cut the text at length. Otherwise it will discard the last word. If the text was in fact truncated it will append an ellipsis sign ("..."). If you want a different ellipsis sign than "..." you can specify it using the third parameter.
Parameter | Description |
---|---|
number_of_characters
Required
| Number of characters to truncate the text by. Default is 255. |
breakword
Optional
| Boolean value. If true, the filter will cut the text at length. If false, it will discard the last word. |
end
Optional
| Override the default '...' trailing characters after the truncation. |
Truncates a given string, respecting html markup (i.e. will properly close all nested tags). This will prevent a tag from remaining open after truncation. HTML characters do not count towards the character total. This filter has a length parameter and a truncation symbol parameter. There is a third boolean parameter that specifies whether words will be broken at length. This parameter is false by default in order to preserve the length of words. If using only one of the optional parameters, use keyword arguments, such as truncatehtml(70, breakwords = false).
Parameter | Description |
---|---|
number_of_characters
Required
| Number of characters to truncate the text by. Default is 255. |
end
Optional
| Override the default '...' trailing characters after the truncation. |
breakword
Optional
| Boolean value. If true, the filter will cut the text at length. If false, it will discard the last word. |
This filter extracts a unique set from a sequence or dict of objects. When filtering a dict, such as a list of posts returned by a function, you can specify which attribute is used to deduplicate items in the dict.
Parameter | Description |
---|---|
attr
Optional
| Specifies the attribute that should be used when filtering a dict value |
This filter converts a datetime object into a unix timestamp.
Escapes and URL encodes a string using UTF-8 formatting. Accepts both dictionaries and regular strings as well as pairwise iterables.
Decodes encoded URL strings back to the original URL. Accepts both dictionaries and regular strings as well as pairwise iterables.
Converts URLs in plain text into clickable links. If you pass the filter an additional integer it will shorten the urls to that number. The second parameter is a boolean that dictates whether the link is rel="no follow". The final parameter lets you specify whether the link will open in a new tab.
Parameter | Description |
---|---|
shorten_text
Optional
| Integer that will shorten the urls to desired number. |
no_follow
Optional
| Boolean value to indicate whether the link is rel="no follow". |
target="_blank"
Optional
| Specifies whether the link will open in a new tab. |
Causes words to wrap at a given character count. This works best in a <pre> because HubSpot strips whitespace by default.
Parameter | Description |
---|---|
character_count
Required
| Number of characters to wrap the content at. |
Create an HTML/XML attribute string, based on the items in a dict. All values that are neither none
nor undefined are automatically escaped. It automatically prepends a space in front of the item if the filter returned something unless the first parameter is false.
Parameter | Description |
---|---|
autospace
Required
| Boolean value that will automatically prepend a space in front of the item unless set to false. |
Thank you for your feedback, it means a lot to us.