Stay up to date with weekly industry insights

the latest trends in web design, inbound marketing, mobile strategy and more...

In Beta: HubSpot's Related Posts Tag Explained and Extended

In Beta: HubSpot's Related Posts Tag Explained and Extended

When reading a blog post, such as this one, often times you will see suggestions for other blogs that are available to read and related to the article. In the past, building this type of functionality inside of HubSpot often meant using a highly complex custom module.

Now, thanks to the folks over at HubSpot (special shout out to Steven McKinless and Victoria Gumaer who are working on it), we have a beta tag called related_blog_posts that allows us to create a "Related Posts" section. This ensures that the articles generated is not the blog post people just read and checking to make sure it is, in fact, related to the current article.

Note: This tag is currently in development. This means the parameters of the tag and how it works is subject to change. If you plan on using this in a production environment, make sure you check in on it every now and then in case there are major changes to the functionality. 

So what kind of related posts can I pull?

Related posts can come from many sources. With HubSpot's new tag we have the ability to be granular in the type of related posts we want to pull in. These can be based on:

  • The current post being read
  • Tag/topic based
  • Author based
  • The published date (such as only showing blogs published after X date)
  • Similar path prefixes

These options allow us to create related posts quickly and use the fields in the Design Manager (DMv2) to give our content-entry users the ability to customize it. 

What does the Tag look like and what can it do?

At the time of writing this post, our new related posts tag can be used with the following minimal HubL Statement.

Note: replace XXXXXXXXXX with your blog ID number.

 {% related_blog_posts blog_ids="XXXXXXXXXXXXX" %} 

When using this statement at its bare minimum, as shown above, you'll get the following results:

Related Posts with minimal parameters

The HTML output is shown below for one of those entries. This structure, within the outermost span with the class of "hs_cos_wrapper", is used for each post that is output from the tag.


<span id="hs_cos_wrapper_module_5996263033_" class="hs_cos_wrapper hs_cos_wrapper_widget hs_cos_wrapper_type_related_blog_posts" style="" data-hs-cos-general-type="widget" data-hs-cos-type="related_blog_posts">
    <!--related-blog-entries-->
    <div class="hs-related-blog-module feedreader_box">
    
        <div class="hs-related-blog-item  hs-with-featured-image">
            <div class="hs-related-blog-item-text">
                <a class="hs-related-blog-title" href="https://blog.wsol.com/episerver-cms-best-blog-posts">
                    <span>
                        Top Five Best Episerver CMS Posts From Our Blog You May Have Missed
                    </span>
                </a>
                <div class="hs-related-blog-byline">
                    by
                    <span class="hs-related-blog-author">Doug Miller</span>
                    <span class="hs-related-blog-posted-at"> posted on </span>
                    <span class="hs-related-blog-date">June 6, 2017</span>
                </div>
                <div class="hs-related-blog-byline">
                    <p class="hs-related-blog-post-summary">
                        </p><p style="text-align: left;">If you have spent any time with anyone from our team at WSOL, you would figure out pretty quickly that we have a very deep bench when it comes to staff skilled in CMS platforms like Episerver and MAP platforms like HubSpot. As a result, our blog ends up being a great repository of information and contains posts from a variety of subject matter experts. But, who has time to dig through a who history of blog posts looking for useful information? We know you are busy, so we took the time to assemble some of the posts we think are super useful, just in case you missed them when they were originally&nbsp;published.</p>

                        <a href="https://blog.wsol.com/episerver-cms-best-blog-posts">Read more</a>
                    <p></p>
                </div>
                <div class="hs-related-blog-byline">
                    <span class="hs-related-blog-tags">
                        Tags: Episerver
                    </span>
                </div>
            </div><div class="hs-related-blog-item-image-wrapper">
                    <img class="hs-related-blog-featured-image" src="https://cdn2.hubspot.net/hubfs/213744/Blog_Images/pexels-photo-306534.jpg?t=1533056062168" alt="">
                </div></div>
    
    </div>

</span>

The rendered HTML is very similar to the output you get when using the RSS Tag or other blog feed tags/functions you can use in HubSpot.

What options are available to customize the related posts Tag?

We can output different related posts by adjusting and adding optional parameters to our related posts tag. Below is a list of the current options available. 

Note: At the time of writing this, HubSpot also officially updated their documentation to include this tag.

  • limit="" - This is the number of posts you want to have shown. The value entered must be a numerical value and if this parameter is left off, the default value of 3 will be applied. 

  • blog_ids="" - This parameter is a numerical value that corresponds to blogs hosted inside of your HubSpot portal. The id's listed here are where the blog posts will be pulled from. If you don't include this parameter, it will pull from all the blogs in your portal.

  • tags="" - This is a comma-separated list of tags (string value) that are used when determining the relevancy of the posts that are pulled. Posts that have tags that are matched to this parameter will have a higher relevance thus increasing its ranking for being pulled. If you don't include this, it will simply determine posts without taking the tags into account, as there is no default value for this parameter.

  • blog_authors="" - Another comma-separated list of authors names (string value) that you wish to pull blogs from. This works great if you are looking to create a section such as "Other posts from this author" instead of a related posts section. There is no default value for this field. 

  • blog_post_ids="" - Don't let the parameter name fool you, this is not to list out certain blog posts. This parameter should only be used on "Pages" and is a comma-separated list of blog post id's (string value) that this tag will use to find relevant posts to pull in onto the page. When this tag is used on blog posts, this is automatically set to the post in which the tag resides on. 

  • post_formatter="" - This parameter is string based and the value entered corresponds to the name of a custom macro that you can create to format the output of the related posts section. This essentially lets you create your own styling for the posts and should be used 99% of the time when you use this tag. The macro you specify here is passed three parameters from the tag:

    1. The blog post object data
    2. The index number (iteration number) of the post
    3. The amount (or limit) of posts

    If you don't use this parameter or set it to "default" then the post will be output using the built-in formatter of HubSpot. You can see this via the image and HTML output from above.

  • path_prefixes="" - Another string based comma-separated list that allows you get even more granular and choose URL paths or sub-directories in which to include posts from. If posts have a similar prefix in their paths, then they become more relevant and have a better chance of appearing in the data set returned.  

  • start_date="" - A date/time field that allows you to set posts to show that were published either on or after this date. If not set, then there will be no restriction on the starting date used when pulling your data set.

  • end_date="" A date/time field that allows you to set posts to show that were published either on or before this date. If not set, then there will be no restriction on the starting date used when pulling your data set.

  • blog_post_override="" - A string-based field of the blog post ID's that will always be shown regardless of the parameters above. This is a perfect use case for when you want to push one post as a "featured" post of sorts in your data set. 

What are some examples of how we can use the related posts Tag? 

Now we could always create a custom module, pop the tag in there and be on our way. But what about creating a reusable version of this tag that is more dynamic and allows us to create a robust module that gives our content creators more flexibility in choosing what to show? Let's take a look at some examples of how we can make this happen. 

Note: for the examples below, we will be using our blog id 2718545028, make sure to switch this out with your ID when using this code. Need to find your blog ID? When looking on your blog dashboard in your portal, it's the second set of numbers in the URL. Here is the breakdown of that URL:

https://app.hubspot.com/blog/(portal_id)/blogs/(blog_id)/manage/posts/all 

You can also find this number in your blogs source code appended as a class to the body which looks like hs-blog-id-(blog_id)

Creating a related posts module on a blog post by pulling in the posts tags automagically

Let's say we want related posts to show for our posts, but our posts always have different topics. If you are a business with many different services or offerings, chances are your blogging is not tied down to one thing only. You could build using the functionality that HubSpot already has and used some custom variables to accomplish this. For example, we could take a posts current tag(s) values and group them into the tag so we never have to directly specify what post tags are being used to show the relevant posts. Granted, on its own (if we are on a blog post) the blog_post_ids parameter should auto-populate and pull relevant blogs in for us. However, using the tags parameter would allow us to take one more step in making sure that posts under the same tag grouping also get pulled in.

To begin, we're going to look under the "Developer Info" to find what we need to grab. For those not familiar with this area, I highly recommend reading over it here in HubSpot's Designer Documentation. Go ahead and find a currently published blog post on your site and click the sprocket menu then go to Developer Info. 

Once here, this will show you a list of all the properties that HubSpot provides values for in which you can pull through HubL code. The data we are concerned with falls under the content > tag_names property.

Developer Info JSON output for content > tag_names

If you are using the browser plugin that HubSpot recommends in their article, you will see some information listed across the bottom when you hover over the tag_names property. This is a clue to how our HubL statement is going to end up looking. By using these properties, we can assign them to a variable and place that variable into the tag as shown below.


{#	Assign our content.tag_names array to a variable	#}
{% set tagNames = content.tag_names %}
{#	Add this to the function and use HubSpot's JOIN filter to turn the array into a comma separated string	#}
{% related_blog_posts blog_ids="2718545028" limit="3", tags="{{tagNames|join(',')}}" %}

This essentially is pulling the tags from the current blog post and populating the tag parameter automatically. This means we don't have to rely on manual entry of this parameter.

Create a related posts module showing additional articles by the current author

On most blog sites, in addition to related posts on an article, you may also see additional posts by the author. We can accomplish this by using our developer info area yet again to grab the current post author name and placing it into the tag. When looking at our developer info we can see a property called meta_author:

meta-author-json

because this property returns a string value, we are able to simply place it directly into the tag without needing to assign it to a variable first.


{% related_blog_posts blog_ids="2718545028" limit="3", blog_authors="{{meta_author}}" %}

Create a related posts module showing posts that were only published last year to present

Often times when showing related articles, we want the reader to see newer relevant articles that are being published instead of a related article from 5 years ago. We can do this by utilizing the start_date parameter along with the {{year}} HubL snippet. 


{# using {{year - 1}} will take the current year and subtract one from it #}
{% related_blog_posts blog_ids="2718545028" limit="3", start_date="{{year - 1}}-01-01" %}

Create a sidebar bullet point listing of related blog titles

Now let's take a look at how we can create a basic sidebar listing of just blog titles. Now by default (and referring to the output HTML at the beginning of this post) HubSpot's built in formatter will pull in the following items:

  • Blog Title
  • Author Name
  • Published Date
  • Partial Content from the post
  • Tags
  • Featured Image

but in this example, we are not looking for all that information to be pulled in. Here, we'll pretend we are a business and we have a simple press release section which doesn't require us to have all those finer details like featured images, tags, and authors.

Using the post_formatter parameter we can choose how the output of our listing will look.

First, we begin by creating our macro that will output our results


{% macro blog_post_formatter(blog_post) %}
    <li><h4><a href="{{blog_post.url}}">{{blog_post.name}}</a></h4></li>
{% endmacro %}

Next, we'll add a call to this macro inside of our related posts tag:


<ul>
	{% related_blog_posts blog_ids="2718545028" limit="3", start_date="{{year - 1}}-01-01", post_formatter="blog_post_formatter"  %} 
</ul>

When we put this all together, we get a finished module with the following code:


{% macro blog_post_formatter(blog_post) %}
    <li><h4><a href="{{blog_post.url}}">{{blog_post.name}}</a></h4></li>
{% endmacro %}

<ul>
	{% related_blog_posts blog_ids="2718545028" limit="3", start_date="{{year - 1}}-01-01", post_formatter="blog_post_formatter"  %} 
</ul>

Create a related posts section where one post is hand selected to show

Let's say we have a scenario where a recent blog post was published and it's the bee knees. A post that is so good, we want to always push this out to people and show them the post. For this scenario, we can make use of the blog_post_override parameter. First, we will have to grab the post ID from the awesome post we created, you can get this by going to your post editor page and checking the URL like we did before when looking for blog id's (as an example, we'll use the ID of this post 6009713892):

https://app.hubspot.com/blog/(portal_id)/edit-beta/(post_id)/content

From here, we can then plug this into our function as so:


{% related_blog_posts blog_ids="2718545028" limit="3", start_date="{{year - 1}}-01-01", blog_post_override="6009713892"  %} 

This should now give us an output where one post is the post we have defined by ID and the other two are pulled in by the tag and its additional parameters.

Where can I go from here?

As you can see, this new tag gives us a plethora of possibilities when building a related posts section. Likewise, we can also add some automation into this function to relieve any manual input of parameters. If you add this to a new custom module in the new Design Manager Version 2, you will also be able to make use of all the new fields to create a truly customized module that can be modified on a post by post basis (or even a page by page). As we've stated before, this is a tag that is still in Beta so there will definitely be more enhancements being added in as time goes on. Just make sure to check in on the documentation from time to time to see if there were any updates.

Have questions? Let us know in the comments below or you can also join the HubSpot Developer Slack Group where there is a channel dedicated to this function called #related-posts-module.

About the Author

AJ LaPorte
AJ LaPorte
As a HubSpot Designer/Developer, AJ works on creating pixel-perfect visual designs of interface elements and responsive HTML prototyping, from templates to style guides and more. When not working, you can find him searching his way across the interwebs, looking for the next big trends in design, marketing, and development. AJ is also an avid video gamer and enjoys listening to country music, acoustic music, Grateful Dead, and the occasional Sinatra.