HubSpot Gurus Tech Talk

The Basics of Custom Modules

Custom modules are one of HubSpot most powerful CMS features. It's a self-contained element in HubSpot, and can be used on a page just like the built-in HubSpot modules. But, it’s custom built to display exactly that data you want (or make it flexible and display a wider range of data you think it should.) The good news is, that the Custom Module is flexible enough to do both. And it has self-contained style sheet and javascript support elements to ensure that any custom code and style will transport easily to different pages, themes, or web sites.

This walkthrough will cover creating a custom module through the HubSpot design manager, and not the CLI option.

Create a New Module
01. New Custom Module

Creating a new module is in the same New File command in the Design Manager screen. In the New File dialog, select the Module from the new file popup. When creating a new module, you must select the areas of HubSpot you intend to use in the module. 02. Module PagesThis filters the modules so you only see the Modules designed for the area being modified. And if you are building a module for use in Emails, some elements (like the CSS and JavaScript features) will be unavailable. Also, you will be choosing if the module is intended to be used locally only or as a global module. A global module will be locked and any instances of the module will use the default data you specify when building it. Keep in mind you can still use a local module in a global content area and be able to select the content for the global instance of the content element.

Basic Module Features

Your module consists of two major sections. The left panel has the HTML, CSS and JavaScript for your module. This is responsible for the HTML and support resources that will be displayed for the user. The module.html panel is where you will put the HTML code responsible for displaying your module on the page (or email, etc.) This panel will consist of both your static HTML and will also allow you to use any HubL variables (module specific elements, covered below, global HubL variables and, if building the module as a part of a theme, any theme variables.) The right panel has the admin elements you will use to configure your module. Here, you will name the module, add fields the page editor will have access to, and other behind the scenes settings.


Module admin elements

03. Base Module FeaturesThe area to the right of the window has the administrative elements of your module.

Module Name
The top section is where you name the module The file name is the actual name of the module in the HubSpot file area. If you change the name, you may need to update instances of the module used in your templates. The label is what a page editor will see when selecting the modules for the page. This may be changed anytime and not damage any module paths in templates. Clicking the icon will also allow you to change the icon the page editors will see. You may browse from hundreds of icons HubSpot has included, or upload your own SVG file. This can be useful to more easily find your module at a glance when it's in a list of all of the other modules.

Module Fields
The fields section is probably the most used area of your module. Fields are data elements you are giving the page editor to change when they add your module to a page. HubSpot now has dozens of different field elements available for you, each with their own unique features and elements. I’ll cover a few of the most common/useful ones.

03.1.-Image-Module-FeaturesA few elements that are common to all fields.

  • Name: the label the page editor sees when entering content into your module. This should be as descriptive as possible, but it is just a label.
  • HubL variable name: the HubL variable you will use to refer to this object in your module.html area. This will not be seen by the page editor, and must be unique to your module. It will be defaulted based on your field’s name, but can be changed. Keep in mind if this changes, any references to the name in your module will also need to be updated.

Content Options will have the content fields unique to the field type available for data. Most of these are related to the default values you want populated in the module when a new instance is created. However, there are some additional fields that aren’t directly displayed but allow you to manage the options the page editor has when using the module. This will range from the default values you may want to pre-populate in your module, to image controls, to restrictions placed on the page editor when entering data into your field.

Editor Options will allow you to put some limits on and give page editors some additional information when they are dealing with a specific module field.

  • 03.2.-Field-Editor-OptionsMake this field required will require a page editor to have a value for this field.
  • Prevent editing in content editors will lock this field for the page editors; your default value will be used.
  • Tooltip help text will be a popup next to the field’s label for the page editor.
  • Inline help text will appear below the field’s label for the page editor.

Display Conditions will allow you to hide this field from page editors based on other field values in the module. For instance, if you want a text field and its label to be hidden from the page editor if they haven't entered a value in another field, the conditions will allow you to manage that restriction.

Repeater Conditions allow you to specify that the field should have multiple instances in the module. We will cover this in a separate blog post in the future.

Common Field Types

  • Rich Text: The standard HubSpot rich text editor. Gives the page editor the full WYSIWYG toolset including fonts/styles/colors, links, images, etc.
  • Text: A single line of text. Useful if you want to give a user a header field or hyperlink text and not allow them access to style it in the rich text editor.
  • Link: A variable that will contain a link to something. You are able to restrict the page editor to specific types of links (internal pages, external links, files, etc.)
  • Image: An image in the HubSpot file library.
  • Icon: A FontAwesome icon; sometimes it can be easier for a page editor to pick an icon rather than an image.
  • CTA: Select a HubSpot call to action.
  • Form: Select a HubSpot form. Also allows the page editor to override the thank you message or page.
  • Blog: Select a blog in your HubSpot instance.
  • HubDB table and HubDB row: Select a HubDB table or a specific row in a HubDB table.
  • Boolean/Choice: Give a page editor a boolean checkbox or a limited set of options. The can be directly output to the screen, but are usually used to manage other fields in your module.

Each field has an actions menu for quick access to some key field elements. The two most critical elements are the copy features.

03.3.-Field-PopupThe Copy Snippet will put the HubSpot default HubL code to display this field on your clipboard. You may then paste this code into the module.html area to display the field. This is the best way to display some elements, such as the Rich Text, Fields and Image field types, as it will create default code for some of the field’s critical elements if the object is a complex HubL dictionary (has sub-elements under the parent variable.) Sometimes, the HubL code will have multiple lines with it to ensure all of the field elements are covered (such as image sizing or adding support code for the link element if an email option is specified. But, this default HubL code can be modified at your discretion.

The Copy Value Only will only grab the variable name for the clipboard. With most elements, it’s not enough to display this (if the field consists of a HubL dictionary with multiple sub-elements.) But, you can output the field variable to see all of it’s dictionary elements (especially when using the pprint “pretty print” filter on the variable. Or, you can use the variable name in any HubL logic code you have (

Receive HS Gurus Updates via Email

  • Recent
  • Popular

Recent Posts

Popular Posts

Recent Posts