Groove Commerce
Learn tips and tricks for building customized templates on the HubSpot COS from Groove - a HubSpot Platinum Certified Agency Partner.

HubSpot revamped their version of a standard CMS in 2013 in what they named their Content Optimization System, or “COS” for short. With the COS, users of the software have the ability to create entire websites, blogs, landing pages and emails that are mobile-optimized out-of-box and integrate with HubSpot’s full suite of inbound marketing tools.

While HubSpot offers a ton of great pre-built templates for these content channels on the COS, along with a basic Template Builder tool (no coding required), they also allow you to build your own templates using HubSpot Markup Language (HubL) within a Code Editor option for those users and developers looking to add more advanced customizations and features.

In this blog, I’m going to provide a high-level overview and some general tips for building customized templates on the HubSpot COS while primarily using the Code Editor tool. Enjoy!


Accessing HubSpot's Design Manager

You can access HubSpot's Design Manager (where you can build templates) by logging into your HubSpot account and then navigating to Content > Design Manager within the top navigation bar, as shown below:

HubSpot COS Blog 1

Setting Up Your Templates

To get started, you’ll want to select "New Template" on the Design Manager page, as shown below:

HubSpot COS Blog 2

Next, a small lightbox will pop up and you will have the ability to select the type of HubSpot template to create. For this blog, I’ll be using the Code Editor option primarily.

HubSpot COS Blog 3

A quick trick that saves time (so that you’re not coding completely from scratch) is to create a basic layout using the Template Builder, then clone the template to a new file by selecting Actions > Clone to File. This will output an html file with all of the required HubL code included. It can, however, become messy if you're not careful, so it is up to you whether or not you want to go this path vs. coding from scratch.

HubSpot COS Blog 4

I personally prefer to build out the template with the Template Builder first, however it is entirely possible to write up completely unique html as long as you include the appropriate module tags and the two standard header and footer tokens:

Include this in your header:

Include this in your footer:

Adding Tokens & Tags

What are tokens and tags, you ask? According to the HubL Syntax Reference Doc: “Templates contain tokens and tags. Tokens are indicated by a curl brace syntax: [Developer's Toolbox] A Guide to Building Customized Templates on the HubSpot COS and are replaced with values when the template is processed. Tags control the logic of the template and provide support for various components.

Certain tokens can only work in certain content types. For example, if you were to use an email token such as inside of a landing page template, the template may not work. HubSpot does break these down by template type, as shown below:

HubSpot COS Blog 5Click here to view all HubL supported variables

Adding Modules

Modules allow dynamic, user-defined content to be loaded into templates. There are 20 standard modules that you can choose from, but it is possible to create and use your own modules from scratch.

Note that “modules” and “widgets” are the same thing. You will occasionally see HubSpot use these terms interchangeably.

Your standard module syntax looks like:

    • module_type – this is the type of module you are using, for example: rich_text, or image
    • “a_unique_name” – each module must have a unique name. If two modules have duplicate names, only one will show up
    • label – this is the text that the end-user will see in the template's module editor
    • attribute & value – any additional parameters based on the module type that you are using. For example, an image module requires an “src” attribute to be defined

Again, HubSpot gives you a full breakdown of module types, as shown below:

HubSpot COS Blog 6

Click here to view all HubL supported modules

Two Important Module Parameters to Keep in Mind

There are two extremely useful parameters that you should keep in mind when developing your templates.

#1: export_to_template_context=True

Including “export_to_template_content=True” will allow you to export data from the module into your template by using the syntax:

Modules with “export_to_template_context=True” defined will not automatically display output in the template. For example, let’s say that you had an image module named “groove_image” set up in the front-end template module editor, like shown below:

HubSpot COS Blog 7

If you wanted to grab the alt text in the template, the token you would write is:

This would print out “this is the ALT text”.

If you want to grab the link URL, you would write:

And so forth.

Adding “export_to_template_context” becomes incredibly helpful once you start building templates with more customization options. You can see the available parameters for each module if you go to the HubL Supported Modules Documentation.

For more useful tips using “export_to_template_context”, see my section below labeled Providing Options in the Template's Module Editor.

#2: no_wrapper=True

I don't want to dive into full details here as this one's pretty simple but it's worth mentioning nonetheless -- by default, Hubspot wraps all module content in either a div or span tag. Depending on your specific template needs, you may want to disable this by including “no_wrapper=True” in your module.

Making the Most of Your Grid Layout

Hubspot makes use of a 12-column grid system based on Bootstrap 2 (Bootstrap 3 is the most recent version).

When working with the html file, you can stick to this framework or include and create your own. Like I mentioned above, you can write up completely unique html as long as you include the appropriate modules and tokens.

HubSpot COS Blog 8

This page shows you the full code output for a sample template.


So now you know how to edit the layout of your templates! Using coded files over the Template Builder allows you to exhibit greater control over the design and function of your templates.

But what if you want to offer more customization options for a user who doesn’t know a lot about html and would need to make template adjustments directly within the front-end template module editor, like shown below:

HubSpot COS Blog 9

The following two tricks will improve your life!

Taking Advantage of the Choice Module and Conditional Logic

These tricks will let you create options such as selecting specific stylings, or displaying entire blocks of content. For convenience purposes, I've marked the important code elements in pink.

Now, there are two parts to this customization: setting up the “choice” module, and then wrapping it together with if-statements, otherwise referred to as conditional logic.

Let’s say that we want to create an optional section of a template, something that will only display if the user explictly sets it to display.

Step 1: Setting Up the Choice Module

The first step makes use of the “choice” module. This module will offer the end-user with a pre-determined list of values.

The HubL module tag will look like this:

I am assigning this block the name “optional_content_block” and the choices are “No,Yes”.

It is imperitive that you include “export_to_template_context=True” or else you will be unable to reference any of the module’s data within the template.

It's also worth noting that it is not necessary to include the <span> tags in the label, but I feel as though it helps distinguish this option on the module editor screen.

You can create as many choices as you like. These will populate as a dropdown list. I've set "No" first so that this module will default to "No" (that is, it won't randomly display things it shouldn’t).

It will render on the template module editor as:

HubSpot COS Blog 10

Step 2: Using Conditional Logic to Wrap it Together

Hubspot offers tags for conditional logic. The syntax is very straightforward. This snippet from the COS Documentation gives a colorful example of its usage:

Conditional Logic - HubSpot

We will make use of this tag to toggle different conditions. The option that you select in the Code Editor is saved and its value can be called in the template with the token:


Please note how this token follows the same convention as defined above:

You can then set up conditionals for the module with the following code:

<div style="display:none;">

Now, this section will only display if the end-user selects and saves “Yes.”

So, with a little creativity, you can set this up for a number of uses. For example, the following defines different css styles based on your choice:

Setting User-Defined Background Images

Sometimes, you might be asked to create a template that requires the ability to swap out background images as necessary. You could do some CSS magic with absolute positioning and z-indexes... and that definitely works, but the simplest way is to add “export_to_template_context=True” to an image module. There are two ways to go about this:

Step 1: Add an Image Module

Add an image module anywhere in the template. I would put it near the top of the layout, but it’s ultimately up to you.

Step 2: Set up CSS

Set up your CSS and put the proper token where applicable.

body { background:url(''); }

And voila! You’ve now created helpful options for non-technical users to adjust your templates directly within HubSpot’s front-end template module editor -- #SelfFive.



While this is not meant to be a complete technical guide that covers every single detail of building customized templates on the HubSpot COS, hopefully this gives you a high-level overview and answers some of your general questions.

Need help with anything HubSpot or inbound-related? Don’t hesitate to drop us a line at Groove and we’d be happy to chat!