HubL functions

Functions in HubL are similar to filters in that they accept parameters and generate a value. However, not all functions need to be applied to an initial template value, and instead they interact with other areas of your HubSpot environment.

If you maintain an older website, you may also want to check out the list of deprecated HubL functions.

Below, learn more about each HubL function and its syntax.

Adds a single item to the end of a list.

The blog_all_posts_url function returns a full URL to the listing page for all blog posts for the specified blog. 

The example below shows how this function can be used as an anchor's href.

The blog_author_url function returns a full URL to the specified blog author's listing page.

The example below shows how this function can be used as an anchor's href. This can be combined with blog_authors as shown in that function's examples.

The blog_authors function returns a sequence of blog author objects for the specified blog, sorted by slug ascending. This sequence can be stored in a variable and iterated through to create custom author post filters.

The number of live posts by each author can be accessed with author.live_posts.

The first line of the example below demonstrates how the function returns a sequence of author objects. The rest of the example demonstrates a use case of saving a sequence into a variable and then iterating though the author objects, printing a set of author listing links. The example assumes that the blog has 4 authors.

The blog_by_id function returns a blog by ID. The below example code shows this function in use to generate a hyperlinked list item.

The blog_page_link function generates the URL of a paginated view of your blog listing. The function takes a numeric parameter, which allows you to generate links for current, next, previous, or a specific page. This function is generally used in the href attribute of pagination anchor tags and must be used on your blog listing template.

The examples below show this function in use as an anchor href. The first example outputs the current page. The second example takes the number 7 parameter to specify the seventh page. The third example uses the next_page_num variable to generate a link that is relative to the current page number (you can also use the last_page_num variable for the previous page). The final example uses the current_page_num variable and a + operator to create a link that is 4 greater than the current page.

The blog_popular_posts function renders a set number of popular posts into a sequence. This sequence of posts can be saved into a variable and iterated through with a for loop, creating a custom post listing of your most popular posts. 

Results from this function are cached for six hours. To retrieve blog posts using HubL in a way that avoids caching, you may want to use blog_recent_tag_posts instead.

In the example code below, the first line shows how the function returns a sequence. The sequence is saved as a variable, which the code below that uses to loop through the sequence. Any blog post variables should use the name of the individual loop item rather than content.. In the example, pop_post.name is used. This technique can be used on blog templates and website pages.

The blog_post_archive_url function returns a full URL to the archive listing page for the given date values on the specified blog. This function has two required parameters and two optional parameters. The first parameter is a blog ID or simply the keyword "default". The second is the year of archived posts you'd like to display.

The optional parameters include the month and day of archived posts you'd like to display, respectively.

The example below shows how this function can be used as an anchor's href.

The blog_recent_author_posts function returns a sequence of blog post objects for the specified author, sorted by most recent. This sequence of posts can be saved into a variable and iterated through with a for loop, creating a custom post listing of posts by a particular author. 

The function takes three parameters. The first parameter specifies which blog to collect posts by an author from. The value should be "default" or the blog ID of a particular blog (available in the URL of the Blog dashboard). The second parameter specifies which author to use. This parameter can use the content.blog_post_author.slug to use the author of the current post or accepts a lowercase hyphenated name such as "brian-halligan". The third parameter specifies how many posts are retrieved. 

The first line of the example below demonstrates how the function returns a sequence of posts by an author. In this example, rather than specifying an exact author name, the current post author is used. The sequence is saved in a variable and looped through. Any blog post variables should use the name of the individual loop item rather than content.. In the example, author_post.name is used. This technique can be used on blog and page templates.

The blog_recent_posts function returns a sequence of blog post objects for the specified blog, sorted by most recent first. This sequence of posts can be saved into a variable and iterated through with a for loop, creating a custom post listing of your most popular posts. 

The function takes two parameters. The first parameter specifies which blog to collect popular posts from. The value should be "default" or the blog ID of a particular blog (available in the URL of the Blog dashboard). The second parameter specifies how many posts are retrieved. 

The first line of the example below demonstrates how the function returns a sequence. The sequence is saved in a variable and looped through. Any blog post variables should use the name of the individual loop item rather than content.. In the example, rec_post.name is used. This technique can be used, not only on blog templates, but also regular pages. 

The blog_recent_tag_posts function returns a sequence of blog post objects for a specified tag or tags, sorted by most recent first. This sequence of posts can be saved into a variable and iterated through with a for loop, creating a custom post listing of posts by a particular tag or tags.

The function takes three parameters. The first parameter specifies which blog to collect posts from. The value should be "default" or the blog ID of a particular blog (available in the URL of the Blog dashboard).

The second parameter specifies which tags to use, either a single tag or an array of up to 10 tags separated by commas. This parameter can use tag.slug for a particular tag from content.tag_list or accepts a lowercase hyphenated name such as "marketing-tips".  Spaces in tag names must be converted to hyphens.

The third parameter specifies how many posts are retrieved. 

The first line of the example below demonstrates how the function returns a sequence of posts by tag. The second line shows the function used to save a sequence in a variable which is then looped through. Any blog post variables should use the name of the individual loop item rather than content.. In the example, tag_post.name is used. This technique can be used, not only on blog templates, but also regular pages. 

You can use this function as the foundation for a related posts section of an individual blog post layout. To learn more about creating a related posts section, check out this tutorial.

The blog_tag_url function returns a full URL to the specified blog tag's listing page.

This function accepts two parameters. The first parameter specifies which blog the tag's listing page exists in. The second parameter specifies which tag to link. This parameter can use the topic.slug for a particular tag from content.topic_list or accepts a lowercase hyphenated name such as "marketing-tips".

The example below shows how this function can be used as an anchor's href.

The blog_tags function returns a sequence of the 250 most blogged-about tags (based on number of associated blog posts) for the specified blog, sorted by blog post count.

This sequence can be stored in a variable and iterated through to create custom tag post filters. The number of posts for each tag can be accessed with tag.live_posts. 

This function accepts two parameters. The first parameter specifies which blog to fetch tags from. The second parameter sets a limit on the number of tags fetched.

The first line of the example below demonstrates how the function returns a sequence of tag objects. The rest of the example demonstrates a use case of saving a sequence into a variable and then iterating though the tag objects, printing a set of author tag links. The example assumes that the blog has 4 tags. 

This function returns the total number of published posts in the specified blog. If no parameter is specified, it will count your default blog posts. Alternatively, you can specify "default" or a blog ID of a different blog to count. The blog ID is available in the URL of your blog dashboard for a particular blog.

Returns the number of times a variable exists in a list.

Gets a list of CRM records associated with another record by its record ID, association category, and association definition ID.

This function returns an object with the following attributes: has_more, total, offset and results.

• has_more indicates there are more results available beyond this batch (total > offset).
• total is the total number of results available.
• offset is the offset to use for the next batch of results.
• results returns an array of the specified associated objects matching the function's parameters

Gets a single CRM record by query or by its ID. Records are returned as a dict of properties and values.

This function can also be used with custom and integrator objects.

Gets a list of records for a specific object type from the HubSpot CRM.

This function returns an object with the following attributes: has_more, total, offset and results.

• has_more indicates there are more results available beyond this batch (total > offset).
• total is the total number of results available.
• offset is the offset to use for the next batch of results.
• results returns an array of the specified objects matching the function's parameters.

Get the property definition for a given object type and property name.

Supported object types are HubSpot standard objects (e.g., contacts), portal specific objects, and integrator objects.

Get the property definitions for a given object type and set of  property names.

Supported object types are HubSpot standard objects (e.g. contacts), portal specific objects, and integrator objects.

Because CTA modules have so many parameters that contain variations of their code, you can use the CTA function to easily generate a particular CTA in a template, page, or email. This function is what the rich text editor uses when you add a CTA via the editor.

Extend a list by appending all items from an iterable. In other words, insert all list items from one list into another list.

This function returns the metadata of a file by ID. It accepts a single parameter, the numeric ID of the file to look up.

Returns the social media account links set in account settings. Used in the default follow_me module. 

Formats an address based on the context's locale. 

Formats a company's name by adding Japanese honorifics where appropriate.

Formats both the date and time components of a date object, similar to the format_datetime HubL filter. This function replaces the deprecated datetimeformat function.

This function contains 4 parameters and calculates the ellipsoidal 2D distance between two points on Earth. Use this function as a filter query for getting HubDB data.

This function returns the public URL of a specified template or code file. The parameter of this function is the asset's path in the design manager. Coded file URLs update each time you publish them; therefore, by using this function your ensure you are always using the latest version of the file. 

You can automatically generate this function in the app, by either right-clicking a file and selecting Copy public URL, or by clicking Actions, then selecting Copy public URL. 

The example below gets the URL of a Javascript file authored in Design Manager that can be included as the src of a <script> tag.

This function works just like get_public_template_url, returning public URL of a specified template or code file. The only difference is the parameter of this function is the template ID (available in the URL of the template or coded file), instead of the design manager path.

HubDB is a feature available in CMS Hub Professional and Enterprise.

The hubdb_table function can be used to get information on a table including its name, columns, last updated, etc. 

The following pieces of information can be pulled by calling the appropriate attributes:

• ID: the ID of the table.
• name: the name of the table.
• columns: a list of column information.
• created_at: the timestamp of when this table was first created.
• published_at:  the timestamp of when this table was published.
• updated_at: timestamp of when this table was last updated.
• row_count: the number of rows in the table.

HubDB is a feature available in CMS Hub Professional and Enterprise.

The hubdb_table_column function can be used to get information on a column in table such as its label, type and options. This function accepts two parameters. 

These pieces of information about the column can be pulled by calling the appropriate attributes:

• ID: the ID of the column.
• name: the name of the column.
• label: the label to be used for the column.
• type: the type of the column.
• options: for columns of type select, a map of optionId to option information.
• foreignIds: for columns of type "foreignId", a list of foreignIds (with id and name properties).

In addition to the above attributes, there is also a method which can be called: getOptionByName("<option name>") whereby for columns of type "select", this will get option information by the option's name.

HubDB is a feature available in CMS Hub Professional and Enterprise.

The hubdb_table_row function can be used to pull a single row from a HubDB table. From this row, you can pull information from each table cell by calling on the corresponding attribute: 

• hs_id: the globally unique id for this row.
• hs_created_at: a timestamp representing when this row was created.
• hs_path: when used with dynamic pages, this string is the last segment of the url's path for the page.
• hs_name: when used with dynamic pages, this is the title of the page.
• <column name> or ["<column name>"]: get the value of the column for this row by the name of the column.

HubDB is a feature available in CMS Hub Professional and Enterprise.

The hubdb_table_rows function can be used to list rows of a HubDB table, to be iterated through. A single call of hubdb_table_rows() is limited to 10 table scans per page.

By default, this function will return a maximum of 1,000 rows. To retrieve more rows, specify a limit in the query, as shown in the code below.

This function generates a link tag that references the Primary CSS file (default_custom_style.min.css). This file is designed to be a global CSS file that can be added to all templates. To render, the function requires a boolean parameter value of True.

Returns the location of the first matching item in a 0-based array.

This function accepts 3 parameters, The first parameter is required. The first parameter is the item you are trying to find in the array. The second (start) and third (end) enable you to find that item in a slice of the array. 

Places an element into a list at the specific index provided.

This function accepts two parameters:

• Index: the position where an element is to be inserted.
• Element: the item to be inserted.

Returns a human-readable string representation of a language code, optionally translated to a target language.

Returns the nested link structure of an advanced menu. Menu nodes have a variety of properties that can be used on objects that are returned. If you pass null to the menu function it will return an empty pylist. You can also specify a menu by name. In most cases it's safer to use the menu id, as a menu being renamed won't affect the id. If building for the marketplace it makes sense to default to "default" if menu is null.

Gets the URL for an asset attached to a custom module via Linked Files > Other Files.

This function enqueues a CSS file to be rendered in the head element. All CSS link tags are grouped together and render before any JavaScript tags. The HubL is replaced with an empty line and then a link tag is added to {{ standard_header_includes }}. This method requires an absolute URL; CMS content with a known relative URL can be required by using the get_asset_url() function.

To enqueue an inline style to be rendered in the head via a style tag element, use the {% require_css %} and {% end_require_css %} tag instead with your style tags and CSS inside of that.

The second parameter is a dictionary of options to modify generated tag. Supports async (true/false) a technique described on web.dev and any other key-value pair will be added as HTML attributes to the style tag.

Specifies whether a script should be enqueued to render in the head or footer (default). Specify the render location by including the head or footer parameter. The HubL will be replaced by an empty line, and included in either the header or footer includes. 

To enqueue an inline script to be rendered in the footer via a script element, wrap your <script> tags with {% require_js %} and {% end_require_js %}. 

You can also include additional render options in this function. These will be added as HTML attributes in the script tag. Render options include:

• position: head/footer
• defer: true/false
• async: true/false
• type: string

Rewrites the URL of image stored in File Manager to a URL that will resize the image on request. The function accepts one required parameter, and five optional parameters. At least one optional parameter must be passed.

Required

• URL: string, URL of a HubSpot-hosted image.

Optional

• width: number, the new image width in pixels.
• height: number, the new image height in pixels.
• length: number, the new length of the largest side, in pixels.
• upscale: boolean, use the resized image dimensions even if they would scale up the original image (images may appear blurry).
• upsize: boolean, return the resized image even if it is larger than the original in bytes.

Reverses the order of items in a list. Doesn't take any parameters. To reverse an object or return an iterator to iterate over the list in reverse, use |reverse

Set the response code as the specified code. 404 is the only supported code for now. When using this, your page will return a 404 error.

Returns the start of today (12:00am). Optionally you can add a parameter to change the timezone from the default UTC.

Converts a UNIX timestamp to the local time, based on your HubSpot Report Settings. You can then apply a datetimeformat filter to format the date.

Returns a HubL dict representing the topic cluster associated with a piece of content (determined by the passed content id), including metadata about the associated pillar page, core topic, and subtopics. Can be used to "auto-link" a piece of content with its associated pillar page [if it exists].

Available metadata can be found in: attachableContent (the current content's metadata), topic (the current content's associated topic metadata), coreTopic (the associated cluster's core topic metadata), and pillarPage (the associated pillar page's metadata).

Use {{ topicCluster|pprint }} to see a full a display of available properties/attributes.

The truncate function works just like the truncate filter, but uses function syntax instead of filter syntax. The first parameter specifies the string. The second parameter specifies the length at which to truncate. The final parameter specifies the characters to add when the truncation occurs.